1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
33
34 35 36
37 package ti.sdo.tools.build;
38
39 import xdc.bld.Executable;
40 import xdc.bld.Library;
41
42
43 /*!
44 * ======== PackageBuildHelp ========
45 * Common package build support
46 *
47 * This module is a helper module for your package build script
48 * (`package.bld`). It provides a high-level interface for defining
49 * your libraries and executables, and provides functions to generate
50 * your package interface (makefiles).
51 */
52
53 metaonly module PackageBuildHelp {
54
55 /*!
56 * ======== LibAttrs ========
57 * Attributes for a library instances
58 *
59 * An array of this type is passed to `PackageBuildHelp.makeLibraries`.
60 * Each element in the array describes the build properties for the
61 * library. Multiple library instances may be produced from a single
62 * `LibAttrs` element. For example, a library instance may be build for
63 * different profiles and/or different targets.
64 *
65 * The `icw` array is used to limit which targets will be use for
66 * building the library. For example, if you have a library which
67 * should only be built for ARM, but you know the build model has a
68 * target for DSP, then set the `icw` array as follows to build only
69 * for the ARM targets and exclude the DSP targets.
70 *
71 * @p(code)
72 * icw: [ "v5T" ]
73 * @p(text)
74 * Note that all ARM targets which accept v5T as an input isa will
75 * build the library using their output isa. For example, if the build
76 * model contains both GCArmv5T (isa=v5T) and GCArmv6 (isa=v6) targets,
77 * then both targets will build this library using their respective
78 * isa. However, if the build model contains the C64P (isa=64P) target,
79 * it will not be used to build this library because it cannot accept
80 * the v5T isa.
81 *
82 * @a(See Also)
83 * {@link #makeLibraries} -- for additional examples
84 *
85 * @field(name) The name of the library with an optional
86 * directory prefix.
87 *
88 * @field(sources) An array of source files to be compiled
89 * for the library.
90 *
91 * @field(icw) An array of strings listing isa's that a given target
92 * must be able to accept. Use this property to limit which targets
93 * will be used to build this library. See Details below.
94 *
95 * @field(libAttrs) An xdc.bld.Library.Attrs object used to specify
96 * optional attributes of the library instance.
97 */
98 struct LibAttrs {
99 String name; /*! library name */
100 String sources[]; /*! source files to build */
101 String icw[]; /*! array of input isa's */
102 Library.Attrs libAttrs; /*! library attributes */
103 };
104
105 /*!
106 * ======== ProgAttrs ========
107 * Attributes for an executable instance
108 *
109 * An array of this type is passed to `PackageBuildHelp.makeExecutables`.
110 * Each element in the array describes the build properties for the
111 * executable. Multiple executable instances may be produced from a
112 * single `ProgAttrs` element. For example, an executable instance may
113 * be build for different profiles, targets, and platforms.
114 *
115 * The `icw` array is used to limit which targets will be use for
116 * building the executable. For example, if you have an executable
117 * which should only be built for ARM, but you know the build model
118 * has a target for DSP, then set the `icw` array as follows to build
119 * only for the ARM targets and exclude the DSP targets.
120 *
121 * @p(code)
122 * icw: [ "v5T" ]
123 * @p(text)
124 * Note that all ARM targets which accept v5T as an input isa will
125 * build the executable using their output isa. For example, if the build
126 * model contains both GCArmv5T (isa=v5T) and GCArmv6 (isa=v6) targets,
127 * then both targets will build this executable using their respective
128 * isa. However, if the build model contains the C64P (isa=64P) target,
129 * it will not be used to build this executable because it cannot accept
130 * the v5T isa.
131 *
132 * @p(text)
133 * Note: this property is more useful to building libraries than
134 * executables. The `isas` property is usually used when building
135 * executables.
136 *
137 * @p(text)
138 * The `isas` array is used to control the executable's isa. Only those
139 * targets which have an output isa that matches any entry in this array
140 * will be used to build the executable. For example, if you have a
141 * program which should be built for ARM v5T or ARM v6 but not for ARM
142 * v7A, but you know the build model has targets for all three, then
143 * set the `isas` array as follows to get the desired output.
144 *
145 * @p(code)
146 * isas: [ "v5T", "v6" ]
147 * @p(text)
148 * Note: although the GCArmv7A target accepts v5T and v6 isa as input,
149 * it will not participate in the build because it outputs v7A isa which
150 * not specified in the `isas` array.
151 *
152 * @a(See Also)
153 * {@link #makeExecutables} -- for additional examples
154 *
155 * @field(name) The name of the executable with an optional
156 * directory prefix.
157 *
158 * @field(sources) An array of strings listing the source files
159 * to be compiled for the executables.
160 *
161 * @field(platforms) An array of platform (and/or platform instance)
162 * names which are supported by this program. When this property is
163 * specified, the executable is built only for those platforms listed
164 * by this property, otherwise, the executable is built for all
165 * platforms specified in the target's platforms array property.
166 *
167 * @field(icw) An array of strings listing isa's which are compatible
168 * for this executable. Use this property to limit which isa's the
169 * program will be built for.
170 *
171 * @field(isas) An array of isa's the program should be built for.
172 *
173 * @field(execAttrs) An xdc.bld.Executable.Attrs object used to specify
174 * optional attributes of the executable instance.
175 */
176 struct ProgAttrs {
177 String name; /*! executable name */
178 String sources[]; /*! source files to build */
179 String platforms[]; /*! array of platform names */
180 String icw[]; /*! array of input isa's */
181 String isas[]; /*! array of output isa's */
182 Executable.Attrs execAttrs; /*! executble attributes */
183 };
184
185 /*!
186 * ======== fileArray ========
187 * Record all source files and config scripts in given array
188 *
189 * When this config param is assigned to a string array, each call
190 * to `PackageBuildHelp.makeExecutables` and
191 * `PackageBuildHelp.makeLibraries` will append all given source files
192 * and config scripts to the array.
193 */
194 config Any fileArray;
195
196 /*!
197 * ======== skipExec ========
198 * Skip given program if function returns true
199 *
200 * If you don't want your package to build a given executable based
201 * on certain build attributes, set this config param to a function
202 * defined in your package.bld script which returns true for any
203 * executable you do not want to build.
204 *
205 * This function can also be used to modify the program object just
206 * before building it. The following example show a function which
207 * adds a source file depending on the target.os property. It always
208 * returns false, because we don't want to skip the executable.
209 *
210 * @p(code)
211 * PackageBuildHelp.skipExec = function(prog, targ, platName)
212 * {
213 * if (targ.os == undefined) {
214 * prog.sources.push("main_BIOS.c");
215 * }
216 * else {
217 * prog.sources.push("main_native.c");
218 * }
219 * return false;
220 * }
221 *
222 * @b(ARGUMENTS)
223 * @p(dlist)
224 * - prog
225 * (`PackageBuildHelp.ProgAttrs`) An element from the `progAry`
226 * argument passed to the `PackageBuildHelp.makeExecutables`
227 * function.
228 * - targ
229 * (`xdc.bld.ITarget.Module`) The target used for building the
230 * current executable.
231 * - platName
232 * (`String`) The name of the platform used for the current
233 * executable.
234 * @p(text)
235 */
236 config Bool skipExec(ProgAttrs, xdc.bld.ITarget.Module, String);
237
238 /*!
239 * ======== skipLib ========
240 * Skip given library if function returns true
241 *
242 * If you don't want your package to build a given library based
243 * on certain build attributes, set this config param to a function
244 * defined in your package.bld script which returns true for any
245 * library you do not want to build.
246 *
247 * This function can also be used to modify the library object just
248 * before building it. The following example show a function which
249 * adds a source file depending on the target.os property. It always
250 * returns false, because we don't want to skip the library.
251 *
252 * @p(code)
253 * PackageBuildHelp.skipLib = function(lib, targ)
254 * {
255 * if (targ.os == undefined) {
256 * lib.sources.push("util_BIOS.c");
257 * }
258 * else {
259 * lib.sources.push("util_native.c");
260 * }
261 * return false;
262 * }
263 *
264 * @p(text)
265 * This example show a function which builds the library only if the
266 * library name contains the string "syslink" and the target's
267 * os (Operating System) property matches "Linux".
268 *
269 * @p(code)
270 * PackageBuildHelp.skipLib = function(lib, targ)
271 * {
272 * if (lib.name.match(/syslink/)) {
273 * return targ.os != "Linux" ? true : false;
274 * }
275 * else {
276 * return false;
277 * }
278 * }
279 *
280 * @b(ARGUMENTS)
281 * @p(dlist)
282 * - lib
283 * (`PackageBuildHelp.LibAttrs`) An element from the `libAry`
284 * argument passed to the `PackageBuildHelp.makeLibraries` function.
285 * - targ
286 * (`xdc.bld.ITarget.Module`) The target used for building the
287 * current library.
288 * @p(text)
289 */
290 config Bool skipLib(LibAttrs, xdc.bld.ITarget.Module);
291
292 /*!
293 * ======== usePlatformInstanceName ========
294 * Use platform instance name when constructing executable pathname
295 *
296 * The executable pathname is constructed using the following
297 * elements: 'bin', platform name, directory prefix used in
298 * program name, profile, and the executable basename. These
299 * elements are combined in the following pattern:
300 *
301 * bin/platform/prefix/profile/name
302 *
303 * This config param controls the platform part of the pathname
304 * when using platform instances. When set to true, the platform
305 * instance name is used, otherwise, the platform base name is used.
306 * When using the default platform instance the platform base name
307 * is always used.
308 */
309 config Bool usePlatformInstanceName = false;
310
311 /*!
312 * ======== skipPlatform ========
313 * Skip given platform if function returns true
314 *
315 * If you do not want your package to build for a particular
316 * platform, set this config param to a function defined in your
317 * `package.bld` script which returns true for any platform you wish
318 * to skip.
319 *
320 * The following example shows a function which skips any platform
321 * named `ti.platforms.evm3530`.
322 *
323 * @p(code)
324 * PackageBuildHelp.skipPlatform = function(platName, targ)
325 * {
326 * return platName.match(/ti.platforms.evm3530/) ? true : false;
327 * }
328 *
329 * @b(ARGUMENTS)
330 * @p(dlist)
331 * - platName
332 * (`String`) The name of the platform used for the current
333 * executable.
334 * - targ
335 * (`xdc.bld.ITarget.Module`) The target used for building the
336 * current executable.
337 * @p(text)
338 */
339 config Bool skipPlatform(String, xdc.bld.ITarget.Module);
340
341 /*!
342 * ======== skipTarget ========
343 * Skip given target if function returns true
344 *
345 * If you do not want your package to build for a particular
346 * target, set this config param to a function defined in your
347 * package.bld script which returns true for any target you wish
348 * to skip.
349 *
350 * The following example shows a function which skips any target
351 * named `UCArm9`.
352 *
353 * @p(code)
354 * PackageBuildHelp.skipTarget = function(targ)
355 * {
356 * return targ.name.match(/UCArm9/) ? true : false;
357 * }
358 *
359 * @b(ARGUMENTS)
360 * @p(dlist)
361 * - targ
362 * (`xdc.bld.ITarget.Module`) The target used for building the
363 * current library or executable.
364 * @p(text)
365 */
366 config Bool skipTarget(xdc.bld.ITarget.Module);
367
368 /*!
369 * ======== makeExecutables ========
370 * Add executables to the build model
371 *
372 * This function iterates over the given `progAry` and adds each element
373 * to the build model, possibly multiple times to cover all combinations
374 * of platforms, targets, and profiles.
375 *
376 * The following code adds a program called `program` to the build model
377 * for all combinations of platforms, targets, and profiles in the build
378 * model.
379 *
380 * @p(code)
381 * var PackageBuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
382 * var progArray = new Array();
383 *
384 * progArray.push(
385 * new PackageBuildHelp.ProgAttrs({
386 * name: "program",
387 * sources: [ "main.c", "core.c" ],
388 * execAttrs: {
389 * cfgScript: "server.cfg"
390 * }
391 * })
392 * );
393 *
394 * PackageBuildHelp.makeExecutables(progArray, arguments);
395 *
396 * @p(text)
397 * You can pass an array of profiles as the third (optional)
398 * argument to `PackageBuildHelp.makeExecutables`. This is useful
399 * for limiting the number of executables to build when the target
400 * defines additional profiles.
401 *
402 * @p(code)
403 * PackageBuildHelp.makeExecutables(
404 * progArray, arguments, [ "debug", "release" ]);
405 *
406 * @p(text)
407 * You may limit the build to a single profile using the XDCARGS
408 * command line option, provided the target supports the given profile.
409 *
410 * @p(code)
411 * xdc -r XDCARGS="profile=coverage" all
412 *
413 * @p(text)
414 * You may limit the build to a single platform using the XDCARGS
415 * command line option, provided the target supports the given platform.
416 *
417 * @p(code)
418 * xdc -r XDCARGS="platform=ti.platforms.evm3530" all
419 *
420 * @p(text)
421 * The profile and platform arguments may be combined in XDCARGS by
422 * separating them with white space.
423 *
424 * @p(code)
425 * XDCARGS="profile=coverage platform=ti.platforms.evm3530"
426 *
427 * @p(text)
428 * When specifying platforms, isas, or both it is important to ensure
429 * that all possible combinations are valid. In other words, each
430 * platform specified in the `platforms` array must have a core which
431 * is either capable of executing every isa specified in the `isas`
432 * array or, if `isas` is not specified, capable of executing code
433 * generated by every target in the build model. To avoid invalid
434 * combinations, specify either or both. Use multiple `ProgAttrs`
435 * instances to cover all desired combinations.
436 *
437 * The following example builds a program for the DSP on an
438 * OMAP3530 device and the same program for the VIDEO-M3 on a DM8168
439 * device.
440 *
441 * @p(code)
442 * var BuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
443 * var progArray = new Array();
444 *
445 * progArray.push(
446 * new BuildHelp.ProgAttrs({
447 * name: "server",
448 * platforms: [ "ti.platforms.evm3530" ],
449 * isas: [ "64P" ],
450 * sources: [ "server.c", "utils.c" ]
451 * })
452 * );
453 *
454 * progArray.push(
455 * new BuildHelp.ProgAttrs({
456 * name: "server",
457 * platforms: [ "ti.platforms.evmDM8168" ],
458 * isas: [ "v7M" ],
459 * sources: [ "server.c", "utils.c" ]
460 * })
461 * );
462 *
463 * BuildHelp.makeExecutables(progArray, arguments);
464 * @p(text)
465 * Note that combining these two entries into one would generate an
466 * invalid combination. For example, there is no core on the OMAP3530
467 * capable of running the v7M isa.
468 *
469 * @param(progAry) An array of program attributes, one for each
470 * executable to build.
471 *
472 * @param(arguments) The global arguments object passed to the build
473 * script which contains the arguments assigned to the XDCARGS
474 * environment variable used by the xdc command.
475 *
476 * @param(profiles) Optional. (`String[]`) Array of profile names to
477 * build provided the target supports the profile. If not supported
478 * by the target, the profile is ignored. When omitted, all profiles
479 * defined in the target will be used. If a profile is specified in
480 * XDCARGS as described above, this parameter is ignored.
481 */
482 Void makeExecutables(
483 ProgAttrs progAry[],
484 Any arguments,
485 Any profiles = undefined
486 );
487
488 /*!
489 * ======== makeLibraries ========
490 * Add libraries to the build model
491 *
492 * This function iterates over the given `libAry` and adds each element
493 * to the build model, possibly multiple times to cover all combinations
494 * of targets and profiles.
495 *
496 * The following code adds a library called `rcm` to the build model
497 * for all combinations of targets and profiles in the build model.
498 *
499 * @p(code)
500 * var PackageBuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
501 * var libArray = new Array();
502 *
503 * libArray.push(
504 * new PackageBuildHelp.LibAttrs({
505 * name: "rcm",
506 * sources: [ "rcm.c" ],
507 * })
508 * );
509 *
510 * PackageBuildHelp.makeLibraries(libArray, arguments);
511 *
512 * @p(text)
513 * You can pass an array of profiles as the third (optional)
514 * argument to `PackageBuildHelp.makelibraries`. This is useful
515 * for limiting the number of libraries to build when the target
516 * defines additional profiles.
517 *
518 * @p(code)
519 * PackageBuildHelp.makeLibraries(
520 * libArray, arguments, [ "debug", "release" ]);
521 *
522 * @p(text)
523 * You may limit the build to a single profile using the XDCARGS
524 * command line option, provided the target supports the given profile.
525 *
526 * @p(code)
527 * xdc -r XDCARGS="profile=debug" all
528 * @p(text)
529 *
530 * @a(Examples)
531 * The following example builds the library only for ARM targets and
532 * only for the debug and release profiles.
533 *
534 * @p(code)
535 * var BuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
536 * var libArray = new Array();
537 *
538 * libArray.push(
539 * new BuildHelp.LibAttrs({
540 * name: "host",
541 * sources: [ "config_host.c" ],
542 * icw: [ "v5T" ]
543 * })
544 * );
545 *
546 * BuildHelp.makeLibraries(libArray, arguments, ["debug","release"]);
547 * @p(text)
548 * If the build model contained the GCArmv5T, GCArmv6, and C64P targets,
549 * the following libraries would be produced. Note, the C64P target is
550 * excluded.
551 *
552 * @p(code)
553 * lib/debug/host.av5T
554 * lib/debug/host.av6
555 * lib/release/host.av5T
556 * lib/release/host.av6
557 * @p(text)
558 *
559 * @param(libAry) An array of library attributes, one for each
560 * library to build.
561 *
562 * @param(arguments) The global arguments object passed to the build
563 * script which contains the arguments assigned to the XDCARGS
564 * environment variable used by the xdc command.
565 *
566 * @param(profiles) Optional. (`String[]`) Array of profile names to
567 * build provided the target supports the profile. If not supported
568 * by the target, the profile is ignored. When omitted, all profiles
569 * defined in the target will be used. If a profile is specified in
570 * XDCARGS as described above, this parameter is ignored.
571 */
572 Void makeLibraries(
573 LibAttrs libAry[],
574 Any arguments,
575 Any profiles = undefined
576 );
577 }
578 579 580 581
582