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 be a relative path that is relative to the
110 * package's "base" directory; i.e., the directory containing the
111 * package's specification file `package.xdc`. If it is not
112 * specified (or set to `null`) the current setting of
113 * `{@link xdc.bld.PackageContents#releasePrefix}` is used.
114 *
115 * @field(compress) If this field is set to `true`, the release
116 * archive file will be compressed; otherwise, the
117 * archive will not be compressed. Archives are compressed
118 * via `gzip`; compressed archives are `.tar.gz` files.
119 *
120 * @field(archiver) This field names the archiver to use when creating a
121 * release. Two archivers are currently supported:
122 * "tar" and "zip". If the archiver is set to "zip"
123 * the `{@link #Attrs.compress}` field is implicitly set to
124 * `true`.
125 *
126 * @see #attrs
127 */
128 struct Attrs {
129 String archiver; /*! "tar" or "zip"; defaults to "tar" */
130 Bool compress; /*! if `true`, compress package archive */
131 Bool exportDoc; /*! if `true`, export generated docs */
132 Bool exportExe; /*! if `true`, export program executables */
133 Bool exportCfg; /*! if `true`, export program cfg scripts */
134 Bool exportSrc; /*! if `true`, export all package sources */
135 Bool exportAll; /*! if `true`, export all files in package */
136 String relScript; /*! release files post-processing script */
137 String prefix; /*! prefix for name of install of archive */
138 String label; /*! uninterpreted label for this release */
139 };
140
141 /*!
142 * ======== Desc ========
143 * A description of a release
144 *
145 * This structure provides information about a release that can be
146 * used to select from multiple releases provided by a package.
147 *
148 * @see xdc.bld.BuildEnvironment#getReleaseDescs()
149 */
150 struct Desc {
151 String name; /*! the name used to create the release */
152 String aname; /*! the file name of the archive */
153 String label; /*! the label given to the release */
154 };
155
156 /*!
157 * ======== DescArray ========
158 * An array of release descriptors
159 */
160 typedef Desc DescArray[];
161
162 instance:
163 /*!
164 * ======== create ========
165 * @_nodoc 166 * Instances should only be created via PackageContents.addRelease()
167 */
168 create();
169
170 /*!
171 * ======== name ========
172 * The name of the release.
173 *
174 * This name is the base name of the generated tar file containing all
175 * files that make up the release. For example, if the name of the
176 * release is "foo" then the file "foo.tar" (located in the same
177 * directory as package.bld) is a tar file containing the release files.
178 *
179 * Note that each package has at least one release defined, the default
180 * release. The default release's name is the name of the package with
181 * '.'s replaced with '_'s. For example, the default release name for
182 * the package "foo.bar" is "foo_bar" and the generated tar file is
183 * named "foo_bar.tar".
184 */
185 config String name;
186
187 /*!
188 * ======== attrs ========
189 * This instance's attributes.
190 *
191 * Unless explicitly specified, these attributes are "inherited" from
192 * the package's attributes (`{@link xdc.bld.PackageContents#attrs}`)
193 *
194 * @see xdc.bld.PackageContents#attrs
195 */
196 config Release.Attrs attrs;
197
198 /*!
199 * ======== otherFiles ========
200 * Additional files to add to this release.
201 *
202 * This is an array of arbitrary files that are to be included
203 * in this release of the package.
204 *
205 * Only those files that are not already directly (or indirectly) named
206 * by adding programs or libraries to this release need to appear in
207 * this array.
208 */
209 config String otherFiles[];
210 }
211 /*
212 * @(#) xdc.bld; 1, 0, 2,216; 9-3-2009 11:41:16; /db/ztree/library/trees/xdc-t57x/src/packages/
213 */
214