1 2 3 4 5 6 7 8 9 10 11
12 13 14
15 package xdc.bld;
16
17 /*!
18 * ======== BuildEnvironment ========
19 * Global build environment
20 *
21 * This module defines a global object (aliased as '`Build`' in build scripts)
22 * which is configured by a build "startup" script and read by package build
23 * scripts.
24 *
25 * This module's configuration parameters are initialized by
26 * a "startup" script that is run prior to running a package's build
27 * script (`package.bld`). This script (often named "`config.bld`") is
28 * responsible for specifying the the `{@link xdc.bld.ITarget#rootDir}`
29 * configuration parameter of all targets that appear in the
30 * `{@link #targets}` array; the `rootDir` configuration parameter specifies
31 * the absolute path to the installation directory of the compiler used to
32 * build for the specified target. Typically one startup script is used to
33 * establish an environment for multiple packages.
34 *
35 * Note: it does not matter if you do not have tools for all the targets
36 * mentioned in the startup script; if you do not build for a target,
37 * its setting in the startup script is irrelevant.
38 *
39 * The startup script may configure this module as a function of the
40 * following global variables that exist before this script runs:
41 * @p(dlist)
42 * - `environment`
43 * a hash table of environment strings
44 * - `arguments`
45 * an array of string arguments to the `config.bld` script
46 * initialized as follows:
47 * `arguments[0]` - the file name of the `config.bld` script;
48 * `arguments[1]` - the first argument specified in `XDCARGS`;
49 * ...;
50 * `arguments[n]` - the nth argument in `XDCARGS`.
51 * - `Build`
52 * an alias for this module (`xdc.bld.BuildEnvironment`)
53 * The following parameters of this object are initialized
54 * before the startup script runs:
55 * `hostOS` - `{@link #HostOS}` enumeration identifier;
56 * `hostOSName` - "Windows", "Linux", "MacOS" or "Solaris"
57 * - `Pkg`
58 * an alias for this module (`xdc.bld.PackageContents`)
59 * The following parameters of this object are initialized
60 * before the startup script runs:
61 * `{@link PackageContents#name}` - the name of the current
62 * package;
63 * `{@link PackageContents#modules}` - array of module names
64 * supplied by this package; and
65 * `{@link PackageContents#interfaces}` - array of interface
66 * names supplied by this package
67 * @p
68 * When you build a package, the `xdc` command looks for the startup file
69 * using the following algorithm:
70 * @p(nlist)
71 * - if `XDCBUILDCFG` is defined on the `xdc` command line, its value is
72 * used;
73 * - if `config.bld` exists in the current directory, this file is used;
74 * - if `XDCBUILDCFG` is defined as an environment variable, its value
75 * is used;
76 * - if `config.bld` exists along the package path (i.e. in `$XDCPATH`
77 * followed by the current package's repository), the first such
78 * file is used;
79 * - if `$XDCROOT/config.bld` exists this file is used;
80 * - if `$XDCROOT/etc/config.bld` exists, this file is used; and
81 * finally
82 * - if no "startup file" can be found above, a fatal error is
83 * reported and the `xdc` command terminates with a non-zero exit
84 * status.
85 */
86 metaonly module BuildEnvironment {
87
88 /*!
89 * ======== HostOS ========
90 * An enumeration of all supported development hosts
91 *
92 * @see #hostOS
93 */
94 enum HostOS {
95 WINDOWS, /*! Win32 Intel development host */
96 SOLARIS, /*! SUN OS 5.x development host */
97 LINUX, /*! Linux development host */
98 MACOS /*! MacOS development host */
99 };
100
101 /*!
102 * ======== hostOS ========
103 * Enumerated constant that identifies the host OS that is executing
104 * the build script
105 *
106 * Note that host OS at the time the makefiles are created may be
107 * different from the host OS at the time sources are compiled!
108 */
109 readonly config HostOS hostOS;
110
111 /*!
112 * ======== hostOSName ========
113 * The name of the development host
114 *
115 * One of the strings: "Windows", "Solaris", "Linux", "MacOS". This name is
116 * name of the host OS that is executing the package's build script.
117 */
118 readonly config String hostOSName;
119
120 /*!
121 * ======== useTargets ========
122 * The set of targets to use if the `{@link #targets}` array
123 * is empty
124 *
125 * `useTargets` is a string of white space separated target names
126 * (i.e., names of modules that implement `{@link xdc.bld.ITarget}`) or
127 * regular expression patterns matching target names.
128 *
129 * If the `Build.{@link #targets}` array is empty at the end of the
130 * build model's configuration script, targets specified by this string
131 * are added to the build model's `{@link #targets}` array.
132 *
133 * In addition to module names, the distinguished string
134 * `"native"` is interpreted as an alias for the target
135 * specified by the `{@link #nativeTarget}` configuration
136 * parameter.
137 *
138 * Special values:
139 * @p(dlist)
140 * -`undefined`
141 * use the environment variable `XDCTARGETS`;
142 * -`null`
143 * initialize the `{@link #targets}` array to be empty; and
144 * -`""`
145 * use all TI targets (i.e., "`ti.targets\..*`").
146 *
147 * @see #excludeTargets
148 * @see #nativeTarget
149 */
150 config String useTargets;
151
152 /*!
153 * ======== excludeTargets ========
154 * A set of targets to exclude from the set specified by
155 * `{@link #useTargets}`
156 *
157 * This string parameter is a single regular expression used to exclude
158 * targets from the set specified by `useTargets` (or `XDCTARGETS`).
159 *
160 * If `{@link #targets}` is initialized by the build model's
161 * configuration script (i.e., has length > 0) this parameter is
162 * ignored.
163 *
164 * If this string is `null` or `undefined`, nothing is excluded from
165 * list specified by `{@link #useTargets}` or the environment variable
166 * `XDCTARGETS`.
167 *
168 * @see #useTargets
169 * @see #nativeTarget
170 */
171 config String excludeTargets;
172
173 /*!
174 * ======== targets ========
175 * Array of all targets that are supported for the current build
176 *
177 * This array may be explicitly initialized by the build model's
178 * initial configuration script (by default, "`config.bld`"). For
179 * example, the following fragment specifies that just the
180 * `ti.targets.C64` target should be used:
181 * @p(code)
182 * // get the ti.targets.C64 module
183 * var C64 = xdc.module('ti.targets.C64');
184 *
185 * // add the ti.target.C64 module to BuildEnvironment.targets array
186 * Build.targets[Build.targets.length++] = C64;
187 * @p
188 * Alternatively, this array can be implicitly initialized via the
189 * `XDCTARGETS` environment variable or the `{@link #useTargets}`
190 * and `{@link #excludeTargets}` strings. The `{@link #targets}` array
191 * is implicitly initialized if and only if the length of this array is
192 * 0 after the build model's configuration script completes.
193 *
194 * All targets that are in this array *must* have their
195 * `{@link xdc.bld.ITarget#rootDir}` property set.
196 *
197 * @see #excludeTargets
198 * @see #useTargets
199 */
200 config ITarget.Module targets[];
201
202 /*!
203 * ======== nativeTarget ========
204 * A target that defines the "native" target
205 *
206 * This parameter allows build scripts to refer to the "native"
207 * target without explicitly naming the target.
208 *
209 * For example, a `package.bld` script may add a library via:
210 * @p(code)
211 * Pkg.addLibrary("lib", Build.nativeTarget);
212 * @p
213 * In addition, it is possible to use `"native"` in `XDCTARGETS` or
214 * `{@link #useTargets}` to specify that
215 * `{@link #nativeTarget}` be added to the `{@link #targets}` array.
216 * Thus, it is possible to use the following command on *any* host to
217 * build for that host:
218 * @p(code)
219 * xdc XDCTARGETS=native
220 * @p
221 *
222 * If this parameter is not set by the build model's configuration
223 * script, it is initialized to an appropriate default native target:
224 * @p(blist)
225 * - `{@link microsoft.targets.Win32}` for Windows hosts;
226 * - `{@link gnu.targets.Sparc}` for Solaris hosts; and
227 * - `{@link gnu.targets.Linux86}` for Linux hosts.
228 * @p
229 */
230 config ITarget.Module nativeTarget = null;
231
232 /*!
233 * ======== platformTable ========
234 * A map of platform instance names to the parameters used to
235 * create them
236 *
237 * This map allows one to define platform instances that require
238 * non-default parameter settings. It also provides a way to
239 * publish a set of platforms to be shared among multiple build
240 * scripts.
241 *
242 * @a(EXAMPLES)
243 * The following fragment defines a platform instance named
244 * `"ti.platforms.sim6xxx:big"` that corresponds to a platform instance
245 * created by the `ti.platforms.sim6xxx.Platform` module with the
246 * parameters `{endian: "big"}`:
247 * @p(code)
248 * Build.platformTable["ti.platforms.sim6xxx:big"] = {endian: "big"};
249 * @p
250 *
251 * The following fragment redefines the default platform instance for
252 * the platform package `ti.platforms.sim6xxx` by specifying alternative
253 * instance creation parameters.
254 * @p(code)
255 * Build.platformTable["ti.platforms.sim6xxx"] = {
256 * endian: "little", verbose: false, ftpath: "c:/ftsuite_1_5",
257 * };
258 * @p
259 * Some platforms are "software abastractions" that can emulate a large
260 * number different physical platforms. In the example below, the
261 * `ti.platforms.sim6xxx` platform package is capable of simulating
262 * any TMS320C6xxx device. This particular platform package uses the
263 * name of the instance to determine the specific device that it should
264 * emulate. So, the fragment below specifies a platform instance named
265 * `"ti.platforms.sim6xxx:TMS320C6416"` that emulates the `TMS320C6416`
266 * device, in little endian mode.
267 * @p(code)
268 * Build.platformTable["ti.platforms.sim6xxx:TMS320C6416"] = {
269 * endian: "little"
270 * };
271 * @p
272 * Software platform packages, such as the `ti.platforms.generic`, can
273 * even go as far as emulating any device from any "catalog" of
274 * devices. In this example, we use the `ti.platforms.generic`
275 * platform package to define an instance named
276 * `ti.platforms.generic:c6416` that corresponds to a platform
277 * containing the TMS320C6416 device specified in the `ti.catalog.c6000`
278 * package of devices.
279 * @p(code)
280 * Build.platformTable["ti.platforms.generic:c6416"] = {
281 * deviceName: "TMS320C6416",
282 * catalogName: "ti.catalog.c6000",
283 * };
284 * @p
285 * @see ti.catalog.c6000
286 * @see ti.platforms.generic
287 * @see ti.platforms.sim6xxx
288 */
289 config any platformTable[string] = [];
290
291 /*!
292 * ======== platforms ========
293 * Cache of all platform objects added via `{@link #usePlatform}`
294 * @_nodoc
295 */
296 config any platforms[string];
297
298 /*!
299 * ======== usePlatform ========
300 * @_nodoc
301 *
302 * Instantiate the specified platform
303 *
304 * The parameter `name` must contain the qualified name of a platform
305 * package, and may also contain a platform instance name separated from
306 * the package name by a ':'. Therefore, accepted names include both
307 * "joes.platform.foo" and "joes.platform.foo:bar", where the first name
308 * creates an unnamed instance of the platform `joes.platform.foo`, while
309 * the second name creates an instance named `bar` of the same platform.
310 *
311 * @param(name) name of platform to create
312 *
313 * @a(returns)
314 * `usePlatform()` returns the platform instance object
315 * (`xdc.platform.IPlatform.Instance`) specified by `name`.
316 *
317 * @a(throws)
318 * `XDCException` exceptions are thrown for fatal errors. The following
319 * error codes are reported in the exception message:
320 * @p(dlist)
321 * - `xdc.bld.PARAMETER_MISMATCH`
322 * This error is reported whenever parameters with the wrong type
323 * are passed to the method. Ensure that the parameters passed have
324 * the right type.
325 */
326 function usePlatform(name);
327
328 /*!
329 * ======== isInTargetsArray ========
330 * Test whether a target is in of the `targets` array
331 *
332 * @_nodoc
333 *
334 * @param(target) `xdc.bld.ITarget` target object to test
335 */
336 Bool isInTargetsArray(ITarget.Module target);
337
338 /*!
339 * ======== printBuildTargets ========
340 * @_nodoc
341 */
342 String printBuildTargets();
343
344 /*!
345 * ======== onInit ========
346 * @_nodoc this function is called from the `xdc.bld` package's
347 * initialization function to initialize this module.
348 */
349 function onInit();
350
351 /*!
352 * ======== getReleaseDescs ========
353 * Return a description of all releases for the specified package
354 *
355 * This function allows a "package of packages" to select appropriate
356 * releases from another package based on information provided by that
357 * package.
358 *
359 * @param(pname) name of the package to get the release
360 * information from
361 *
362 * @a(returns) array of `{@link xdc.bld.Release#Desc}`
363 * structures that describe the releases specified
364 * by `pname`'s build script
365 *
366 * @a(throws) `XDCException` exceptions are thrown for fatal
367 * errors. The following error codes are
368 * reported in the exception message:
369 * @p(dlist)
370 * - `xdc.bld.PACKAGE_NOT_BUILT`
371 * This error is reported when a consumer tries to
372 * use a package that has not been built. Ensure that
373 * the required package has been built by `XDCtools`.
374 * - `xdc.bld.INVALID_PACKAGE`
375 * This error is reported when a consumer tries to
376 * use a corrupted package. Try rebuilding the
377 * package causing the problem.
378 *
379 * @see xdc.bld.Release#Desc
380 */
381 Release.DescArray getReleaseDescs(String pname);
382
383 /*!
384 * ======== initializeModel ========
385 * @_nodoc
386 * Initialize the build model
387 *
388 * @param(args) - an array of arguments whose first element is
389 * the path to a config.bld script and subsequent
390 * arguments are the argument (usually) specified
391 * by `XDCARGS`.
392 */
393 function initializeModel(args);
394 }
395 396 397
398