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 package that contributes a
187 * compiled form of the `{@link xdc.runtime}` runtime support
188 * modules.
189 *
190 * This package is implicitly loaded prior to running the
191 * executable's configuration script. If this field is set to
192 * `null`, no package will be pre-loaded. If this field is not
193 * set (or set to `undefined`), the package specified by this
194 * executable's target will be used (see
195 * {@link xdc.bld.ITarget#rts}) .
196 *
197 * @field(cpuArgs) This field is a hash-table of name-value pairs
198 * interpreted by the CPU as register settings that exist at the
199 * time that the executable is loaded; e.g., it is possible to
200 * specify a non-reset value for the `PMST` register on a C54xx
201 * CPU by setting this parameter to `{PMST: 0xffff}`.
202 *
203 * @field(exportCfg) If this field is set to true, the configuration
204 * script will be part of the releases named in the releases
205 * array. If it is unspecified (or set to `null`) and the
206 * release specifies that configurations are to be exported,
207 * the configuration script will be part of the release. In
208 * all other cases, the configuration is not part of the
209 * release.
210 *
211 * @field(exportSrc) If this field is set to true, the sources
212 * specified via `{@link xdc.bld.Executable#addObjects()}`
213 * will be part of the releases named in the releases
214 * array. If it is unspecified (or set to `null`) and the
215 * release specifies that sources are to be exported,
216 * the sources will be part of the release. In
217 * all other cases, the sources are not added to the
218 * release.
219 *
220 * @field(exportExe) If this field is set to true, the executable
221 * will be part of the releases named in the releases
222 * array. If it is unspecified (or set to `null`) and the
223 * release specifies that configurations are to be exported,
224 * the executable will be part of the release. In
225 * all other cases, the executable is not part of the
226 * release.
227 *
228 * @field(releases) This array contains releases that will contain the
229 * executable. Thus, a single executable can be part of any set
230 * of releases. Each executable is always added to the
231 * package's "default release" in addition to any releases
232 * specified in the releases array.
233 *
234 * @field(test) If this field is set, it defines default attributes for
235 * tests added to this executable, including the implicitly
236 * added test (see {@link xdc.bld.PackageContents#addExecutable}).
237 *
238 * @field(linkTemplate) If this field is set, it defines the linker
239 * command file template to be used to link this executable.
240 * This specification may, however, be overridden by the
241 * configuration script (see
242 * {@link xdc.cfg.Program#linkTemplate}).
243 *
244 * As with configuration scripts, if the specified file does not
245 * exist in the package where the executable is being built and
246 * the name does not begin with `"./"`, it is searched for along
247 * the package path. Thus, it is possible to use templates in
248 * other packages to build executables; e.g., to use the linker
249 * command file "`myExe.cmd`" from the `ti.bios.examples.hello`
250 * package, `linkTemplate` should be set to
251 * `"ti/bios/examples/hello/myExe.cmd"`.
252 *
253 * @see #attrs
254 * @see xdc.bld.PackageContents#Attrs
255 */
256 struct Attrs {
257 String profile; /*! target options profile */
258 String aopts; /*! asm options for objs added to this exe */
259 String copts; /*! C/C++ options for objs added to this exe */
260 String cfgcopts; /*! C/C++ options for the C config file */
261 String defs; /*! definitions for objs added to this exe */
262 String incs; /*! include opts for objs added to this exe */
263 String lopts; /*! linker options for this exe */
264 String tcopts; /*! `tconf` 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 * @(#) xdc.bld; 1, 0, 2,384; 6-27-2012 10:24:45; /db/ztree/library/trees/xdc/xdc-y30x/src/packages/
449 */
450