1 2 3 4 5 6 7 8 9 10 11
12
13 14 15
16 package xdc.bld;
17
18 /*!
19 * ======== Executable ========
20 * Model of a file that can be loaded and executed on a platform.
21 *
22 * Executable instances represent executable files. Instances must be
23 * created via the `{@link xdc.bld.PackageContents#addExecutable()}`
24 * function; this ensures that each executable created appears in the
25 * package's manifest and that it properly "inherits" appropriate default
26 * attributes from the containing package.
27 */
28 metaonly module Executable {
29
30 /*!
31 * ======== Attrs ========
32 * Optional attributes for an Executable instance.
33 *
34 * Unspecified attributes are "inherited" from
35 * `{@link xdc.bld.PackageContents#attrs}`;
36 * i.e., if one of fields in this structure is unspecified *and* this
37 * field's name matches a field name in
38 * `{@link xdc.bld.PackageContents#attrs}`, then this field's value
39 * defaults to the value in specified by
40 * `{@link xdc.bld.PackageContents#attrs}`. This mechanism makes it
41 * possible to establish package-wide default values for any of the
42 * "inherited" attributes.
43 *
44 * Suppose, for example, that you want all executable files in this
45 * package to be built with the 'release' profile, but one particular file
46 * must be built with 'debug' (because it is a source example). The
47 * following build script fragment shows how this can be accomplished:
48 * @p(code)
49 * Pkg.attrs.profile = 'release';
50 * var exe = Pkg.addExecutable('example', ..., {profile: 'debug'});
51 * @p
52 * @field(cfgArgs) This string may contain any expression that can be
53 * assigned to a JavaScript property. It is evaluated in
54 * the configuration domain after the platform package is
55 * imported and just prior to running the executable's
56 * configuration script. Its value (after evaluation) is
57 * assigned to `Program.build.cfgArgs`; so, program
58 * configuration scripts can use this property to adjust their
59 * behavior based on values specified in a build script.
60 *
61 * For example, a package's build script might build an
62 * executable for each possible level of a "trace" value:
63 * @p(code)
64 * for (t = 0; t < NUM_TRACE_LEVELS; t++) {
65 * :
66 * Pkg.addExecutable("myExe" + t, targ, plat, {
67 * cfgArgs: "{traceLevel: " + t + "}",
68 * cfgScript: "myExe.cfg"
69 * });
70 * }
71 * @p
72 *
73 * In this case, the configuration script `myExe.cfg` can
74 * reference the "trace level" set in the build script by
75 * referencing the `Program.build.cfgArgs` object directly:
76 * @p(code)
77 * if (Program.build.cfgArgs.traceLevel == 1) {
78 * :
79 * }
80 * @p
81 *
82 * @field(cfgArgsEncoded) This boolean flag indicates whether the
83 * string `cfgArgs` should be treated as an encoded string (via ECMA-262
84 * `escape()`) or not. If this field is `true`, the string is treated
85 * as an encoded string and is decoded via `unescape()` prior to
86 * interpretation.
87 *
88 * @field(incs) This string contains include path options used by
89 * the compiler (or assembler) to locate include files; e.g.,
90 * "-I ../../include -I ../c55xx". Note that the syntax of
91 * this string may be target dependent.
92 *
93 * @field(defs) This string contains options used by the
94 * compiler (or assembler) to define macros; e.g.,
95 * "-D_C6xxx -DDEBUG=1". Note that the syntax of
96 * this string may be target dependent.
97 *
98 * @field(aopts) This string contains options used by the assembler
99 * to produce object files; e.g., "-mP1". Note that the syntax
100 * of this string may be target dependent.
101 *
102 * @field(copts) This string contains options used by the C/C++
103 * compiler to produce object files; e.g., "-o3 -mi1". Note
104 * that the syntax of this string may be target dependent.
105 *
106 * @field(cfgcopts) This string contains options used by the C/C++
107 * compiler to compile the generated C config file. If `cfgcopts`
108 * is not specified, either explicitly or through
109 * `Pkg.attrs.cfgcopts`, the options specified in `copts` are
110 * used instead.
111 *
112 * @field(lopts) This string contains options used by the linker
113 * produce object files; e.g., "-l mylib.lib". Note
114 * that the syntax of this string may be target dependent.
115 *
116 * @field(xsopts) This string contains options passed to the
117 * `{@link http://rtsc.eclipse.org/docs-tip/Command_-_xs xs}`
118 * command that's used to run configuration scripts. This option
119 * can be used, for example, to define name-value pairs accessible
120 * to configuration scripts via the XDCscript global
121 * `environment` hash-table. For example, setting `xsopts` to
122 * `"-DFOO=bar"` enables the configuration script to get the
123 * value of `FOO` via the expression `environment["FOO"]`. For
124 * more information about XDCscript and `environment` see
125 * {@link http://rtsc.eclipse.org/docs-tip/The_XDCscript_Language The XDCscript Language}.
126 *
127 * @field(cfgHome) This string names the package that is bound to
128 * the Configuration Model's `$homepkg`. This home package
129 * is automatically loaded as part of configuration and, as
130 * a result, may contribute libraries to the configuration.
131 *
132 * If this parameter is not specified, the package containing
133 * the configuration script is used as the home package. This
134 * ensures that the results of a configuration script are
135 * independent of the package building the configuration. In
136 * most cases, the build package is the package containing the
137 * configuration script and this distinction is not important.
138 * But there are times when it is important to control the home
139 * package; e.g., when an external tool generates a
140 * configuration script from information supplied by another
141 * package or when a configuration script in not in any package.
142 *
143 * @field(cfgScript) This string names the program configuration
144 * script used to create the files necessary to create the
145 * executable. If `cfgScript` is not specified, the configuration
146 * script is assumed to be `<name>.cfg`, where `<name>` is the
147 * base name of the executable. If `cfgScript` is set to `null`,
148 * the executable is assumed to be a "legacy" application that
149 * defines `main()` directly and does not require any
150 * `{@link xdc.runtime}` support.
151 *
152 * If this string is set to a non-`null` value, and does not have
153 * an extension, then the extension `".cfg"` is automatically
154 * added.
155 *
156 * If the specified configuration file does not exist in the
157 * package where the executable is being built and
158 * the name does not begin with `"./"`, it is searched
159 * for along the package path. Thus, it is possible to use
160 * configuration scripts in other packages to build executables;
161 * e.g., to use the configuration script "myExe.cfg" from a
162 * `ti.bios.examples.hello` package, `cfgScript` should be set
163 * to `"ti/bios/examples/hello/myExe.cfg"`.
164 *
165 * The package containing the specified configuration script is
166 * imported prior to running the configuration script and this
167 * package is used to set `xdc.$homepkg`; thus, configuration
168 * scripts that use `xdc.$homepkg` will configure the same
169 * executable independent of the package building the executable.
170 *
171 * @field(profile) This string names a profile defined by the
172 * executable's target. The profile specifies a set of compiler,
173 * linker, and archiver options that are to be used when
174 * producing the executable. Note that these tool options are
175 * in addition to any options specified via `aopts`, `copts`,
176 * etc.
177 *
178 * If this field is not set or set to `null`, the value of
179 * `{@link xdc.bld.PackageContents#attrs.profile}` is used. If
180 * `{@link xdc.bld.PackageContents#attrs.profile}` is not
181 * specified or equal to `null`, the `"release"` profile is used.
182 *
183 * @field(cpuId) This string is used to uniquely identify the
184 * particular CPU on a platform that will run the executable; on
185 * platforms that contain a single CPU, this string is ignored.
186 *
187 * @field(rtsName) This string names a package that contributes a
188 * compiled form of the `{@link xdc.runtime}` runtime support
189 * modules.
190 *
191 * This package is implicitly loaded prior to running the
192 * executable's configuration script. If this field is set to
193 * `null`, no package will be pre-loaded. If this field is not
194 * set (or set to `undefined`), the package specified by this
195 * executable's target will be used (see
196 * {@link xdc.bld.ITarget#rts}) .
197 *
198 * @field(cpuArgs) This field is a hash-table of name-value pairs
199 * interpreted by the CPU as register settings that exist at the
200 * time that the executable is loaded; e.g., it is possible to
201 * specify a non-reset value for the `PMST` register on a C54xx
202 * CPU by setting this parameter to `{PMST: 0xffff}`.
203 *
204 * @field(exportCfg) If this field is set to true, the configuration
205 * script will be part of the releases named in the releases
206 * array. If it is unspecified (or set to `null`) and the
207 * release specifies that configurations are to be exported,
208 * the configuration script will be part of the release. In
209 * all other cases, the configuration is not part of the
210 * release.
211 *
212 * @field(exportSrc) If this field is set to true, the sources
213 * specified via `{@link xdc.bld.Executable#addObjects()}`
214 * will be part of the releases named in the releases
215 * array. If it is unspecified (or set to `null`) and the
216 * release specifies that sources are to be exported,
217 * the sources will be part of the release. In
218 * all other cases, the sources are not added to the
219 * release.
220 *
221 * @field(exportExe) If this field is set to true, the executable
222 * will be part of the releases named in the releases
223 * array. If it is unspecified (or set to `null`) and the
224 * release specifies that configurations are to be exported,
225 * the executable will be part of the release. In
226 * all other cases, the executable is not part of the
227 * release.
228 *
229 * @field(releases) This array contains releases that will contain the
230 * executable. Thus, a single executable can be part of any set
231 * of releases. Each executable is always added to the
232 * package's "default release" in addition to any releases
233 * specified in the releases array.
234 *
235 * @field(test) If this field is set, it defines default attributes for
236 * tests added to this executable, including the implicitly
237 * added test (see {@link xdc.bld.PackageContents#addExecutable}).
238 *
239 * @field(linkTemplate) If this field is set, it defines the linker
240 * command file template to be used to link this executable.
241 * This specification may, however, be overridden by the
242 * configuration script (see
243 * {@link xdc.cfg.Program#linkTemplate}).
244 *
245 * As with configuration scripts, if the specified file does not
246 * exist in the package where the executable is being built and
247 * the name does not begin with `"./"`, it is searched for along
248 * the package path. Thus, it is possible to use templates in
249 * other packages to build executables; e.g., to use the linker
250 * command file "`myExe.cmd`" from the `ti.bios.examples.hello`
251 * package, `linkTemplate` should be set to
252 * `"ti/bios/examples/hello/myExe.cmd"`.
253 *
254 * @see #attrs
255 * @see xdc.bld.PackageContents#Attrs
256 */
257 struct Attrs {
258 String profile; /*! target options profile */
259 String aopts; /*! asm options for objs added to this exe */
260 String copts; /*! C/C++ options for objs added to this exe */
261 String cfgcopts; /*! C/C++ options for the C config file */
262 String defs; /*! definitions for objs added to this exe */
263 String incs; /*! include opts for objs added to this exe */
264 String lopts; /*! linker options for this exe */
265 String xsopts; /*! `xs` options for this exe */
266 String cpuId; /*! optional id of CPU on platform */
267 String rtsName; /*! optional run time support package name */
268 any cpuArgs; /*! optional register settings */
269 String sharedCfg;
270 String cfgScript; /*! optional name of config script */
271 String cfgHome; /*! optional home package of config model */
272 String cfgArgs; /*! optional arguments passed to cfgScript */
273 Bool cfgArgsEncoded; /*! if true, cfgArgs is encoded via escape() */
274 Bool exportExe; /*! export executable's exe file? */
275 Bool exportCfg; /*! export executable's config script? */
276 Bool exportSrc; /*! if true, export exe sources to releases */
277 Release.Instance releases[]; /*! releases that this exe is a part of */
278 Test.Attrs test; /*! test attrs for tests added to this exe */
279 String linkTemplate; /*! linker command file template for this exe*/
280 };
281
282 instance:
283 /*!
284 * ======== create ========
285 * @_nodoc
286 * Instances should only be created via PackageContents.addExecutable()
287 */
288 create();
289
290 /*!
291 * ======== name ========
292 * Base name of the executable.
293 *
294 * This name is used to construct the final executable file name as
295 * follows:
296 * @p(code)
297 * <name>.x<target_suffix>
298 * @p
299 * where `<name>` is name and `<target_suffix>` is the suffix defined
300 * by each target that the file is built for. See NOTE in
301 * `{@link xdc.bld}` for filename rules.
302 *
303 * Note: if the same executable is to be built for different platforms
304 * (having the same target), then name must "encode" the platform's
305 * name.
306 */
307 config String name;
308
309 /*!
310 * ======== platform ========
311 * The name of the platform that will run this executable.
312 *
313 * Platforms are modeled as packages that have a module called
314 * "Platform"; thus the platform name is really a package name.
315 */
316 config String platform;
317
318 /*!
319 * ======== target ========
320 * The target (on a platform) that executable should be built for.
321 *
322 * This parameter is used to determine the target to use for any
323 * objects added to the executable.
324 *
325 * During configuration, the executable's platform package can
326 * validate that the target is compatible with the configuration of
327 * the platform; the target object is accessible via the expression
328 * `Program.build.target`.
329 */
330 config ITarget.Module target;
331
332 /*!
333 * ======== attrs ========
334 * This executable's optional attributes.
335 *
336 * These attributes are "inherited" by all objects added to this
337 * executable; i.e., any object attribute that is undefined but is
338 * defined here will be assigned the value from these attributes.
339 *
340 * Similarly, any unspecified attributes that also appear in
341 * `{@link xdc.bld.PackageContents#Attrs}` are inherited from
342 * `{@link xdc.bld.PackageContents#attrs}`.
343 *
344 * @see xdc.bld.PackageContents#Attrs
345 */
346 config Executable.Attrs attrs;
347
348 /*!
349 * ======== addObjects ========
350 * Add specified object to be built and linked into this executable.
351 *
352 * All objects added to the executable are built with the symbol
353 * `xdc_cfg__header__` defined to be the name of the executable-specific
354 * C header generated by the program configuration tool. This symbol
355 * is used by the `xdc/cfg/global.h` header to include the generated
356 * header file; see `{@link xdc.cfg.Program#global}`. Thus, it is
357 * possible to portably include configuration specific definitions in a
358 * source file that is used in many different configurations.
359 *
360 * For example, a portable `main.c` might be structured as follows:
361 * @p(code)
362 * #include <xdc/std.h>
363 * #include <ti/bios/include/log.h>
364 *
365 * #include <xdc/cfg/global.h> // include declaration of trace
366 *
367 * int main(int argc, char *argv[])
368 * {
369 * LOG_printf(trace, "hello world");
370 * :
371 * }
372 * @p
373 *
374 * @a(Examples)
375 *
376 * 1. Locate a source file whose name starts with "hello" with
377 * an extension supported by the executable's target, compile it
378 * and link it into the executable `myExe`:
379 * @p(code)
380 * myExe.addObjects(["hello"]);
381 * @p
382 * If hello.c exists, compile and add to `myExe`, if hello.asm exists
383 * assemble and add to `myExe`, etc. If no such file is located,
384 * a warning is emitted.
385 *
386 * 2. Compile hello.c and add to the executable `myExe`:
387 * @p(code)
388 * myExe.addObjects(["hello.c"]);
389 * @p
390 * 3. Names may include sub-directory prefixes. In this case, the
391 * source will be located in a sub-directory of the current
392 * package. The following statement declares that the file
393 * "`foo/hello.c`" should be compiled and linked into the executable
394 * `myExe`:
395 * @p(code)
396 * myExe.addObjects(["foo/hello.c"]);
397 * @p
398 * As in the previous examples, the extension ".c" is optional.
399 * In case an extension is not supplied, each extension
400 * understood by the target will be tried until a source file
401 * is located.
402 *
403 * 4. It is also possible to supply file specific compilation
404 * options.
405 * @p(code)
406 * myExe.addObjects(["fir.c", "iir.c"], {defs: "-D_DEBUG"});
407 * @p
408 * In this case, both files fir.c and iir.c will be compiled
409 * with the "`-D_DEBUG`" flag. Any setting of `attrs.defs` in the
410 * executable or package is overridden by this definition.
411 *
412 * @param(names) array of base names of the sources of object files
413 * to be created and linked into the executable.
414 * See NOTE in `{@link xdc.bld}` for filename rules.
415 * @param(objAttrs) optional `{@link xdc.bld.Object#Attrs}` for the
416 * array of objects added; all objects named by names
417 * will be given the attributes `objAttrs`.
418 * @a(returns) `void`
419 *
420 * @a(throws) `Error` exceptions are thrown for fatal errors
421 *
422 * @see xdc.cfg.Program#global
423 */
424 Void addObjects(String names[], Object.Attrs objAttrs = {});
425
426 /*!
427 * ======== addTest ========
428 * Add specified test to executable.
429 *
430 * A test encapsulates an executable and a set of arguments passed to
431 * the executable when it is run.
432 *
433 * Tests are run by naming the goal "`<test_name>.test`" on the xdc
434 * command line; `<test_name>` is the test's name.
435 *
436 * Multiple tests may have the same name; in this case, it is possible
437 * to run all tests using the single goal "`<test_name>.test`"
438 *
439 * @param(testAttrs) test attrs object (`{@link xdc.bld.Test#Attrs}`)
440 *
441 * @a(returns) the `{@link xdc.bld.Test}` instance object created
442 *
443 * @a(throws) `Error` exceptions are thrown for fatal errors
444 */
445 Test.Instance addTest(Test.Attrs testAttrs);
446 }
447 448 449
450