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