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 * ======== Release.xdc ========
14 */
15 package xdc.bld;
16
17 /*!
18 * ======== Release ========
19 * Model of an archive of all files that are part of a release.
20 *
21 * Release instances define a container object that represents all files that
22 * are part of a release of a package. A release may, for example, include
23 * just the files necessary to support a particular ISA even though the
24 * package as a whole can support multiple ISAs.
25 *
26 * Each Release instance is realized as a tar file containing the files
27 * that are part of a release of a package.
28 */
29 metaonlymodule Release {
30
31 /*!
32 * ======== Attrs ========
33 * Optional Release attributes
34 *
35 * Unspecified attributes are "inherited" from
36 * `{@link xdc.bld.PackageContents#Attrs}`; i.e., if one of fields in
37 * this structure is unspecified *and* this field's name matches a field
38 * name in `{@link xdc.bld.PackageContents#Attrs}`, then
39 * this field's value defaults to the value in specified by
40 * `{@link xdc.bld.PackageContents#attrs}`. This mechanism makes it
41 * possible to establish package-wide default values for any of the
42 * "inherited" attributes.
43 *
44 * However, elements added to a release can "override" these attributes.
45 * For example, when an executable is added to a release and the
46 * executable's attributes specify `'exportSrc = false'`, the release
47 * will not contain the executable's sources (even if the release's
48 * `{@link #attrs}.exportSrc` attribute is set to `true`).
49 *
50 * @field(exportCfg) If this field is set to `true`, configuration
51 * scripts will be part of the release. If it is unspecified
52 * (or set to `null`), program configuration scripts will not
53 * be added to this release.
54 *
55 * @field(exportDoc) If this field is set to `true`, generated
56 * documentation will be part of the release.
57 *
58 * @field(exportSrc) If this field is set to `true`, sources
59 * used to produce object files will be part of the release.
60 * If it is unspecified (or set to `null`), no sources will
61 * be part of this release.
62 *
63 * @field(exportExe) If this field is set to `true`, executables
64 * will be part of the release. If it is unspecified (or set
65 * to `null`), executables will not be part of this release.
66 *
67 * @field(exportAll) If this field is set to `true`, all files
68 * in this package that are not known to be generated are in
69 * the release. If it is unspecified (or set to `null`), these
70 * files will not be added to this release.
71 *
72 * Note that the set of files specified by `exportAll` is
73 * determined at the time the package's makefile is generated.
74 * If one of these files is subsequently removed before the
75 * release is built, the build of the release will fail; a file
76 * required by the release no longer exists. If the file is
77 * not really required for the release, you must trigger a
78 * rebuild for the generated makefiles; either touch
79 * `package.bld` or remove the generated makefile and re-build
80 * the release.
81 *
82 * @field(relScript) If this field is non-`null`, the string names a
83 * "release script" that is run to post-process the
84 * files that are part of a release. Like
85 * configuration scripts, the string names a script
86 * file that is searched for first in the in package's
87 * base directory, and then along the package path. See
88 * `{@link Manifest}` for more information about release scripts
89 * and what they can do.
90 *
91 * @field(label) This string allows one to "tag" each release with a
92 * label that can be used by other tools to select appropriate
93 * releases. For example, the label might contain customer names.
94 *
95 * This label is not interpreted by the XDC tools. It is simply
96 * recorded in the package's build model XML file
97 * (`package/package.bld.xml`) and retrieved via
98 * `{@link xdc.bld.BuildEnvironment#getReleaseDescs()}`
99 *
100 * @field(prefix) This string allows one to "export" each release to a
101 * location outside of the package. `prefix` is prepended
102 * to the name of the release name to form the name of the
103 * release archive.
104 *
105 * For example, setting `prefix` to `"../"` implies that a
106 * release named `"exports/foo"` generates an archive file named
107 * `foo.tar` in the directory `"../exports"`.
108 *
109 * `prefix` must either begin with the '^' character or
110 * be a path that is relative to the package's "base"
111 * directory; i.e., the directory containing the package's
112 * specification file `package.xdc`.
113 *
114 * If `prefix` begins with the '^' character, the
115 * remainder of the string is treated as though it is relative
116 * to the package's repository. In effect, the '^' character is
117 * replaced with an appropriate number of '../' sequences to
118 * sufficient to navigate to the package's repository.
119 *
120 * If it is not specified (or set to `null`) the current setting
121 * of `{@link xdc.bld.PackageContents#releasePrefix}` is used.
122 *
123 * @field(compress) If this field is set to `true`, the release
124 * archive file will be compressed; otherwise, the
125 * archive will not be compressed. Archives are compressed
126 * via `gzip`; compressed archives are `.tar.gz` files.
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 archiver; /*! "tar" or "zip"; defaults to "tar" */
138 Bool compress; /*! if `true`, compress package archive */
139 Bool exportDoc; /*! if `true`, export generated docs */
140 Bool exportExe; /*! if `true`, export program executables */
141 Bool exportCfg; /*! if `true`, export program cfg scripts */
142 Bool exportSrc; /*! if `true`, export all package sources */
143 Bool exportAll; /*! if `true`, export all files in package */
144 String relScript; /*! release files post-processing script */
145 String prefix; /*! prefix for name of install of archive */
146 String label; /*! uninterpreted label for this release */
147 };
148
149 /*!
150 * ======== Desc ========
151 * A description of a release
152 *
153 * This structure provides information about a release that can be
154 * used to select from multiple releases provided by a package.
155 *
156 * @see xdc.bld.BuildEnvironment#getReleaseDescs()
157 */
158 struct Desc {
159 String name; /*! the name used to create the release */
160 String aname; /*! the file name of the archive */
161 String label; /*! the label given to the release */
162 };
163
164 /*!
165 * ======== DescArray ========
166 * An array of release descriptors
167 */
168 typedef Desc DescArray[];
169
170 instance:
171 /*!
172 * ======== create ========
173 * @_nodoc 174 * Instances should only be created via PackageContents.addRelease()
175 */
176 create();
177
178 /*!
179 * ======== name ========
180 * The name of the release.
181 *
182 * This name is the base name of the generated tar file containing all
183 * files that make up the release. For example, if the name of the
184 * release is "foo" then the file "foo.tar" (located in the same
185 * directory as package.bld) is a tar file containing the release files.
186 *
187 * Note that each package has at least one release defined, the default
188 * release. The default release's name is the name of the package with
189 * '.'s replaced with '_'s. For example, the default release name for
190 * the package "foo.bar" is "foo_bar" and the generated tar file is
191 * named "foo_bar.tar".
192 */
193 config String name;
194
195 /*!
196 * ======== attrs ========
197 * This instance's attributes.
198 *
199 * Unless explicitly specified, these attributes are "inherited" from
200 * the package's attributes (`{@link xdc.bld.PackageContents#attrs}`)
201 *
202 * @see xdc.bld.PackageContents#attrs
203 */
204 config Release.Attrs attrs;
205
206 /*!
207 * ======== otherFiles ========
208 * Additional files to add to this release.
209 *
210 * This is an array of arbitrary files that are to be included
211 * in this release of the package.
212 *
213 * Only those files that are not already directly (or indirectly) named
214 * by adding programs or libraries to this release need to appear in
215 * this array.
216 */
217 config String otherFiles[];
218 }
219 /*
220 * @(#) xdc.bld; 1, 0, 2,237; 12-18-2009 12:26:41; /db/ztree/library/trees/xdc/xdc-u16x/src/packages/
221 */
222