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 * ======== 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(relScriptArgs) If this field is non-`null`, the string is
92 * used to initialize the `arguments[]` array which is
93 * accessible to the release script named by `relScript`. The
94 * elements of the `argumants[]` array are formed from the white
95 * space separated elements of `relScriptArgs`. If this string
96 * is `null` or empty, the `arguments[]` array has length `0`.
97 *
98 * @field(label) This string allows one to "tag" each release with a
99 * label that can be used by other tools to select appropriate
100 * releases. For example, the label might contain customer names.
101 *
102 * This label is not interpreted by the XDC tools. It is simply
103 * recorded in the package's build model XML file
104 * (`package/package.bld.xml`) and retrieved via
105 * `{@link xdc.bld.BuildEnvironment#getReleaseDescs()}`
106 *
107 * @field(prefix) This string allows one to "export" each release to a
108 * location outside of the package. `prefix` is prepended
109 * to the name of the release name to form the name of the
110 * release archive.
111 *
112 * For example, setting `prefix` to `"../"` implies that a
113 * release named `"exports/foo"` generates an archive file named
114 * `foo.tar` in the directory `"../exports"`.
115 *
116 * `prefix` must either begin with the '^' character or
117 * be a path that is relative to the package's "base"
118 * directory; i.e., the directory containing the package's
119 * specification file `package.xdc`.
120 *
121 * If `prefix` begins with the '^' character, the
122 * remainder of the string is treated as though it is relative
123 * to the package's repository. In effect, the '^' character is
124 * replaced with an appropriate number of '../' sequences to
125 * sufficient to navigate to the package's repository.
126 *
127 * If it is not specified (or set to `null`) the current setting
128 * of `{@link xdc.bld.PackageContents#releasePrefix}` is used.
129 *
130 * @field(compress) If this field is set to `true`, the release
131 * archive file will be compressed; otherwise, the
132 * archive will not be compressed. Archives are compressed
133 * via `gzip`; compressed archives are `.tar.gz` files.
134 *
135 * @field(archiver) This field names the archiver to use when creating a
136 * release. Two archivers are currently supported:
137 * "tar" and "zip". If the archiver is set to "zip"
138 * the `{@link #Attrs.compress}` field is implicitly set to
139 * `true`.
140 *
141 * @see #attrs
142 */
143 struct Attrs {
144 String archiver; /*! "tar" or "zip"; defaults to "tar" */
145 Bool compress; /*! if `true`, compress package archive */
146 Bool exportDoc; /*! if `true`, export generated docs */
147 Bool exportExe; /*! if `true`, export program executables */
148 Bool exportCfg; /*! if `true`, export program cfg scripts */
149 Bool exportSrc; /*! if `true`, export all package sources */
150 Bool exportAll; /*! if `true`, export all files in package */
151 String relScript; /*! release files post-processing script */
152 String relScriptArgs; /*! optional arguments to relScript */
153 String prefix; /*! prefix for name of install of archive */
154 String label; /*! uninterpreted label for this release */
155 };
156
157 /*!
158 * ======== Desc ========
159 * A description of a release
160 *
161 * This structure provides information about a release that can be
162 * used to select from multiple releases provided by a package.
163 *
164 * @see xdc.bld.BuildEnvironment#getReleaseDescs()
165 */
166 struct Desc {
167 String name; /*! the name used to create the release */
168 String aname; /*! the file name of the archive */
169 String label; /*! the label given to the release */
170 };
171
172 /*!
173 * ======== DescArray ========
174 * An array of release descriptors
175 */
176 typedef Desc DescArray[];
177
178 instance:
179 /*!
180 * ======== create ========
181 * @_nodoc 182 * Instances should only be created via PackageContents.addRelease()
183 */
184 create();
185
186 /*!
187 * ======== name ========
188 * The name of the release.
189 *
190 * This name is the base name of the generated tar file containing all
191 * files that make up the release. For example, if the name of the
192 * release is "foo" then the file "foo.tar" (located in the same
193 * directory as package.bld) is a tar file containing the release files.
194 *
195 * Note that each package has at least one release defined, the default
196 * release. The default release's name is the name of the package with
197 * '.'s replaced with '_'s. For example, the default release name for
198 * the package "foo.bar" is "foo_bar" and the generated tar file is
199 * named "foo_bar.tar".
200 */
201 config String name;
202
203 /*!
204 * ======== attrs ========
205 * This instance's attributes.
206 *
207 * Unless explicitly specified, these attributes are "inherited" from
208 * the package's attributes (`{@link xdc.bld.PackageContents#attrs}`)
209 *
210 * @see xdc.bld.PackageContents#attrs
211 */
212 config Release.Attrs attrs;
213
214 /*!
215 * ======== otherFiles ========
216 * Additional files to add to this release.
217 *
218 * This is an array of arbitrary files that are to be included
219 * in this release of the package.
220 *
221 * Only those files that are not already directly (or indirectly) named
222 * by adding programs or libraries to this release need to appear in
223 * this array.
224 */
225 config String otherFiles[];
226
227 /*!
228 * ======== excludeDirs ========
229 * List of directory base names to exclude
230 *
231 * This is an array of arbitrary directory "base names" that should
232 * be excluded in this release of the package. This list only
233 * excludes directories that would otherwise be added due to the
234 * recursive include of a parent directory.
235 *
236 * For example, if a directory is specified in `{@link #otherFiles}`
237 * all of its sub-directories will be added unless those sub-directories
238 * are named in the `excludeDirs` list.
239 *
240 * This list is often used to exclude "hidden" directories added by
241 * change control systems and IDEs (`.svn`, `.git`, `.settings`, ...).
242 *
243 * @see #otherFiles
244 * @see PackageContents#excludeDirs
245 */
246 config String excludeDirs[];
247 }
248 /*
249 * @(#) xdc.bld; 1, 0, 2,290; 8-20-2010 17:20:47; /db/ztree/library/trees/xdc/xdc-v48x/src/packages/
250 */
251