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