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