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