1 /*
2 * Copyright (c) 2008 Texas Instruments and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * Texas Instruments - initial implementation
10 *
11 * */
12
13 /*
14 * ======== Executable.xdc ========
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 metaonlymodule 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(tcopts) This string contains options passed to `tconf`.
117 * Deprecated, use `xsopts` instead.
118 *
119 * @field(xsopts) This string contains options passed to `xs`
120 * when running configuration scripts; e.g., to turn on the
121 * reporting of warnings this string can be set to "-js -w",
122 * or to define the name-value pair "FOO=bar" available via
123 * the environment hash-table `xsopts` should be set to
124 * "-DFOO=bar".
125 *
126 * @field(cfgHome) This string names the package that is bound to
127 * the Configuration Model's `$homepkg`. This home package
128 * is automatically loaded as part of configuration and, as
129 * a result, may contribute libraries to the configuration.
130 *
131 * If this parameter is not specified, the package containing
132 * the configuration script is used as the home package. This
133 * ensures that the results of a configuration script are
134 * independent of the package building the configuration. In
135 * most cases, the build package is the package containing the
136 * configuration script and this distinction is not important.
137 * But there are times when it is important to control the home
138 * package; e.g., when an external tool generates a
139 * configuration script from information supplied by another
140 * package or when a configuration script in not in any package.
141 *
142 * @field(cfgScript) This string names the program configuration
143 * script used to create the files necessary to create the
144 * executable. If `cfgScript` is not specified, the configuration
145 * script is assumed to be `<name>.cfg`, where `<name>` is the
146 * base name of the executable. If `cfgScript` is set to `null`,
147 * the executable is assumed to be a "legacy" application that
148 * defines `main()` directly and does not require any
149 * `{@link xdc.runtime}` support.
150 *
151 * If this string is set to a non-`null` value, and does not have
152 * an extension, then the extension `".cfg"` is automatically
153 * added.
154 *
155 * If the specified configuration file does not exist in the
156 * package where the executable is being built and
157 * the name does not begin with `"./"`, it is searched
158 * for along the package path. Thus, it is possible to use
159 * configuration scripts in other packages to build executables;
160 * e.g., to use the configuration script "myExe.cfg" from a
161 * `ti.bios.examples.hello` package, `cfgScript` should be set
162 * to `"ti/bios/examples/hello/myExe.cfg"`.
163 *
164 * The package containing the specified configuration script is
165 * imported prior to running the configuration script and this
166 * package is used to set `xdc.$homepkg`; thus, configuration
167 * scripts that use `xdc.$homepkg` will configure the same
168 * executable independent of the package building the executable.
169 *
170 * @field(profile) This string names a profile defined by the
171 * executable's target. The profile specifies a set of compiler,
172 * linker, and archiver options that are to be used when
173 * producing the executable. Note that these tool options are
174 * in addition to any options specified via `aopts`, `copts`,
175 * etc.
176 *
177 * If this field is not set or set to `null`, the value of
178 * `{@link xdc.bld.PackageContents#attrs.profile}` is used. If
179 * `{@link xdc.bld.PackageContents#attrs.profile}` is not
180 * specified or equal to `null`, the `"release"` profile is used.
181 *
182 * @field(cpuId) This string is used to uniquely identify the
183 * particular CPU on a platform that will run the executable; on
184 * platforms that contain a single CPU, this string is ignored.
185 *
186 * @field(rtsName) This string names a RunTime Support (RTS) package that
187 * will be implicitly loaded prior to running the executable's
188 * configuration script. If this field is set to `null`, then
189 * no RTS package will be loaded. If this field is not set (or
190 * set to `undefined`), the RTS 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 tcopts; /*! `tconf` options for this exe */
262 String xsopts; /*! `xs` options for this exe */
263 String cpuId; /*! optional id of CPU on platform */
264 String rtsName; /*! optional run time support package name */
265 any cpuArgs; /*! optional register settings */
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 Bool isRom; /*! if true, exe is a ROMable sub-assembly */
277 };
278
279 instance:
280 /*!
281 * ======== create ========
282 * @_nodoc 283 * Instances should only be created via PackageContents.addExecutable()
284 */
285 create();
286
287 /*!
288 * ======== name ========
289 * Base name of the executable.
290 *
291 * This name is used to construct the final executable file name as
292 * follows:
293 * @p(code) 294 * <name>.x<target_suffix>
295 * @p 296 * where `<name>` is name and `<target_suffix>` is the suffix defined
297 * by each target that the file is built for. See NOTE in
298 * `{@link xdc.bld}` for filename rules.
299 *
300 * Note: if the same executable is to be built for different platforms
301 * (having the same target), then name must "encode" the platform's
302 * name.
303 */
304 config String name;
305
306 /*!
307 * ======== platform ========
308 * The name of the platform that will run this executable.
309 *
310 * Platforms are modeled as packages that have a module called
311 * "Platform"; thus the platform name is really a package name.
312 */
313 config String platform;
314
315 /*!
316 * ======== target ========
317 * The target (on a platform) that executable should be built for.
318 *
319 * This parameter is used to determine the target to use for any
320 * objects added to the executable.
321 *
322 * During configuration, the executable's platform package can
323 * validate that the target is compatible with the configuration of
324 * the platform; the target object is accessible via the expression
325 * `Program.build.target`.
326 */
327 config ITarget.Module target;
328
329 /*!
330 * ======== attrs ========
331 * This executable's optional attributes.
332 *
333 * These attributes are "inherited" by all objects added to this
334 * executable; i.e., any object attribute that is undefined but is
335 * defined here will be assigned the value from these attributes.
336 *
337 * Similarly, any unspecified attributes that also appear in
338 * `{@link xdc.bld.PackageContents#Attrs}` are inherited from
339 * `{@link xdc.bld.PackageContents#attrs}`.
340 *
341 * @see xdc.bld.PackageContents#Attrs
342 */
343 config Executable.Attrs attrs;
344
345 /*!
346 * ======== addObjects ========
347 * Add specified object to be built and linked into this executable.
348 *
349 * All objects added to the executable are built with the symbol
350 * `xdc_cfg__header__` defined to be the name of the executable-specific
351 * C header generated by the program configuration tool. This symbol
352 * is used by the `xdc/cfg/global.h` header to include the generated
353 * header file; see `{@link xdc.cfg.Program#global}`. Thus, it is
354 * possible to portably include configuration specific definitions in a
355 * source file that is used in many different configurations.
356 *
357 * For example, a portable `main.c` might be structured as follows:
358 * @p(code) 359 * #include <xdc/std.h>
360 * #include <ti/bios/include/log.h>
361 *
362 * #include <xdc/cfg/global.h> // include declaration of trace
363 *
364 * int main(int argc, char *argv[])
365 * {
366 * LOG_printf(trace, "hello world");
367 * :
368 * }
369 * @p 370 *
371 * @a(Examples) 372 *
373 * 1. Locate a source file whose name starts with "hello" with
374 * an extension supported by the executable's target, compile it
375 * and link it into the executable `myExe`:
376 * @p(code) 377 * myExe.addObjects(["hello"]);
378 * @p 379 * If hello.c exists, compile and add to `myExe`, if hello.asm exists
380 * assemble and add to `myExe`, etc. If no such file is located,
381 * a warning is emitted.
382 *
383 * 2. Compile hello.c and add to the executable `myExe`:
384 * @p(code) 385 * myExe.addObjects(["hello.c"]);
386 * @p 387 * 3. Names may include sub-directory prefixes. In this case, the
388 * source will be located in a sub-directory of the current
389 * package. The following statement declares that the file
390 * "`foo/hello.c`" should be compiled and linked into the executable
391 * `myExe`:
392 * @p(code) 393 * myExe.addObjects(["foo/hello.c"]);
394 * @p 395 * As in the previous examples, the extension ".c" is optional.
396 * In case an extension is not supplied, each extension
397 * understood by the target will be tried until a source file
398 * is located.
399 *
400 * 4. It is also possible to supply file specific compilation
401 * options.
402 * @p(code) 403 * myExe.addObjects(["fir.c", "iir.c"], {defs: "-D_DEBUG"});
404 * @p 405 * In this case, both files fir.c and iir.c will be compiled
406 * with the "`-D_DEBUG`" flag. Any setting of `attrs.defs` in the
407 * executable or package is overridden by this definition.
408 *
409 * @param(names) array of base names of the sources of object files
410 * to be created and linked into the executable.
411 * See NOTE in `{@link xdc.bld}` for filename rules.
412 * @param(objAttrs) optional `{@link xdc.bld.Object#Attrs}` for the
413 * array of objects added; all objects named by names
414 * will be given the attributes `objAttrs`.
415 * @a(returns) `void`
416 *
417 * @a(throws) `Error` exceptions are thrown for fatal errors
418 *
419 * @see xdc.cfg.Program#global
420 */
421 Void addObjects(String names[], Object.Attrs objAttrs = {});
422
423 /*!
424 * ======== addTest ========
425 * Add specified test to executable.
426 *
427 * A test encapsulates an executable and a set of arguments passed to
428 * the executable when it is run.
429 *
430 * Tests are run by naming the goal "`<test_name>.test`" on the xdc
431 * command line; `<test_name>` is the test's name.
432 *
433 * Multiple tests may have the same name; in this case, it is possible
434 * to run all tests using the single goal "`<test_name>.test`"
435 *
436 * @param(testAttrs) test attrs object (`{@link xdc.bld.Test#Attrs}`)
437 *
438 * @a(returns) the `{@link xdc.bld.Test}` instance object created
439 *
440 * @a(throws) `Error` exceptions are thrown for fatal errors
441 */
442 Test.Instance addTest(Test.Attrs testAttrs);
443 }
444 /*
445 * @(#) xdc.bld; 1, 0, 2,293; 9-14-2010 16:36:16; /db/ztree/library/trees/xdc/xdc-v49x/src/packages/
446 */
447