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