1    /* --COPYRIGHT--,EPL
     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     * --/COPYRIGHT--*/
    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     *  @a(Throws)
    54     *  `XDCException` exceptions are thrown for fatal errors. The following error
    55     *  codes are reported in the exception message:
    56     *  @p(dlist)                            
    57     *      -  `xdc.cfg.CONFIG_ERROR`
    58     *           This is a general error reported when the program configuration
    59     *           fails. This error is caused by one or more configuration errors.
    60     *           The list of those specific errors preceds this error.
    61     *      -  `xdc.cfg.INCOMPATIBLE_TARGET_VERSION`
    62     *           This is an error or a warning usually reported when the version of 
    63     *           the compiler used in the current build is not compatible with the
    64     *           version of the compiler used to build some of the loaded packages.
    65     *           The compiler version might be encoded in the compatibility keys
    66     *           displayed in the error message, but it is not required. Please
    67     *           check the documentation of the current target's package for the
    68     *           content of the compatibility keys.
    69     *  @p
    70     *
    71     *  To define these environment variables one must pass the appropriate `-D`
    72     *  options to the XDCscript shell (`xs`); this is done by setting the
    73     *  `xsopts` attribute of an `{@link xdc.bld.Executable}` within a build
    74     *  script.
    75     *
    76     *  @a(Controlling Compatibility Checks)
    77     *  To treat compatibility check failures as warnings for the executable
    78     *  `app`:
    79     *  @p(code)
    80     *    Pkg.addExecutable("app", targ, targ.platform, {
    81     *         xsopts: "-Dxdc.cfg.check.fatal=false"
    82     *    });
    83     *  @p
    84     *
    85     *  To ignore any incompatibilities triggered by targets used by the
    86     *  `ti.targets.rts*` packages:
    87     *  @p(code)
    88     *    Pkg.addExecutable("app", targ, targ.platform, {
    89     *        xsopts: "-Dxdc.cfg.check.exclude='ti.targets.rts.*'"
    90     *    });
    91     *  @p
    92     *  In this case the `xdc.cfg.check.exclude` option is regular expression used
    93     *  to exclude any package whose names matches the regular expression from the
    94     *  checks.
    95     *
    96     *  Finally, if you don't want to set `xsopts` on each executable, it is
    97     *  possible to set it for all executables within a package by setting the
    98     *  `xsopts` attribute of the `{@link xdc.bld.PackageContents}` (a.k.a. `Pkg`)
    99     *  object.  For example, to turn all compatibility checks into warnings for
   100     *  all executables in a package, add the following line to the package's
   101     *  build script:
   102     *  @p(code)
   103     *    Pkg.attrs.xsopts = "-Dxdc.cfg.check.fatal=false";
   104     *  @p
   105     *
   106     *  @see xdc.cfg.Program#global
   107     *  @see xdc.tools.configuro.Main
   108     */
   109    package xdc.cfg [1,0,2,0] {
   110        module Program, Main;
   111    }
   112    /*
   113     *  @(#) xdc.cfg; 1, 0, 2, 0,214; 7-29-2009 14:53:00; /db/ztree/library/trees/xdc-t56x/src/packages/
   114     */
   115