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 * ======== IPackage.xdc ========
14 */
15 package xdc;
16
17 /*!
18 * ======== IPackage ========
19 * Base interface implemented by all packages.
20 *
21 * If a package does not specify a function declared in
22 * `IPackage`, the default defined in this package is used.
23 *
24 * Packages must implement `IPackage` functions in the package's `package.xs`
25 * file. This file simply defines a function with the same name as that
26 * declared in the the this specification. For example, to implement the
27 * `{@link #getLibs()}` function the following must appear in the package's
28 * `package.xs` file:
29 * @p(code) 30 * function getLibs(prog)
31 * {
32 * ...
33 * }
34 * @p 35 *
36 * Since most `IPackage` functions can be called in any model, any access to
37 * global variables specific for a particular object model should happen only
38 * if the function is called in the context of that model. For example, the
39 * variable `Program` is a global variable in the Configuration Model
40 * (`{@link xdc.cfg.Program}`). Any access to it should happen after a check
41 * for the current model:
42 * @p(code) 43 * if (xdc.om.$name != "cfg") {
44 * print(Program.build.target.name);
45 * }
46 * @p 47 */
48 metaonlyinterface IPackage {
49 /*!
50 * ======== LibDesc ========
51 * Library properties from the Build Object Model (BOM)
52 *
53 * This structure defines library properties that are
54 * carried forward from the Build Model into the Configuration Model.
55 *
56 * @field(target) target for which the library was built.
57 * @field(suffix) the suffix associated with the named target.
58 *
59 */
60 struct LibDesc {
61 String target; /*! target name */
62 String suffix; /*! suffix property of the named target */
63 }
64
65 /*!
66 * ======== BuildAttrs ========
67 * Package-level attributes from the Build Object Model (BOM)
68 *
69 * This structure defines a set of package-level attributes that are
70 * carried forward from the Build Model into the Configuration Model.
71 *
72 * @field(getLibs) the JavaScript function that should be used when
73 * the package participates in a program configuration
74 * script. This field contains the function specified
75 * by a package's build script
76 * @field(libraries) an array of archive names created by this package.
77 * Each name is a package-relative file name of an
78 * archive within the package.
79 * @field(libDesc) a map of library descriptors. This map is indexed
80 * by names that appear in the `libraries` array.
81 */
82 struct BuildAttrs {
83 String libraries[]; /*! array of archive names produced by this pkg */
84 LibDesc libDesc[string]; /*! desriptors for elements in `libraries` */
85 any getLibs; /*! `getLibs` function defined by build script */
86 };
87
88 /*!
89 * ======== packageBase ========
90 * The absolute path to the package's "base" directory
91 *
92 * This parameter contains an absolute path to the directory
93 * containing the package's build script (`package.bld`). For example,
94 * if the package `ti.bios` is located in `c:/packages/ti/bios`, then
95 * `packageBase` equals `c:/packages/ti/bios/`.
96 *
97 * To be robust, clients should not assume that this string ends with a
98 * directory separator.
99 *
100 * @a(readonly) This parameter is set when the package is first loaded
101 * and should not be modified by any other script.
102 */
103 config string packageBase;
104
105 /*!
106 * ======== packageRepository ========
107 * The absolute path to the repository containing the package
108 *
109 * This parameter contains an absolute path to the directory
110 * containing the full directory namespace of the package. For
111 * example, if the package `ti.bios` is located in `c:/packages/ti/bios`,
112 * then `packageRepository` equals `c:/packages/`.
113 *
114 * To be robust, clients should not assume that this string ends with a
115 * directory separator.
116 *
117 * @a(readonly) This parameter is set when the package is first loaded
118 * and should not be modified by any other script.
119 */
120 config string packageRepository;
121
122 /*!
123 * ======== build ========
124 * The package information from the Build Object Model (BOM)
125 *
126 * @a(readonly) This parameter is set when the package is first loaded
127 * and should not be modified by any other script.
128 */
129 config BuildAttrs build;
130
131 /*!
132 * ======== profile ========
133 * The profile requested by a configuration script.
134 *
135 * This parameter is set by configuration scripts to convey additional
136 * information to the package about the libraries being requested from
137 * this package; in particular, it names a specific profile supported by
138 * this package (see {@link xdc.bld.ITarget#profiles}).
139 *
140 * Package `{@link #getLibs()}` functions should refer to this parameter
141 * in lieu of the program's `build.profile`. This allows configuration
142 * scripts to selectively request debug or release libraries on a per
143 * package basis, for example.
144 *
145 * @p(code) 146 * function getLibs(prog)
147 * {
148 * if (this.profile == "debug") {
149 * ...
150 * }
151 * }
152 * @p 153 *
154 * If this parameter is not set by the configuration script, it is
155 * initialized to `{@link xdc.cfg.Program#build.profile}` prior to
156 * generating and configuration files; i.e., the package's
157 * `{@link #getLibs()}` function can assume that this field is always
158 * set and defaults to the profile used to build the executable.
159 */
160 config string profile;
161
162 /*!
163 * ======== init ========
164 * Initialize this package when first imported
165 *
166 * This function is called to initialize the package within any
167 * model. It is called just once (when the package is first imported)
168 * so there is no need to explicitly check for prior invocation.
169 *
170 * The default implementation of this function is a nop.
171 *
172 * @a(context) 173 * @p(dlist) 174 * - `this`
175 * The current package's `xdc.IPackage.Module` object
176 * before any model-specific user script runs (e.g. a program's
177 * configuration script),
178 * after the package's `package.xs` script is run and all
179 * the package's modules are created, and before the
180 * package is added to `xdc.om.$packages` (the Object Model's
181 * package array)
182 *
183 * @a(returns) Returns nothing.
184 *
185 * @a(throws) `Error` exceptions are thrown for fatal errors.
186 */
187 function init();
188
189 /*!
190 * ======== close ========
191 * Close this package after user scripts complete.
192 *
193 * This function is called to allow the package to modify its state
194 * based on the results of the user's script. It can optionally
195 * redefine configuration parameters or even throw exceptions to
196 * prevent the configuration step from completing, for example.
197 *
198 * Other packages and modules, including the modules in the package, can
199 * change the configuration parameters of any module in the package, after
200 * this function was called. Therefore, this function cannot be used to
201 * validate state of the package and of the whole configuration.
202 * Validation should be done in `{@link #validate()}`.
203 *
204 * For all packages A and B, if A requires B, then package A is
205 * closed before package B.
206 *
207 * The default implementation of this function is a nop.
208 *
209 * @a(context) 210 * @p(dlist) 211 * - `this`
212 * The current package's `xdc.IPackage.Module` object
213 * immediately after the program's configuration script
214 * has completed and before validation is started.
215 *
216 * @a(returns) Returns nothing.
217 *
218 * @a(throws) `Error` exceptions are thrown for fatal errors.
219 */
220 function close();
221
222 /*!
223 * ======== validate ========
224 * Validate this package after the model's state is "sealed".
225 *
226 * This function is called to validate the package's state in the
227 * curent model. It can verify semantic constraints and optionally
228 * throw exceptions to prevent the configuration step from completing.
229 *
230 * For example, a package that needs to assert incompatibility with
231 * certain versions of prerequisite packages can check the versions in
232 * this function and throw an exception if they are known to be
233 * incompatible with the current package.
234 *
235 * This method must not modify the model.
236 *
237 * The default implementation of this function is a nop.
238 *
239 * @a(context) 240 * @p(dlist) 241 * - `this`
242 * The current package's `xdc.IPackage.Module` object
243 * immediately after the program's configuration script
244 * has completed and before generation started.
245 *
246 * @a(returns) Returns nothing.
247 *
248 * @a(throws) `Error` exceptions are thrown for fatal errors.
249 */
250 function validate();
251
252 /*!
253 * ======== exit ========
254 * Exit this package after the model has been successfully validated.
255 *
256 * The default implementation of this function is a nop.
257 *
258 * @a(context) 259 * @p(dlist) 260 * - `this`
261 * The current package's `xdc.IPackage.Module` object
262 * immediately after the program's configuration script
263 * has completed and after generation has completed.
264 *
265 * @a(returns) Returns nothing.
266 *
267 * @a(throws) `Error` exceptions are thrown for fatal errors.
268 */
269 function exit();
270
271 /*!
272 * ======== getLibs ========
273 * Get the libraries necessary to use this package
274 *
275 * This function is called during the configuration model's generation
276 * phase (after a program's configuration script completes and all
277 * imported packages are closed) and is responsible for returning a list
278 * of libraries (or object files) that are needed to link the program
279 * being configured.
280 *
281 * If the package produces one (or no) library for the target for which
282 * the executable is being built, the default implementation of this
283 * function simply returns the name of this library (or `null`).
284 *
285 * If the package produces more than one library for the given target, the
286 * default implementation of this function returns the following library
287 * name:
288 * @p(code) 289 * lib/<package_name>.a<target_suffix>
290 * @p 291 * where `<package_name>` is the name of the package (e.g., "ti.bios")
292 * and `<target_suffix>` is the {@link xdc.bld.ITarget#suffix} property
293 * of the target used to build the executable.
294 *
295 * @param(prog) the configuration model program object
296 * (`{@link xdc.cfg.Program}`) after the program's
297 * configuration script has completed.
298 *
299 * @a(context) 300 * @p(dlist) 301 * - `this`
302 * The current package's `xdc.IPackage.Module` object
303 * after the program's configuration script has completed.
304 * - `Program`
305 * The Configuration model program object
306 * (`{@link xdc.cfg.Program}`) after the program's configuration
307 * script has completed.
308 *
309 * @a(returns) Returns a string of ';' delimited object (or library) file
310 * names that are added to the list of things to link to
311 * create the program. The file names are absolute or
312 * relative to the package's base. All white space is
313 * treated as part of the file name. If the files named do
314 * not exist, a fatal error occurs and configuration
315 * terminates.
316 *
317 * If `null` or empty (""), then no libraries or objects are
318 * required for this package.
319 *
320 * @a(throws) `Error` exceptions are thrown for fatal errors.
321 */
322 function getLibs(prog);
323
324 /*!
325 * ======== getSects ========
326 * Get package-specific linker section data.
327 *
328 * This function is called during the configuration model's generation
329 * phase (after a program's configuration script completes) and is
330 * responsible for returning a template file name that is used to
331 * generate package-specific linker command file statements.
332 *
333 * @a(context) 334 * @p(dlist) 335 * - `this`
336 * The current package's `xdc.IPackage.Module` object
337 * after the program's configuration script has completed.
338 *
339 * - `Program`
340 * The Configuration model program object
341 * (`{@link xdc.cfg.Program}`) after program's configuration
342 * script has completed and all packages have validated the
343 * correctness of the configuration.
344 *
345 * @a(returns) Returns the path name of template file. The path name
346 * must relative to the package path or an absolute path.
347 *
348 * If `null` is returned, no data is generated.
349 *
350 * The template is evaluated in a context where the `this`
351 * pointer is the package object.
352 *
353 * @a(throws) `Error` exceptions are thrown for fatal errors.
354 */
355 function getSects();
356 }
357 /*
358 * @(#) xdc; 1, 1, 1,208; 6-9-2009 20:07:55; /db/ztree/library/trees/xdc-t50x/src/packages/
359 */
360