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