1 2 3 4 5 6 7 8 9 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 }
115 116 117
118