1 2 3 4 5 6 7 8 9 10 11
12 package xdc.bld;
13
14 /*!
15 * ======== Manifest ========
16 * The manifest object for the release file post-processing model
17 *
18 * Each package release corresponds to an archive of a subset of the
19 * developent package's contents. The contents of each release are
20 * specified by an instance of the `{@link Release}` module. Each instance
21 * of the `Release` module can optionally specify a "release script" that
22 * can modify each file prior to it being added to the archive. This script
23 * runs in the context of the "release file post-processing" model.
24 *
25 * This module is the root of the "release file post-processing" model.
26 * Each file in a release may be optionally post-processed by a filter
27 * specified in `{@link #filterMap}.` Other fields of this module provide
28 * a release-specific "context" for the operation of the filters. For
29 * example, a filter may use `{@link #packageName}`, `{@link #releaseName}`,
30 * and `{@link #buildCount}` to prefix all C sources with comments that
31 * identify where they originated.
32 *
33 * All the fields of this module (except `{@link #filterMap}`) are initialized
34 * before a "release script" is run. After the release script completes,
35 * the release archive is created according to the filters specifed in
36 * `{@link #filterMap}`. Files that have no filter are copied without
37 * modification into the release.
38 */
39 metaonly module Manifest {
40
41 /*!
42 * ======== Filter ========
43 * A file filter descriptor
44 *
45 * @field(operation) a JavaScript function that filters the specified
46 * input file and puts the results in specified output file; it is
47 * the output file that is archived as part of the release (not the
48 * input file).
49 *
50 * The operation is called as follows:
51 * @p(code)
52 * operation(filter, src, dst, base)
53 * @p
54 * where:
55 * @p(dlist)
56 * -`filter`
57 * the filter object associated with the file being
58 * processed (which specified `operation` as the function
59 * to call)
60 * -`src`
61 * input file name (relative to the current working
62 * directory)
63 * -`dst`
64 * output file name (relative to the current working
65 * directory)
66 * -`base`
67 * string name of the file as it appears in the array
68 * `Manifest.files`; unlike `dst`, it does not contain a
69 * temporary directory name prefix.
70 *
71 * @field(args) array of arbitrary arguments passed to `operation`
72 * (as a field of the filter object passed as the first argument to
73 * `operation`)
74 *
75 * @field(newFileName) the new name of the output file relative to the
76 * top of the archive. Normally this name should include the
77 * package's name but, in situations where a release must support a
78 * non-RTSC conformant physical design, `newFileName` can be anything.
79 *
80 * @field(newFileMode) the access permissions of the output file.
81 * Normally the file will have the access permissions that exist at
82 * the time archive is created. However, there may be times when
83 * the developer wants/needs to make a file readonly that is (for
84 * development purposes) writable. Only two modes are supported "r"
85 * (readonly) and "rw" (readable and writable).
86 *
87 * @see #filterMap
88 */
89 struct Filter {
90 any operation; /*! the JavaScript function to run */
91 any args[]; /*! additional arguments for operation */
92 String newFileName; /*! the new file name */
93 String newFileMode; /*! either "r" or "rw" */
94 }
95
96 /*!
97 * ======== compatibilityKey ========
98 * The released package's compatibility key
99 *
100 * This string contains the value declared in the package's `package.xdc`
101 * specification file.
102 *
103 * @a(readonly) This value is initialized before the release script or
104 * any of its filters are run and should not be modified.
105 */
106 config String compatibilityKey;
107
108 /*!
109 * ======== buildCount ========
110 * A unique build count for the released package.
111 *
112 * This string contains is a decimal number that increments at least
113 * once every time the package is released. This string together with
114 * the compatibility key forms a unique version number for the package.
115 *
116 * @a(readonly) This value is initialized before the release script or
117 * any of its filters are run and should not be modified.
118 */
119 config String buildCount;
120
121 /*!
122 * ======== packageName ========
123 * The released package's name
124 *
125 * This string contains the value declared in the package's `package.xdc`
126 * specification file.
127 *
128 * @a(readonly) This value is initialized before the release script or
129 * any of its filters are run and should not be modified.
130 */
131 config String packageName;
132
133 /*!
134 * ======== releaseName ========
135 * The release's name
136 *
137 * This string contains the value declared in the package's `package.bld`
138 * build script; it is the name of the output archive without the
139 * "`.tar`" extension.
140 *
141 * @a(readonly) This value is initialized before the release script or
142 * any of its filters are run and should not be modified.
143 */
144 config String releaseName;
145
146 /*!
147 * ======== files ========
148 * An array of files in the release
149 *
150 * The file names in this array include the package's name; i.e.,
151 * these names are relative to the package's repository rather than
152 * the package's build directory.
153 *
154 * This value is initialized before the release script or any of its
155 * filters are run, and it contains the the names of the files specified
156 * directly or indirectly by the package's build script.
157 *
158 * By default, this list does not contain all files in this package
159 * release, it excludes files that are commonly copied verbatim into
160 * the release (see below). To get the complete list you must call
161 * `{@link #getAllFiles Manifest.getAllFiles}`.
162 *
163 * The excluded files are those that are indirectly included either via
164 * @p(blist)
165 * - a directory named in `{@link PackageContents#otherFiles}` or
166 * `{@link Release#otherFiles}`,
167 * - a repository added via `{@link PackageContents#addRepository}`,
168 * or
169 * - the documentation directory named by
170 * `{@link PackageContents#docDir}`
171 * @p
172 *
173 * It is possible to remove files from a release by removing it from
174 * this array; only files in this array or that are in the specified
175 * verbatim directories, the directories named above, will appear in
176 * the release. To remove files that are in any of these directories
177 * use `{@link #getAllFiles Manifest.getAllFiles}` to re-initialize
178 * `files` so that it contains all of the release's files, then
179 * selectivly remove the files from this array.
180 *
181 * It is also possible to add files to a release by adding files to
182 * this array. In fact, files added to the release can be generated
183 * by the filter operation specified for the file in
184 * `{@link #filterMap}`. However, since these files are only present
185 * in releases of a package (they are not built as part of the normal
186 * build of `all` files and only appear in installed releases of a
187 * package), packages that must be built as part of building this
188 * release should not refer to these files.
189 */
190 config String files[];
191
192 /*!
193 * ======== filterMap ========
194 * A map of filters for each file in the release
195 *
196 * This map is indexed by the name of the file (as it appears in the
197 * `{@link #files}` array) in the release and defines for each file a
198 * filter that is applied to the file before it is archived in a
199 * release.
200 *
201 * @a(example) The following script fragment illustrates how one can
202 * filter all *.c files in a release through a custom JavaScript
203 * function named `copyright`.
204 * @p(code)
205 * function copyright(args, ...) { ...}
206 *
207 * for (var i = 0; i < Manifest.files.length; i++) {
208 * var fileName = Manifest.files[i];
209 * if (fileName.match(/\.c$/) != null) {
210 * Manifest.filterMap[fileName] = {operation: copyright};
211 * }
212 * }
213 * @p
214 *
215 * @see #files
216 */
217 config Filter filterMap[string];
218
219 /*!
220 * ======== getAllFiles ========
221 * Read the entire release manifest into the Manifest.files array
222 *
223 * This function re-reads the release's manifest into the
224 * `Manifest.files` array but only excludes the directories whose
225 * names appear in the `String` array `verbatimDirs`.
226 *
227 * @param(verbatimDirs) array of strings naming directories relative
228 * to the package's base directory. Each
229 * directory named in this array (and all the
230 * files and sub-directories it contains) is
231 * excluded from the `Manifest.files` array and
232 * is automatically added to the release without
233 * change.
234 *
235 * If this array is `null` or empty, all files
236 * in the release are read into the
237 * `Manifest.files` array.
238 */
239 Void getAllFiles(String verbatimDirs[]);
240 }
241 242 243
244