1 /* --COPYRIGHT--,EPL
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 * --/COPYRIGHT--*/
12 /*
13 * ======== PackageContents.xdc ========
14 */
15 package xdc.bld;
16
17 /*!
18 * ======== PackageContents ========
19 * Package container populated by a build script.
20 *
21 * This module defines the `PackageContents` object (aliased as `Pkg` in
22 * build scripts) which represents the contents of a package. Build scripts
23 * add to this package using the add* methods defined below.
24 *
25 * In addition to the items added by the build script, every package has at
26 * least one release, the default release. If the {@link #defaultRelease}
27 * configuration parameter is not set, a default release will be
28 * implicitly created.
29 *
30 * Every library, executable, and repository added to the package is
31 * automatically added to the default release.
32 *
33 */
34 metaonlymodule PackageContents {
35 /*!
36 * ======== Attrs ========
37 * Package-level attributes.
38 *
39 * These attributes provide package-level defaults for attributes that
40 * provide control over the code generation tools, the configuration
41 * tool, and release options.
42 *
43 * @field(profile) This string names a profile defined by the
44 * executable's target. A profile specifies a set of compiler,
45 * linker, and archiver options that are to be used when
46 * compiling and linking code. Note that these tool options are
47 * in addition to any options specified via `aopts`, `copts`,
48 * etc.
49 *
50 * If this field is not specified or set to `null`, the
51 * `"release"` profile will be used.
52 *
53 * @field(incs) This string contains include path options used by
54 * the compiler (or assembler) to locate include files; e.g.,
55 * "`-I ../../include -I ../c55xx`". Note that the syntax of
56 * this string may be target dependent.
57 *
58 * @field(defs) This string contains options used by the
59 * compiler (or assembler) to define macros; e.g.,
60 * "`-D_C6xxx -DDEBUG=1`". Note that the syntax of
61 * this string may be target dependent.
62 *
63 * @field(aopts) This string contains options used by the assembler
64 * to produce object files; e.g., "`-mP1`". Note that the syntax
65 * of this string may be target dependent.
66 *
67 * @field(copts) This string contains options used by the C/C++
68 * compiler to produce object files; e.g., "`-o3 -mi1`". Note
69 * that the syntax of this string may be target dependent.
70 *
71 * @field(cfgcopts) This string contains options used by the C/C++
72 * compiler to compile the generated C config file. If `cfgopts`
73 * is not specified, the options specified in `copts` are
74 * used instead.
75 *
76 * @field(lopts) This string contains options used by the linker
77 * produce object files; e.g., "`-l mylib.lib`". Note
78 * that the syntax of this string may be target dependent.
79 *
80 * @field(tcopts) This string contains options passed to `tconf`
81 * Deprecated, use `xsopts` instead.
82 *
83 * @field(xsopts) This string contains options passed to `xs`
84 * when running configuration scripts; e.g., to turn on the
85 * reporting of warnings this string can be set to "`-js -w`",
86 * or to define the name-value pair "`FOO=bar`" available via
87 * the environment hash-table `xsopts` should be set to
88 * "`-DFOO=bar`".
89 *
90 * @field(exportCfg) If this field is set to `true`, configuration
91 * scripts will, by default, be part of the releases created
92 * by this package.
93 *
94 * @field(exportDoc) If this field is set to `true`, generated
95 * documentation will, by default, be part of the releases
96 * created by this package.
97 *
98 * @field(exportSrc) If this field is set to `true`, the sources
99 * used to build this package will, by default, be part of the
100 * releases created by this package.
101 *
102 * @field(exportExe) If this field is set to `true`, the executables
103 * created in this package will, by default, be part of the
104 * releases created by this package.
105 *
106 * @field(exportAll) If this field is set to true, all files
107 * in this package that are not known to be generated are in
108 * the release. If it is unspecified (or set to `null`) these
109 * files will not be added to this release. See
110 * `{@link xdc.bld.Release#Attrs}` for more information about
111 * this option.
112 *
113 * @field(relScript) If this field is non-`null`, the string names a
114 * "release script" that is run to post-process the
115 * files that are part of a release. Like configuration scripts,
116 * the string names a script file that is searched for first in
117 * the in package's base directory, and then along the package
118 * path.
119 *
120 * @field(compress) If this field is set to `true`, the package release
121 * archive files will be, by default, compressed; otherwise, the
122 * archives will not be compressed
123 *
124 * @field(archiver) This field names the archiver to use when creating a
125 * release. Two archivers are currently supported:
126 * "tar" and "zip". If the archiver is set to "zip"
127 * the `{@link #Attrs.compress}` field is implicitly set to
128 * `true`.
129 *
130 * @see #attrs
131 */
132 struct Attrs {
133 String profile; /*! select appropriate `ITarget.OptionSet` */
134 String aopts; /*! assembly language options */
135 String copts; /*! C/C++ compiler options */
136 String cfgcopts; /*! C/C++ compiler options for the C config file */
137 String defs; /*! -D options common to C/C++/asm */
138 String incs; /*! -I options common to C/C++/asm */
139 String tcopts; /*! tconf options, deprecated */
140 String xsopts; /*! xs options */
141 String lopts; /*! linker options */
142 Bool exportDoc; /*! if `true`, export generated docs */
143 Bool exportExe; /*! if `true`, export executables */
144 Bool exportCfg; /*! if `true`, export program cfg scripts */
145 Bool exportSrc; /*! if `true`, export all package sources */
146 Bool exportAll; /*! if `true`, export all non-gen'd files */
147 String relScript; /*! release files post-processing script */
148 Bool compress; /*! if `true`, compress package release archives */
149 String archiver; /*! "tar" or "zip"; defaults to "tar" */
150 };
151
152 /*!
153 * ======== attrs ========
154 * Package attributes.
155 *
156 * These attributes are "inherited" by all executables and libraries
157 * added to this package set.
158 *
159 * @see xdc.bld.Executable#attrs
160 * @see xdc.bld.Library#attrs
161 */
162 config PackageContents.Attrs attrs;
163
164 /*!
165 * ======== cfgDir ========
166 * The directory where all intermediate program files are placed.
167 *
168 * During configuration, several files are generated (a C++ source file,
169 * a linker command file, etc.) these generated files are placed in
170 * the directory specified by this parameter.
171 */
172 config String cfgDir = "package/cfg/";
173
174 /*!
175 * ======== docDir ========
176 * The directory where generated docs are placed.
177 *
178 * If set to a non-`null` value, package documentation will be
179 * automatically generated and placed in this directory. If
180 * it is not set or set to `null`, no docs will be generated for
181 * this package.
182 *
183 * If you set `{@link #Attrs exportDoc}` or `{@link #Attrs exportAll}`
184 * to `true` the generated docs will be included in the appropriate
185 * releases of the package.
186 */
187 config String docDir;
188
189 /*!
190 * ======== imports ========
191 * An array of required packages (and their version) for this package
192 *
193 * @a(readonly) This parameter is an array of all prerequisite packages
194 * required by this package. Each string is of the form:
195 * @p(code) 196 * <packageName>{<packageCompatibilityKey>
197 * @p 198 * where `<packageName>` is the name of the required package and
199 * `<packageCompatibilityKey>` is the compatibility key specified in the
200 * `requires` statement of this package. If no compatibility key is
201 * specified in `package.xdc`, `<packageCompatibilityKey>` is "".
202 *
203 * If the package specifies that a requirement is "internal", the
204 * package name is prefixed with a '*' character. In other words, the
205 * string is of the form:
206 * @p(code) 207 * *<packageName>{<packageCompatibilityKey>
208 * @p 209 */
210 config String imports[];
211
212 /*!
213 * ======== libDir ========
214 * The directory where all intermediate library directories are placed.
215 *
216 * Each object file for a library is placed in a sub-directory of this
217 * directory that has a name that matches the name specified in the
218 * `{@link #addLibrary()}` function.
219 */
220 config String libDir = "package/lib/";
221
222 /*!
223 * ======== libTemplate ========
224 * Template of a common C-file archived into every library
225 *
226 * This template can be used to embed package-specific meta-information
227 * into each library produced by the package. For example, it can be
228 * used to add package version infomation to each library.
229 *
230 * This template is expanded just once in the Build model during
231 * makefile generation. Thus, the contents of the resulting C-file can
232 * not be library specific.
233 *
234 * The template is found using `xdc.findFile()` and, as a result,
235 * `libTemplate` may refer to a template in either the current package
236 * or even in another package.
237 *
238 * During expansion of the template, the `this` pointer is the
239 * `PackageContents` module object; i.e., the object that the global
240 * variable `Pkg` references.
241 *
242 * The expanded template may refer to the following pre-defined macros:
243 * @p(dlist) 244 * - `__xdc_PKGVERS`
245 * the package compatibility key declared in package.xdc; e.g.
246 * "`1, 2, 3`"
247 * - `__xdc_PKGNAME`
248 * the package's name; e.g., `xdc.bld`
249 * - `__xdc_PKGPREFIX`
250 * the package's prefix; e.g., for the package `xdc.bld` the
251 * prefix would be `xdc_bld_`
252 * @p 253 */
254 config String libTemplate = null;
255
256 /*!
257 * ======== relDir ========
258 * The directory where all intermediate release files are placed.
259 *
260 * Release specific files for a release are placed in a sub-directory of
261 * this directory that has a name that matches the name specified in the
262 * `{@link #addRelease()}` function.
263 */
264 config String relDir = "package/rel/";
265
266 /*!
267 * ======== producerId ========
268 * Producer ID string
269 *
270 * The value of this string is embedded in every release of this
271 * package and can serve as a way to identify a single version
272 * ID for a collection of related packages.
273 *
274 * @_nodoc 275 */
276 config String producerId;
277
278 /*!
279 * ======== version ========
280 * The package version string.
281 *
282 * @a(readonly) This parameter is a version string that comes from the
283 * `package.xdc` specification.
284 */
285 config String version;
286
287 /*!
288 * ======== interfaces ========
289 * An array of interface names provided by this package.
290 *
291 * @a(readonly) This parameter is an array of all interface names
292 * defined by this package.
293 */
294 config String interfaces[];
295
296 /*!
297 * ======== makePrologue ========
298 * String to add to the beginning of the generated makefile.
299 *
300 * This string is placed at the very beginning of the package's
301 * generated makefile. This allows one to extend the build
302 * environment using any facility available to GNU make.
303 */
304 config String makePrologue = "";
305
306 /*!
307 * ======== makeEpilogue ========
308 * String to add to the end of the generated makefile.
309 *
310 * Similar to makePrologue except that this string is placed at
311 * the very end of the generated makefile.
312 */
313 config String makeEpilogue = "";
314
315 /*!
316 * ======== defaultRelease ========
317 * The default release for this package.
318 *
319 * If this configuration parameter is defined, it is taken to be the
320 * default release instance; otherwise a default instance is created
321 * with the appropriate defaults.
322 *
323 * If this release's `label` attribute is `undefined` or `null`, it is
324 * set to `"default"` before the release is generated; otherwise the
325 * label attribute is unchanged from what the user specified for this
326 * instance.
327 *
328 * The implicitly created default release is created as follows:
329 * @p(code) 330 * PackageContents.addRelease(name, {label: "default"})
331 * @p 332 * where `name` is the package's name with all '.'s replaced with '_'.
333 */
334 config Release.Instance defaultRelease;
335
336 /*!
337 * ======== releasePrefix ========
338 * A prefix appended to the name of each release archive.
339 *
340 * This configuration parameter allows one to generate release archives
341 * somewhere other than inside the package being built. `releasePrefix`
342 * is prepended to the name of the release name to form the name of the
343 * release archive.
344 *
345 * For example, setting `releasePrefix` to `"../"` implies that a
346 * release named `"exports/foo"` generates an archive file named
347 * `foo.tar` in the directory `"../exports"`.
348 *
349 * `releasePrefix` must either begin with the '^' character or be a
350 * relative path that is relative to the package's "base" directory;
351 * i.e., the directory containing the package's specification file
352 * `package.xdc`.
353 *
354 * If `releasePrefix` begins with the '^' character, the remainder of
355 * the string is treated as though it is relative to the package's
356 * repository. In effect, the '^' character is replaced with an
357 * appropriate number of '../' sequences to sufficient to navigate to
358 * the package's repository.
359 *
360 * For example, suppose your packages are in a repository named `"src"`.
361 * Setting `releasePrefix` to `"^/../exports"` implies that a release
362 * named `"foo"` generates an archive file named `foo.tar` in the
363 * directory named `"exports"` which is a sibiling of `"src"` - the
364 * package's repository.
365 *
366 * This prefix can be overridden on a per release basis; see
367 * `{@link xdc.bld.Release#Attrs}`.
368 *
369 * @a(note) If this parameter starts with `".."` or `"^"`, the resulting
370 * archive file will not be removed as part of a package clean.
371 */
372 config String releasePrefix = "";
373
374 /*!
375 * ======== modules ========
376 * An array of module names provided by this package.
377 *
378 * @a(readonly) This parameter is an array of all module names
379 * implemented in this package.
380 */
381 config String modules[];
382
383 /*!
384 * ======== name ========
385 * Name of this package
386 *
387 * @a(readonly) This parameter is the name of this package as
388 * specified by the `package.xdc` package specification file
389 */
390 config String name;
391
392 /*!
393 * ======== otherFiles ========
394 * Array of files to include this package.
395 *
396 * This is an array of arbitrary file names that are to be included
397 * in the package.
398 *
399 * Only those files that are not already directly (or indirectly)
400 * named by adding executables or libraries to this package set need
401 * to appear in this array.
402 */
403 config String otherFiles[];
404
405 /*!
406 * ======== generatedFiles ========
407 * Array of generated files
408 *
409 * This is an array of arbitrary file names that are to be removed
410 * during a clean of this package. File names that end with the `'/'`
411 * character are assumed to be directories; in this case, the directory
412 * and all of its contents are removed during the clean.
413 *
414 * Only those files that are not already directly (or indirectly)
415 * named by adding executables or libraries to this package set need
416 * to appear in this array.
417 */
418 config String generatedFiles[];
419
420 /*!
421 * ======== otherSrcs ========
422 * Array of source files to include this package.
423 *
424 * Like otherFiles except that the file names listed here are to be
425 * post-processed by the xdc document preparation tools. This array
426 * only needs to specify files that are not implicitly specidied via
427 * any of the addObjects function; e.g., script files, hand-creafted
428 * headers, etc.
429 */
430 config String otherSrcs[];
431
432 /*!
433 * ======== packagePath ========
434 * This configuration parameter allows one to set the package
435 * path from within the build script. This setting overrides
436 * the setting of `XDCPATH` either in the environment or on the
437 * command line.
438 *
439 * @b(deprecated) `XDCPATH` should be set on the command line or in
440 * the environment. This avoids the confusion that will result from
441 * different package paths being used to generate the makefiles from
442 * the package path used to build other package contents.
443 *
444 * @_nodoc this parameter should not be used!!!!!!
445 */
446 config String packagePath = null;
447
448 /*!
449 * ======== uses ========
450 * Array of directory suffixes used to locate files.
451 *
452 * This array of directory suffixes is used to locate package files
453 * that are referenced (e.g., via #include) without the package name.
454 *
455 * This array names package directory suffixes (found along the
456 * package path) that:
457 * @p(nlist) 458 * - contain headers included by this package's sources which
459 * are included *without* using the package name, or
460 * - contain JavaScript "import" files which are included (via
461 * `utils.importFile()`) *without* using the package name.
462 * @p 463 * This mechanism is used to support legacy code that does not
464 * explicitly name the package in the #include statements, and *only*
465 * affects the compiler's -I options (not the package path) and the
466 * configuration tool's import path (`config.importPath`).
467 *
468 * Strings in the Pkg.uses array must not be absolute paths. Each string
469 * in the Pkg.uses array must point to an existing directory that can be
470 * located along the package path. The generated makefiles create an
471 * absolute path by simply appending the string from `uses[]` to each
472 * directory name in the package path until an existing directory is
473 * found. The resulting absolute path is then passed to the compiler in
474 * a -I option, for example.
475 *
476 * The directories named in this array may include sub-directories of
477 * any package in the package path.
478 *
479 * The strings in this array should use '/' to separate directories;
480 * even on Windows systems. Since Windows supports '/' as a directory
481 * separator, the use of '/' ensures host platform independence.
482 *
483 * @a(Example) 484 * The following example allows sources in the current package to
485 * "`#include <tsk.h>`" and have the compiler find `tsk.h` in the
486 * sub-directory ti/bios/include which is contained in some repository
487 * named in the package path (`XDCPATH`):
488 * @p(code) 489 * var Pkg = xdc.useModule('xdc.bld.PackageContents');
490 * Pkg.uses = ["ti/bios/include", "ti/xdais/legacy"];
491 * @p 492 */
493 config String uses[];
494
495 /*!
496 * ======== addLibrary ========
497 * Add specified library to this package
498 *
499 * The name of the library archive file is `<name>.a<target_suffix>`,
500 * where `<name>` is the name parameter (which may contain a directory
501 * prefix) and `<target_suffix>` is the suffix specified by the target
502 * parameter (`{@link xdc.bld.ITarget#suffix}`).
503 *
504 * The individual objects of each library are located in the directory
505 * `<libDir>/<name>`, where `<name>` is the name parameter and `<libDir>`
506 * is the configurable parameter `{@link xdc.bld.PackageContents#libDir}`.
507 * Thus, the name parameter names *both* an archive file and a
508 * sub-directory (in `PackageContents.libDir`) that contains the objects
509 * in the archive.
510 *
511 * @param(name) library base name; this name is used to create
512 * *both* an archive and a sub-directory in the
513 * package's "libDir" directory which
514 * will contain the target-specific object files.
515 * See NOTE in `{@link xdc.bld}` for filename rules.
516 *
517 * @param(target) target (a module implementing the
518 * `{@link xdc.bld.ITarget}` interface) for each built
519 * object in the library
520 *
521 * @param(libAttrs) optional `library` attributes object
522 * (`{@link xdc.bld.Library#Attrs}`)
523 *
524 * @a(returns) Returns the `{@link xdc.bld.Library}` instance
525 * object created.
526 * @a(throws) `XDCException` exceptions are thrown for fatal
527 * errors. The following error codes are
528 * reported in the exception message:
529 * @p(dlist) 530 * - `xdc.bld.INVALID_TARGET`
531 * This error is reported when a package is being
532 * built for an unknown target. Ensure that the
533 * correct targets are mentioned in the package's
534 * build script.
535 * - `xdc.bld.LIBRARY_EXISTS`
536 * This error is reported when a package's build
537 * script specifies multiple libraries with the
538 * same name. Ensure that the names of the
539 * libraries to be built are unique.
540 * - `xdc.bld.PARAMETER_MISMATCH`
541 * This error is reported whenever parameters with
542 * the wrong type are passed to the method. Ensure
543 * that the parameters passed have the right type.
544 *
545 * @see xdc.bld.PackageContents#libDir
546 * @see xdc.bld.ITarget#suffix
547 */
548 Library.Instance addLibrary(String name, ITarget.Module target,
549 Library.Attrs libAttrs = {});
550
551 /*!
552 * ======== addExecutable ========
553 * Add specified executable to this package.
554 *
555 * The name of the executable file is `<name>.x<target_suffix>`,
556 * where `<name>` is the name parameter (which may contain a directory
557 * prefix) and `<target_suffix>` is the suffix specified by the target
558 * parameter (`{@link xdc.bld.ITarget#suffix}`).
559 *
560 * This name is also used to create a sub-directory in the package's
561 * "cfgDir" directory (`{@link xdc.bld.PackageContents#cfgDir}`) to
562 * contain files generated for the benefit of creating the executable.
563 * Thus, the name parameter names *both* an executable file and a
564 * sub-directory (in `PackageContents.cfgDir`) that contains the objects
565 * linked into the executable.
566 *
567 * When the executable is added to the package, a `{@link xdc.bld.Test}`
568 * is implicitly added to the executable; thus, every executable has at
569 * least one `Test`. Attributes for this test can be specified via
570 * `exeAttrs`.
571 *
572 * @param(name) executable base name; this name is used to create
573 * the file name of the output executable and has the
574 * form:
575 * @p(code) 576 * <name>.x<suffix>
577 * @p 578 * where `<suffix>` is the suffix specified by
579 * the target argument below.
580 * See NOTE in `{@link xdc.bld}` for filename rules.
581 *
582 * @param(target) target (`{@link xdc.bld.ITarget}`) for each built
583 * object linked into the executable.
584 *
585 * @param(platform) string name of the platform; this is the name of a
586 * platform package
587 *
588 * @param(exeAttrs) optional executable attrs object
589 * (`{@link xdc.bld.Executable#Attrs}`)
590 *
591 * @a(returns) Returns the `{@link xdc.bld.Executable}` instance
592 * object created.
593 *
594 * @a(throws) `XDCException` exceptions are thrown for fatal
595 * errors. The following error codes are
596 * reported in the exception message:
597 * @p(dlist) 598 * - `xdc.bld.INVALID_TARGET`
599 * This error is reported when a package is being
600 * built for an unknown target. Ensure that the
601 * correct targets are mentioned in the package's
602 * build script.
603 * - `xdc.bld.EXECUTABLE_EXISTS`
604 * This error is reported when a package's build
605 * script specifies multiple executables with the
606 * same name. Ensure that the names of the
607 * executables to be built are unique.
608 * - `xdc.bld.PARAMETER_MISMATCH`
609 * This error is reported whenever parameters with
610 * the wrong type are passed to the method. Ensure
611 * that the parameters passed have the right type.
612 *
613 */
614 Executable.Instance addExecutable(String name, ITarget.Module target,
615 String platform, Executable.Attrs exeAttrs = {});
616
617 /*!
618 * ======== addRepository ========
619 * Add a repository to this package
620 *
621 * A repository is a directory that contains packages. Repositories are
622 * typically named in the user's XDCPATH environment variable and contain
623 * a set of packages that are managed as a group.
624 *
625 * This method allows one to bundle several packages together into a
626 * single release (of the package that contains this repository).
627 *
628 * @param(repositoryName) name of a directory (relative to this
629 * package's base) that will contain the packages
630 * added via
631 * `{@link xdc.bld.Repository#addPackages()}`
632 * See NOTE in `{@link xdc.bld}` for filename
633 * rules.
634 *
635 * @param(repAttrs) optional `Repository` attributes associated
636 * with this repository (see
637 * `{@link xdc.bld.Repository#Attrs}`)
638 *
639 * @a(returns) Returns the `{@link xdc.bld.Repository}`
640 * instance object created.
641 *
642 * @a(throws) `XDCException` exceptions are thrown for fatal
643 * errors. The following error codes are
644 * reported in the exception message:
645 * @p(dlist) 646 * - `xdc.bld.REPOSITORY_EXISTS`
647 * This error is reported whenever a package's build
648 * script specifies multiple repositories with the
649 * same name. Ensure that the names of the
650 * repositories specified in the build script are
651 * unique.
652 */
653 Repository.Instance addRepository(String repositoryName,
654 Repository.Attrs repAttrs = {});
655
656 /*!
657 * ======== addRelease ========
658 * Add specified release to this package
659 *
660 * @param(name) release base name; this name is used to create
661 * the file name of the output file and has the
662 * form:
663 * <name>.tar
664 * See NOTE in `{@link xdc.bld}` for filename rules.
665 *
666 * @param(relAttrs) optional release attributes object
667 * (`{@link xdc.bld.Release#Attrs}`)
668 *
669 * @a(returns) Returns the `{@link xdc.bld.Release}` instance object
670 * created.
671 *
672 * @a(throws) `XDCException` exceptions are thrown for fatal
673 * errors. The following error codes are
674 * reported in the exception message:
675 * @p(dlist) 676 * - `xdc.bld.RELEASE_EXISTS`
677 * This error is reported whenever a package's build
678 * script specifies multiple releases with the same
679 * name. Ensure that the names of the releases
680 * specified in the build script are unique.
681 * - `xdc.bld.INVALID_RELEASE_PREFIX`
682 * This error is reported whenever a release prefix
683 * is specified by its absolute path in the package's
684 * build script. The release prefix has to be
685 * relative to the package's base directory.
686 * - `xdc.bld.INVALID_RELEASE_NAME`
687 * This error is reported whenever a release name is
688 * specified by its absolute path in the package's
689 * build script. The release name has to be relative
690 * to the package's base directory.
691 */
692 Release.Instance addRelease(String name, Release.Attrs relAttrs = {});
693
694 /*!
695 * ======== addScript ========
696 * Add a script to this package
697 *
698 * Both XDCscript and Korn shell scripts can be added to package. This
699 * not only allows one to add script utilities to a package, it
700 * also makes it easy to create scripted regression tests. As with
701 * `Executable`s, it is possible to add `{@link xdc.bld.Test}`s to a
702 * `{@link xdc.bld.Script Script}`; see `{@link xdc.bld.Script#addTest}`.
703 *
704 * @param(name) name of the script to add to this package. Script
705 * names are simply the script's filename relative to
706 * the package's base directory. Scripts can have any
707 * extension, but if the extension is "`.sh`" or "`.ksh`"
708 * a Korn shell compatible shell is used to run the
709 * script's tests; otherwise it is assumed to be an
710 * XDCscript file and any tests will be run by the
711 * XDCscript interpreter `xs`.
712 *
713 * @param(scriptAttrs) optional script attributes object
714 * (`{@link xdc.bld.Script#Attrs}`)
715 *
716 * @a(returns) Returns the `{@link xdc.bld.Script}` instance
717 * object created.
718 *
719 * @a(throws) `XDCException` exceptions are thrown for fatal
720 * errors. The following error codes are
721 * reported in the exception message:
722 * @p(dlist) 723 * - `xdc.bld.SCRIPT_EXISTS`
724 * This error is reported whenever a package's build
725 * script specifies multiple user scripts with the
726 * same name. Ensure that the names of the user
727 * scripts are unique.
728 */
729 Script.Instance addScript(String name, Script.Attrs scriptAttrs = {});
730
731 /*!
732 * ======== addAssembly ========
733 * @_nodoc assemblies are experimental not fully qualified/tested
734 * entities
735 * @a(returns) Returns the `{@link xdc.bld.Assembly}` instance
736 * object created.
737 *
738 * @a(throws) `XDCException` exceptions are thrown for fatal
739 * errors. The following error codes are
740 * reported in the exception message:
741 * @p(dlist) 742 * - `xdc.bld.INVALID_TARGET`
743 * This error is reported when a package is being
744 * built for an unknown target. Ensure that the
745 * correct targets are mentioned in the package's
746 * build script.
747 */
748 Assembly.Instance addAssembly(String name, ITarget.Module target,
749 String platform, Executable.Attrs exeAttrs = {});
750
751 /*!
752 * ======== onInit ========
753 * @_nodoc this function is called from the bld package's
754 * initialization function to initialize this module.
755 *
756 * @a(throws) `XDCException` exceptions are thrown for fatal
757 * errors. The following error codes are
758 * reported in the exception message:
759 * @p(dlist) 760 * - `xdc.bld.INCORRECT_PACKAGE_NAME`
761 * This error is reported whenever package name does
762 * not match the directory name. Package names should
763 * match the directory layout. For example the
764 * package `ti.sdo.ce.osal` should be created in the
765 * directory `ti\sdo\ce\osal`.
766 * - `xdc.bld.CREATE_DIR_ERROR`
767 * This error is reported whenever there is an error
768 * in creating package directories. This maybe
769 * related with issues with the host filesystem.
770 * Check whether directories
771 * can be created manually in the `package`
772 * sub-directory.
773 */
774 function onInit();
775 }
776 /*
777 * @(#) xdc.bld; 1, 0, 2,240; 6-9-2010 16:24:42; /db/ztree/library/trees/xdc/xdc-u18x/src/packages/
778 */
779