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", 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 };
99
100 /*!
101 * ======== hostOS ========
102 * Enumerated constant that identifies the host OS that is executing
103 * the build script
104 *
105 * Note that host OS at the time the makefiles are created may be
106 * different from the host OS at the time sources are compiled!
107 */
108 readonly config HostOS hostOS;
109
110 /*!
111 * ======== hostOSName ========
112 * The name of the development host
113 *
114 * One of the strings: "Windows", "Solaris", "Linux". This name is
115 * name of the host OS that is executing the package's build script.
116 */
117 readonly config String hostOSName;
118
119 /*!
120 * ======== useTargets ========
121 * The set of targets to use if the `{@link #targets}` array
122 * is empty
123 *
124 * `useTargets` is a string of white space separated target names
125 * (i.e., names of modules that implement `{@link xdc.bld.ITarget}`) or
126 * regular expression patterns matching target names.
127 *
128 * If the `Build.{@link #targets}` array is empty at the end of the
129 * build model's configuration script, targets specified by this string
130 * are added to the build model's `{@link #targets}` array.
131 *
132 * In addition to module names, the distinguished string
133 * `"native"` is interpreted as an alias for the target
134 * specified by the `{@link #nativeTarget}` configuration
135 * parameter.
136 *
137 * Special values:
138 * @p(dlist)
139 * -`undefined`
140 * use the environment variable `XDCTARGETS`;
141 * -`null`
142 * initialize the `{@link #targets}` array to be empty; and
143 * -`""`
144 * use all TI targets (i.e., "`ti.targets\..*`").
145 *
146 * @see #excludeTargets
147 * @see #nativeTarget
148 */
149 config String useTargets;
150
151 /*!
152 * ======== excludeTargets ========
153 * A set of targets to exclude from the set specified by
154 * `{@link #useTargets}`
155 *
156 * This string parameter is a single regular expression used to exclude
157 * targets from the set specified by `useTargets` (or `XDCTARGETS`).
158 *
159 * If `{@link #targets}` is initialized by the build model's
160 * configuration script (i.e., has length > 0) this parameter is
161 * ignored.
162 *
163 * If this string is `null` or `undefined`, nothing is excluded from
164 * list specified by `{@link #useTargets}` or the environment variable
165 * `XDCTARGETS`.
166 *
167 * @see #useTargets
168 * @see #nativeTarget
169 */
170 config String excludeTargets;
171
172 /*!
173 * ======== targets ========
174 * Array of all targets that are supported for the current build
175 *
176 * This array may be explicitly initialized by the build model's
177 * initial configuration script (by default, "`config.bld`"). For
178 * example, the following fragment specifies that just the
179 * `ti.targets.C64` target should be used:
180 * @p(code)
181 * // get the ti.targets.C64 module
182 * var C64 = xdc.module('ti.targets.C64');
183 *
184 * // add the ti.target.C64 module to BuildEnvironment.targets array
185 * Build.targets[Build.targets.length++] = C64;
186 * @p
187 * Alternatively, this array can be implicitly initialized via the
188 * `XDCTARGETS` environment variable or the `{@link #useTargets}`
189 * and `{@link #excludeTargets}` strings. The `{@link #targets}` array
190 * is implicitly initialized if and only if the length of this array is
191 * 0 after the build model's configuration script completes.
192 *
193 * All targets that are in this array *must* have their
194 * `{@link xdc.bld.ITarget#rootDir}` property set.
195 *
196 * @see #excludeTargets
197 * @see #useTargets
198 */
199 config ITarget.Module targets[];
200
201 /*!
202 * ======== nativeTarget ========
203 * A target that defines the "native" target
204 *
205 * This parameter allows build scripts to refer to the "native"
206 * target without explicitly naming the target.
207 *
208 * For example, a `package.bld` script may add a library via:
209 * @p(code)
210 * Pkg.addLibrary("lib", Build.nativeTarget);
211 * @p
212 * In addition, it is possible to use `"native"` in `XDCTARGETS` or
213 * `{@link #useTargets}` to specify that
214 * `{@link #nativeTarget}` be added to the `{@link #targets}` array.
215 * Thus, it is possible to use the following command on *any* host to
216 * build for that host:
217 * @p(code)
218 * xdc XDCTARGETS=native
219 * @p
220 *
221 * If this parameter is not set by the build model's configuration
222 * script, it is initialized to an appropriate default native target:
223 * @p(blist)
224 * - `{@link microsoft.targets.Win32}` for Windows hosts;
225 * - `{@link gnu.targets.Sparc}` for Solaris hosts; and
226 * - `{@link gnu.targets.Linux86}` for Linux hosts.
227 * @p
228 */
229 config ITarget.Module nativeTarget = null;
230
231 /*!
232 * ======== platformTable ========
233 * A map of platform instance names to the parameters used to
234 * create them
235 *
236 * This map allows one to define platform instances that require
237 * non-default parameter settings. It also provides a way to
238 * publish a set of platforms to be shared among multiple build
239 * scripts.
240 *
241 * @a(EXAMPLES)
242 * The following fragment defines a platform instance named
243 * `"ti.platforms.sim6xxx:big"` that corresponds to a platform instance
244 * created by the `ti.platforms.sim6xxx.Platform` module with the
245 * parameters `{endian: "big"}`:
246 * @p(code)
247 * Build.platformTable["ti.platforms.sim6xxx:big"] = {endian: "big"};
248 * @p
249 *
250 * The following fragment redefines the default platform instance for
251 * the platform package `ti.platforms.sim6xxx` by specifying alternative
252 * instance creation parameters.
253 * @p(code)
254 * Build.platformTable["ti.platforms.sim6xxx"] = {
255 * endian: "little", verbose: false, ftpath: "c:/ftsuite_1_5",
256 * };
257 * @p
258 * Some platforms are "software abastractions" that can emulate a large
259 * number different physical platforms. In the example below, the
260 * `ti.platforms.sim6xxx` platform package is capable of simulating
261 * any TMS320C6xxx device. This particular platform package uses the
262 * name of the instance to determine the specific device that it should
263 * emulate. So, the fragment below specifies a platform instance named
264 * `"ti.platforms.sim6xxx:TMS320C6416"` that emulates the `TMS320C6416`
265 * device, in little endian mode.
266 * @p(code)
267 * Build.platformTable["ti.platforms.sim6xxx:TMS320C6416"] = {
268 * endian: "little"
269 * };
270 * @p
271 * Software platform packages, such as the `ti.platforms.generic`, can
272 * even go as far as emulating any device from any "catalog" of
273 * devices. In this example, we use the `ti.platforms.generic`
274 * platform package to define an instance named
275 * `ti.platforms.generic:c6416` that corresponds to a platform
276 * containing the TMS320C6416 device specified in the `ti.catalog.c6000`
277 * package of devices.
278 * @p(code)
279 * Build.platformTable["ti.platforms.generic:c6416"] = {
280 * deviceName: "TMS320C6416",
281 * catalogName: "ti.catalog.c6000",
282 * };
283 * @p
284 * @see ti.catalog.c6000
285 * @see ti.platforms.generic
286 * @see ti.platforms.sim6xxx
287 */
288 config any platformTable[string] = [];
289
290 /*!
291 * ======== platforms ========
292 * Cache of all platform objects added via `{@link #usePlatform}`
293 * @_nodoc
294 */
295 config any platforms[string];
296
297 /*!
298 * ======== usePlatform ========
299 * Instantiate the specified platform
300 *
301 * @_nodoc
302 *
303 * @param(name) name of platform to create
304 *
305 * @a(returns)
306 * `usePlatform()` returns the platform instance object
307 * (`xdc.platform.IPlatform.Instance`) specified by `name`.
308 *
309 * @a(throws)
310 * `XDCException` exceptions are thrown for fatal errors. The following
311 * error codes are reported in the exception message:
312 * @p(dlist)
313 * - `xdc.bld.PARAMETER_MISMATCH`
314 * This error is reported whenever parameters with the wrong type
315 * are passed to the method. Ensure that the parameters passed have
316 * the right type.
317 */
318 function usePlatform(name);
319
320 /*!
321 * ======== isInTargetsArray ========
322 * Test whether a target is in of the `targets` array
323 *
324 * @_nodoc
325 *
326 * @param(target) `xdc.bld.ITarget` target object to test
327 */
328 Bool isInTargetsArray(ITarget.Module target);
329
330 /*!
331 * ======== printBuildTargets ========
332 * @_nodoc
333 */
334 String printBuildTargets();
335
336 /*!
337 * ======== onInit ========
338 * @_nodoc this function is called from the `xdc.bld` package's
339 * initialization function to initialize this module.
340 */
341 function onInit();
342
343 /*!
344 * ======== getReleaseDescs ========
345 * Return a description of all releases for the specified package
346 *
347 * This function allows a "package of packages" to select appropriate
348 * releases from another package based on information provided by that
349 * package.
350 *
351 * @param(pname) name of the package to get the release
352 * information from
353 *
354 * @a(returns) array of `{@link xdc.bld.Release#Desc}`
355 * structures that describe the releases specified
356 * by `pname`'s build script
357 *
358 * @a(throws) `XDCException` exceptions are thrown for fatal
359 * errors. The following error codes are
360 * reported in the exception message:
361 * @p(dlist)
362 * - `xdc.bld.PACKAGE_NOT_BUILT`
363 * This error is reported when a consumer tries to
364 * use a package that has not been built. Ensure that
365 * the required package has been built by the `xdc`
366 * tool.
367 * - `xdc.bld.INVALID_PACKAGE`
368 * This error is reported when a consumer tries to
369 * use a corrupted package. Try rebuilding the
370 * package causing the problem.
371 *
372 * @see xdc.bld.Release#Desc
373 */
374 Release.DescArray getReleaseDescs(String pname);
375
376 /*!
377 * ======== initializeModel ========
378 * @_nodoc
379 * Initialize the build model
380 *
381 * @param(args) - an array of arguments whose first element is
382 * the path to a config.bld script and subsequent
383 * arguments are the argument (usually) specified
384 * by `XDCARGS`.
385 */
386 function initializeModel(args);
387 }
388 389 390
391