1    /* 
     2     *  Copyright (c) 2008 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    10     * 
    11     * */
    12    requires xdc.services.global;
    13    
    14    /*!
    15     *  ======== xdc.cfg ========
    16     *  Configuration Object Model elements
    17     *
    18     *  This package contains the modules necessary to populate the XDC
    19     *  Configuration Object Model.  In addition, this package supplies a
    20     *  C/C++ header, `global.h`, that facilitates the creation of portable
    21     *  sources that need to reference global values defined as part of
    22     *  a configuration (`{@link xdc.cfg.Program#global}`).
    23     *
    24     *  @a(Compatibility Checks)
    25     *  During configuration certain compatibility checks are made.  These checks
    26     *  include:
    27     *  @p(nlist)
    28     *    -   target compatibility among all packages that are included in the
    29     *        configuration
    30     *    -   package compatibility among all packages included in the
    31     *        configuration
    32     *    -   package compatibility with respect to the set of packages used to
    33     *        build the packages that are part of the configuration set.
    34     *  @p
    35     *  By default, if any of the checks above fail, the configuration step fails.
    36     *  It is possible, however, to selectively exclude particular
    37     *  packages from these checks and/or treat check failures as non-fatal
    38     *  warnings.
    39     *
    40     *  There are two "environment" variables that control these checks:
    41     *  @p(dlist)
    42     *    - `xdc.cfg.check.exclude`
    43     *        a regular expression that is used to select packages that should
    44     *        be excluded from the set of packages checked during configuration.
    45     *
    46     *    - `xdc.cfg.check.fatal`
    47     *        if set to "`false`", force any incompatibilities detected to be
    48     *        treated as warnings only; otherwise incompatibilities are fatal
    49     *  @p
    50     *  Of course, it is also possible to use both options together to achieve
    51     *  a desired effect.
    52     *
    53     *  To define these environment variables one must pass the appropriate `-D`
    54     *  options to the XDCscript shell (`xs`) which is used to run the
    55     *  `{@link xdc.tools.configuro configuro}` command line configuration tool.
    56     *  If, on the other hand, you are using `xdc` to run the configuration step
    57     *  you can set these variables by setting the
    58     *  `{@link xdc.bld.Executable#Attrs xsopts}` attribute of an
    59     *  `{@link xdc.bld.Executable}` within a build script.
    60     *
    61     *  @a(Controlling Compatibility Checks)
    62     *  To treat compatibility check failures as warnings for the executable
    63     *  `app`:
    64     *  @p(code)
    65     *    Pkg.addExecutable("app", targ, targ.platform, {
    66     *         xsopts: "-Dxdc.cfg.check.fatal=false"
    67     *    });
    68     *  @p
    69     *
    70     *  To ignore any incompatibilities triggered by targets used by the
    71     *  `ti.targets.rts*` packages:
    72     *  @p(code)
    73     *    Pkg.addExecutable("app", targ, targ.platform, {
    74     *        xsopts: "-Dxdc.cfg.check.exclude='ti.targets.rts.*'"
    75     *    });
    76     *  @p
    77     *  In this case, the `xdc.cfg.check.exclude` option is regular expression used
    78     *  to exclude any package whose names matches the regular expression from the
    79     *  checks.
    80     *
    81     *  Finally, if you don't want to set `xsopts` on each executable, it is
    82     *  possible to set it for all executables within a package by setting the
    83     *  `xsopts` attribute of the `{@link xdc.bld.PackageContents}` (a.k.a. `Pkg`)
    84     *  object.  For example, to turn all compatibility checks into warnings for
    85     *  all executables in a package, add the following line to the package's
    86     *  build script:
    87     *  @p(code)
    88     *    Pkg.attrs.xsopts = "-Dxdc.cfg.check.fatal=false";
    89     *  @p
    90     *
    91     *  @a(Throws)
    92     *  `XDCException` exceptions are thrown for fatal errors. The following error
    93     *  codes are reported in the exception message:
    94     *  @p(dlist)                            
    95     *      -  `xdc.cfg.CONFIG_ERROR`
    96     *           This is a general error reported when the program configuration
    97     *           fails. This error is caused by one or more configuration errors.
    98     *           The list of those specific errors precedes this error.
    99     *      -  `xdc.cfg.INCOMPATIBLE_TARGET_VERSION`
   100     *           This is an error or a warning usually reported when the version of 
   101     *           the compiler used in the current build is not compatible with the
   102     *           version of the compiler used to build some of the loaded packages.
   103     *           The compiler version might be encoded in the compatibility keys
   104     *           displayed in the error message, but it is not required. Please
   105     *           check the documentation of the current target's package for the
   106     *           content of the compatibility keys.
   107     *  @p
   108     *
   109     *  @see xdc.cfg.Program#global
   110     *  @see xdc.tools.configuro.Main
   111     */
   112    package xdc.cfg [1,0,2,0] {
   113        module Program, Main;
   114        module SourceDir;
   115    }
   116    /*
   117     *  @(#) xdc.cfg; 1, 0, 2, 0,386; 9-20-2012 15:01:54; /db/ztree/library/trees/xdc/xdc-y36x/src/packages/
   118     */
   119