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 `cfgopts`
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 `xs`
117 * when running configuration scripts; e.g., to turn on the
118 * reporting of warnings this string can be set to "-js -w",
119 * or to define the name-value pair "FOO=bar" available via
120 * the environment hash-table `xsopts` should be set to
121 * "-DFOO=bar".
122 *
123 * @field(cfgHome) This string names the package that is bound to
124 * the Configuration Model's `$homepkg`. This home package
125 * is automatically loaded as part of configuration and, as
126 * a result, may contribute libraries to the configuration.
127 *
128 * If this parameter is not specified, the package containing
129 * the configuration script is used as the home package. This
130 * ensures that the results of a configuration script are
131 * independent of the package building the configuration. In
132 * most cases, the build package is the package containing the
133 * configuration script and this distinction is not important.
134 * But there are times when it is important to control the home
135 * package; e.g., when an external tool generates a
136 * configuration script from information supplied by another
137 * package or when a configuration script in not in any package.
138 *
139 * @field(cfgScript) This string names the program configuration
140 * script used to create the files necessary to create the
141 * executable. If `cfgScript` is not specified, the configuration
142 * script is assumed to be `<name>.cfg`, where `<name>` is the
143 * base name of the executable. If `cfgScript` is set to `null`,
144 * the executable is assumed to be a "legacy" application that
145 * defines `main()` directly and does not require any
146 * `{@link xdc.runtime}` support.
147 *
148 * If this string is set to a non-`null` value, and does not have
149 * an extension, then the extension `".cfg"` is automatically
150 * added.
151 *
152 * If the specified configuration file does not exist in the
153 * package where the executable is being built and
154 * the name does not begin with `"./"`, it is searched
155 * for along the package path. Thus, it is possible to use
156 * configuration scripts in other packages to build executables;
157 * e.g., to use the configuration script "myExe.cfg" from a
158 * `ti.bios.examples.hello` package, `cfgScript` should be set
159 * to `"ti/bios/examples/hello/myExe.cfg"`.
160 *
161 * The package containing the specified configuration script is
162 * imported prior to running the configuration script and this
163 * package is used to set `xdc.$homepkg`; thus, configuration
164 * scripts that use `xdc.$homepkg` will configure the same
165 * executable independent of the package building the executable.
166 *
167 * @field(profile) This string names a profile defined by the
168 * executable's target. The profile specifies a set of compiler,
169 * linker, and archiver options that are to be used when
170 * producing the executable. Note that these tool options are
171 * in addition to any options specified via `aopts`, `copts`,
172 * etc.
173 *
174 * If this field is not set or set to `null`, the value of
175 * `{@link xdc.bld.PackageContents#attrs.profile}` is used. If
176 * `{@link xdc.bld.PackageContents#attrs.profile}` is not
177 * specified or equal to `null`, the `"release"` profile is used.
178 *
179 * @field(cpuId) This string is used to uniquely identify the
180 * particular CPU on a platform that will run the executable; on
181 * platforms that contain a single CPU, this string is ignored.
182 *
183 * @field(rtsName) This string names a package that contributes a
184 * compiled form of the `{@link xdc.runtime}` runtime support
185 * modules.
186 *
187 * This package is implicitly loaded prior to running the
188 * executable's configuration script. If this field is set to
189 * `null`, no package will be pre-loaded. If this field is not
190 * set (or set to `undefined`), the package specified by this
191 * executable's target will be used (see
192 * {@link xdc.bld.ITarget#rts}) .
193 *
194 * @field(cpuArgs) This field is a hash-table of name-value pairs
195 * interpreted by the CPU as register settings that exist at the
196 * time that the executable is loaded; e.g., it is possible to
197 * specify a non-reset value for the `PMST` register on a C54xx
198 * CPU by setting this parameter to `{PMST: 0xffff}`.
199 *
200 * @field(exportCfg) If this field is set to true, the configuration
201 * script will be part of the releases named in the releases
202 * array. If it is unspecified (or set to `null`) and the
203 * release specifies that configurations are to be exported,
204 * the configuration script will be part of the release. In
205 * all other cases, the configuration is not part of the
206 * release.
207 *
208 * @field(exportSrc) If this field is set to true, the sources
209 * specified via `{@link xdc.bld.Executable#addObjects()}`
210 * will be part of the releases named in the releases
211 * array. If it is unspecified (or set to `null`) and the
212 * release specifies that sources are to be exported,
213 * the sources will be part of the release. In
214 * all other cases, the sources are not added to the
215 * release.
216 *
217 * @field(exportExe) If this field is set to true, the executable
218 * will be part of the releases named in the releases
219 * array. If it is unspecified (or set to `null`) and the
220 * release specifies that configurations are to be exported,
221 * the executable will be part of the release. In
222 * all other cases, the executable is not part of the
223 * release.
224 *
225 * @field(releases) This array contains releases that will contain the
226 * executable. Thus, a single executable can be part of any set
227 * of releases. Each executable is always added to the
228 * package's "default release" in addition to any releases
229 * specified in the releases array.
230 *
231 * @field(test) If this field is set, it defines default attributes for
232 * tests added to this executable, including the implicitly
233 * added test (see {@link xdc.bld.PackageContents#addExecutable}).
234 *
235 * @field(linkTemplate) If this field is set, it defines the linker
236 * command file template to be used to link this executable.
237 * This specification may, however, be overridden by the
238 * configuration script (see
239 * {@link xdc.cfg.Program#linkTemplate}).
240 *
241 * As with configuration scripts, if the specified file does not
242 * exist in the package where the executable is being built and
243 * the name does not begin with `"./"`, it is searched for along
244 * the package path. Thus, it is possible to use templates in
245 * other packages to build executables; e.g., to use the linker
246 * command file "`myExe.cmd`" from the `ti.bios.examples.hello`
247 * package, `linkTemplate` should be set to
248 * `"ti/bios/examples/hello/myExe.cmd"`.
249 *
250 * @see #attrs
251 * @see xdc.bld.PackageContents#Attrs
252 */
253 struct Attrs {
254 String profile; /*! target options profile */
255 String aopts; /*! asm options for objs added to this exe */
256 String copts; /*! C/C++ options for objs added to this exe */
257 String cfgcopts; /*! C/C++ options for the C config file */
258 String defs; /*! definitions for objs added to this exe */
259 String incs; /*! include opts for objs added to this exe */
260 String lopts; /*! linker options for this exe */
261 String xsopts; /*! `xs` options for this exe */
262 String cpuId; /*! optional id of CPU on platform */
263 String rtsName; /*! optional run time support package name */
264 any cpuArgs; /*! optional register settings */
265 String sharedCfg;
266 String cfgScript; /*! optional name of config script */
267 String cfgHome; /*! optional home package of config model */
268 String cfgArgs; /*! optional arguments passed to cfgScript */
269 Bool cfgArgsEncoded; /*! if true, cfgArgs is encoded via escape() */
270 Bool exportExe; /*! export executable's exe file? */
271 Bool exportCfg; /*! export executable's config script? */
272 Bool exportSrc; /*! if true, export exe sources to releases */
273 Release.Instance releases[]; /*! releases that this exe is a part of */
274 Test.Attrs test; /*! test attrs for tests added to this exe */
275 String linkTemplate; /*! linker command file template for this exe*/
276 };
277
278 instance:
279 /*!
280 * ======== create ========
281 * @_nodoc
282 * Instances should only be created via PackageContents.addExecutable()
283 */
284 create();
285
286 /*!
287 * ======== name ========
288 * Base name of the executable.
289 *
290 * This name is used to construct the final executable file name as
291 * follows:
292 * @p(code)
293 * <name>.x<target_suffix>
294 * @p
295 * where `<name>` is name and `<target_suffix>` is the suffix defined
296 * by each target that the file is built for. See NOTE in
297 * `{@link xdc.bld}` for filename rules.
298 *
299 * Note: if the same executable is to be built for different platforms
300 * (having the same target), then name must "encode" the platform's
301 * name.
302 */
303 config String name;
304
305 /*!
306 * ======== platform ========
307 * The name of the platform that will run this executable.
308 *
309 * Platforms are modeled as packages that have a module called
310 * "Platform"; thus the platform name is really a package name.
311 */
312 config String platform;
313
314 /*!
315 * ======== target ========
316 * The target (on a platform) that executable should be built for.
317 *
318 * This parameter is used to determine the target to use for any
319 * objects added to the executable.
320 *
321 * During configuration, the executable's platform package can
322 * validate that the target is compatible with the configuration of
323 * the platform; the target object is accessible via the expression
324 * `Program.build.target`.
325 */
326 config ITarget.Module target;
327
328 /*!
329 * ======== attrs ========
330 * This executable's optional attributes.
331 *
332 * These attributes are "inherited" by all objects added to this
333 * executable; i.e., any object attribute that is undefined but is
334 * defined here will be assigned the value from these attributes.
335 *
336 * Similarly, any unspecified attributes that also appear in
337 * `{@link xdc.bld.PackageContents#Attrs}` are inherited from
338 * `{@link xdc.bld.PackageContents#attrs}`.
339 *
340 * @see xdc.bld.PackageContents#Attrs
341 */
342 config Executable.Attrs attrs;
343
344 /*!
345 * ======== addObjects ========
346 * Add specified object to be built and linked into this executable.
347 *
348 * All objects added to the executable are built with the symbol
349 * `xdc_cfg__header__` defined to be the name of the executable-specific
350 * C header generated by the program configuration tool. This symbol
351 * is used by the `xdc/cfg/global.h` header to include the generated
352 * header file; see `{@link xdc.cfg.Program#global}`. Thus, it is
353 * possible to portably include configuration specific definitions in a
354 * source file that is used in many different configurations.
355 *
356 * For example, a portable `main.c` might be structured as follows:
357 * @p(code)
358 * #include <xdc/std.h>
359 * #include <ti/bios/include/log.h>
360 *
361 * #include <xdc/cfg/global.h> // include declaration of trace
362 *
363 * int main(int argc, char *argv[])
364 * {
365 * LOG_printf(trace, "hello world");
366 * :
367 * }
368 * @p
369 *
370 * @a(Examples)
371 *
372 * 1. Locate a source file whose name starts with "hello" with
373 * an extension supported by the executable's target, compile it
374 * and link it into the executable `myExe`:
375 * @p(code)
376 * myExe.addObjects(["hello"]);
377 * @p
378 * If hello.c exists, compile and add to `myExe`, if hello.asm exists
379 * assemble and add to `myExe`, etc. If no such file is located,
380 * a warning is emitted.
381 *
382 * 2. Compile hello.c and add to the executable `myExe`:
383 * @p(code)
384 * myExe.addObjects(["hello.c"]);
385 * @p
386 * 3. Names may include sub-directory prefixes. In this case, the
387 * source will be located in a sub-directory of the current
388 * package. The following statement declares that the file
389 * "`foo/hello.c`" should be compiled and linked into the executable
390 * `myExe`:
391 * @p(code)
392 * myExe.addObjects(["foo/hello.c"]);
393 * @p
394 * As in the previous examples, the extension ".c" is optional.
395 * In case an extension is not supplied, each extension
396 * understood by the target will be tried until a source file
397 * is located.
398 *
399 * 4. It is also possible to supply file specific compilation
400 * options.
401 * @p(code)
402 * myExe.addObjects(["fir.c", "iir.c"], {defs: "-D_DEBUG"});
403 * @p
404 * In this case, both files fir.c and iir.c will be compiled
405 * with the "`-D_DEBUG`" flag. Any setting of `attrs.defs` in the
406 * executable or package is overridden by this definition.
407 *
408 * @param(names) array of base names of the sources of object files
409 * to be created and linked into the executable.
410 * See NOTE in `{@link xdc.bld}` for filename rules.
411 * @param(objAttrs) optional `{@link xdc.bld.Object#Attrs}` for the
412 * array of objects added; all objects named by names
413 * will be given the attributes `objAttrs`.
414 * @a(returns) `void`
415 *
416 * @a(throws) `Error` exceptions are thrown for fatal errors
417 *
418 * @see xdc.cfg.Program#global
419 */
420 Void addObjects(String names[], Object.Attrs objAttrs = {});
421
422 /*!
423 * ======== addTest ========
424 * Add specified test to executable.
425 *
426 * A test encapsulates an executable and a set of arguments passed to
427 * the executable when it is run.
428 *
429 * Tests are run by naming the goal "`<test_name>.test`" on the xdc
430 * command line; `<test_name>` is the test's name.
431 *
432 * Multiple tests may have the same name; in this case, it is possible
433 * to run all tests using the single goal "`<test_name>.test`"
434 *
435 * @param(testAttrs) test attrs object (`{@link xdc.bld.Test#Attrs}`)
436 *
437 * @a(returns) the `{@link xdc.bld.Test}` instance object created
438 *
439 * @a(throws) `Error` exceptions are thrown for fatal errors
440 */
441 Test.Instance addTest(Test.Attrs testAttrs);
442 }
443 444 445
446