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