1 2 3 4 5 6 7 8 9 10 11
12 /*!
13 * ======== Main ========
14 * Command-line configuration tool
15 *
16 * This command allows RTSC content, in the form of reusable modules built
17 * using the XDCtools tooling, to be imported into a system integrator's
18 * embedded application. It is the recommended method for integrating RTSC
19 * content into non-RTSC application build environments.
20 *
21 * Configuro lets the system integrator identify and customize the RTSC
22 * content they wish to use, and computes a set of libraries, command-line
23 * flags and other artifacts to include in their application build. By
24 * changing the values of configuration settings, the integrator can
25 * trade off the functionality, memory footprint, and even performance of
26 * the RTSC content to best meet the needs of their application.
27 *
28 * @a(INPUTS)
29 * @p(dlist)
30 * - `infile.cfg`
31 * A user-supplied configuration script that names a set of RTSC
32 * modules, and optionally changes their configuration settings.
33 * @p
34 *
35 * @a(OUTPUTS)
36 * @p(dlist)
37 * - `outdir/`
38 * A directory containing all generated build artifacts.
39 * - `outdir/compiler.opt`
40 * A file containing C compiler command-line flags. These flags must
41 * included on the compiler command line for any C source file that
42 * directly accesses the RTSC content. The flags define the header file
43 * include paths, and machine-mode compiler flags to ensure object code
44 * compatibility between all included content.
45 * - `outdir/linker.cmd`
46 * A file containing linker command-line flags. These flags must be
47 * included on the linker command line for the final link of the
48 * application. The flags list needed libraries and object files,
49 * and on some platforms define the embedded system memory map.
50 * @p
51 *
52 * For example:
53 * @p(code)
54 * xs xdc.tools.configuro myconfig.cfg
55 * @p
56 */
57 metaonly module Main inherits xdc.tools.ICmd {
58
59 /*!
60 * usage help message
61 */
62 override config String usage[] = [
63 '[-v | -q]',
64 '[-@ optionsfile]',
65 '[-o outdir]',
66 '[-b config_bld | -c codegen_dir | --cb]',
67 '[-t target] [-p platform[:instance]] [-r profile]',
68 '[-Dname=value]',
69 '[-w | -x regexp]',
70 '[--rtsName pkg_name]',
71 '[--cfgArgs args_string]',
72 '[--linkTemplate linker_template]',
73 '[--pkg] [--generationOnly]',
74 '[--compileOptions compile_options_string]',
75 '[--linkOptions linker_options_string]',
76 '[--oc compiler.opt] [--ol linker.cmd]',
77 'infile.cfg'
78 ];
79
80 instance:
81 /*!
82 * Pathname of the output directory
83 *
84 * A directory containing the generated build artifacts, in particular
85 * the `compiler.opt` and `linker.cmd` files.
86 *
87 * The last component of the output directory path must be a valid
88 * ANSI C identifier; i.e., it must consist entirely of alphanumeric or
89 * '_' characters and must not start with a number. So, the names
90 * '0app' and 'app-test' are not valid but '0app/config' and
91 * 'app-test/config' are valid.
92 *
93 * By default, the output directory has the same name as the
94 * configuration script, minus the `.cfg` extension, within the same
95 * parent directory as this script. As a result, the directory name
96 * constraint above applies to the name of the configuration script.
97 */
98 @CommandOption("o")
99 config String output = null;
100
101 /*!
102 * Name of the RTSC target module
103 *
104 * The name of a RTSC target module to use, for example
105 * `ti.targets.C64P`.
106 *
107 * If no `config.bld` file is given, then this is a required
108 * parameter.
109 *
110 * If a `config.bld` file is given then this parameter is optional,
111 * and by default the target will be
112 * {@link xdc.bld.BuildEnvironment#targets `Build.targets[0]`} from the
113 * user's `config.bld`. If `Build.targets` contains more than one entry,
114 * then this option can be used to override that default.
115 */
116 @CommandOption("t")
117 config String target = null;
118
119 /*!
120 * Root directory of the code generation tools
121 *
122 * The path to the installation directory of the compiler and linker
123 * for the selected target. The definition of "installation directory"
124 * can vary from compiler to compiler, but is most commonly the
125 * directory that contains a "bin" subdirectory.
126 *
127 * If no `config.bld` file is given, then this is a required
128 * parameter.
129 *
130 * If a `config.bld` file is given then this parameter is optional,
131 * and by default the compiler will be the one configured there.
132 * This option can still be used, to override the default established
133 * in `config.bld`.
134 */
135 @CommandOption("c")
136 config String rootdir = null;
137
138 /*!
139 * Name of the RTSC platform package (and optionally instance)
140 *
141 * The name of a RTSC platform package to use, using the syntax
142 * `my.pkg.name` or `my.pkg.name:instanceName`. For example,
143 * `ti.platforms.sim64Pxx` or `ti.platforms.generic:custom`.
144 *
145 * This is an optional parameter, and by default the platform is
146 * the one that the selected target names as its default. The user
147 * may override this default in their `config.bld` or by using this
148 * parameter.
149 *
150 * The optional `:instanceName` suffix names a pre-configured variant
151 * of the platform, which can be set up either in the user's
152 * `config.bld` or in the platform package itself. For more details, see
153 * {@link xdc.bld.BuildEnvironment#platformTable `Build.platformTable`}
154 * and the {@link xdc.platform.IPlatform `IPlatform`} interface.
155 */
156 @CommandOption("p")
157 config String platform = null;
158
159 /*!
160 * Build profile to use
161 *
162 * The name of the build profile to use for the RTSC content, for
163 * example 'release' or 'debug'. The list of allowed profiles is
164 * determined by the RTSC target module named.
165 */
166 @CommandOption("r")
167 config String profile = 'release';
168
169 /*!
170 * Read build environment from the named `config.bld` file
171 *
172 * A `config.bld` file can optionally be used to hold the values
173 * of the target, compiler root directory, platform, and other
174 * more advanced options. This is a convenient way to share a common
175 * build environment between multiple projects.
176 *
177 * The format of the file is JavaScript statements with the XDCscript
178 * extensions. The script should set the properties of the
179 * {@link xdc.bld.BuildEnvironment `Build`} global object.
180 *
181 * If no `config.bld` file is given then the target and compiler
182 * root directory are required command-line parameters.
183 */
184 @CommandOption("b")
185 config String configbld = null;
186
187 /*!
188 * Use a `config.bld` found along the package path
189 *
190 * Find a `config.bld` by searching the package path, instead of
191 * via an explicit pathname. Looks for a file named `config.bld` in
192 * any of the directories named along the package path, in order. The
193 * directories are not searched recursively.
194 */
195 @CommandOption("cb")
196 config Bool searchForConfigBld = false;
197
198 /*!
199 * Set a Java property in the configuration script
200 *
201 * Allows values to be injected from the command line into the
202 * `config.bld` file. For example, the option `-Dmyprop=myval`
203 * creates a property named `myprop` with string value `"myval"`.
204 * This can be read in `config.bld` using the XDCscript syntax
205 * `environment["myprop"]`.
206 */
207 @CommandOption("D")
208 config String defines[] = [];
209
210 /*!
211 * Set the name of the RTSC runtime package
212 *
213 * The name of a package containing pre-built libraries containing
214 * the {@link xdc.runtime} modules. If this parameter is `null` (or
215 * `undefined`) the name of the rts package is taken from the target
216 * (`{@link xdc.bld.ITarget#rtsName}`). If this parameter is set to
217 * the empty string (""), then no rts package is included in the
218 * configuration. Finally, if this parameter is non-`null` and
219 * non-empty, it should be the name of a package along the package
220 * path that can supply pre-built versions of the modules in the
221 * `{@link xdc.runtime}` package.
222 *
223 * @see xdc.bld.ITarget#rtsName
224 * @see xdc.bld.Executable#Attrs
225 */
226 @CommandOption("rtsName")
227 config String rtsName = null;
228
229 /*!
230 * ======== cfgArgs ========
231 * Optional arguments passed to configuration script
232 *
233 * This option lets the user pass values into the configuration script
234 * from the command line. The argument is an expression in JavaScript
235 * syntax. Its value is available in the configuration script under the
236 * name `Program.build.cfgArgs`.
237 *
238 * The JavaScript expression is evaluated in the configuration domain
239 * after the platform package is imported, immediately before calling
240 * the user's configuration script.
241 *
242 * This string has the same effect as the `cfgArgs` string in
243 * `{@link xdc.bld.Executable#Attrs}`.
244 *
245 * You can pass multiple values to configuration scripts using the
246 * syntax of a JavaScript `Object` constant:
247 * @p(code)
248 * xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ... app.cfg
249 * @p
250 *
251 * The configuration script can read the various fields as, e.g.:
252 * @p(code)
253 * if (Program.build.cfgArgs.foo == "hello") {
254 * :
255 * }
256 * @p
257 *
258 * @a(Note)
259 * Different command line shells, such as UNIX `bash` verses Windows
260 * `cmd.exe`, interpret quotes on the command line very differently.
261 * As a result, the syntax necessary to pass a string such as "hello"
262 * to `configuro` can vary depending on the shell you use.
263 *
264 * For most UNIX shells, it is possible to use single quotes around the
265 * use of double quotes as in the example above. However, since Windows
266 * `cmd.exe` does not treat the single quote as a special character, it
267 * is necessary to use a backslash, '\', to ensure that the double quote
268 * characters are passed to the configuro tool.
269 *
270 * Windows `cmd.exe`:
271 * @p(code)
272 * xs xdc.tools.configuro --cfgArgs "{foo:\"hello\", bar:2}" ...
273 * @p
274 *
275 * UNIX `bash`, `ksh`, `csh`, ...:
276 * @p(code)
277 * xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ...
278 * @p
279 *
280 * @see xdc.bld.Executable#Attrs
281 */
282 @CommandOption("cfgArgs")
283 config String cfgArgs = null;
284
285 /*!
286 * Linker command file template
287 *
288 * If this option is provided it overrides the template supplied by
289 * the platform, giving the caller complete control over the generated
290 * linker command file.
291 *
292 * @see xdc.cfg.Program#linkTemplate
293 */
294 @CommandOption("linkTemplate")
295 config String linkTemplate = null;
296
297 /*!
298 * Show verbose details during build
299 *
300 * This option produces the same verbose output as the `xdc` command
301 * with the `XDCOPTIONS=v` parameter.
302 */
303 @CommandOption("v")
304 config Bool verbose = false;
305
306 /*!
307 * Minimize details during build
308 *
309 * This option produces the same output as the `xdc` command
310 * with the `XDCOPTIONS=qq` parameter.
311 */
312 @CommandOption("q")
313 config Bool quiet = false;
314
315 /*!
316 * Exclude packages matching regexp from compatibility checking
317 *
318 * A JavaScript regular expression that is used to select packages that
319 * should be excluded from the set of packages checked during
320 * configuration.
321 *
322 * @see xdc.cfg
323 */
324 @CommandOption("x")
325 config String exclude = null;
326
327 /*!
328 * Treat package version incompatibilites as warnings
329 *
330 * If set to "`true`", force any incompatibilities detected to be
331 * treated as warnings only; otherwise incompatibilities are fatal.
332 *
333 * @see xdc.cfg
334 */
335 @CommandOption("w")
336 config Bool warn = false;
337
338 /*!
339 * Create the build model generated output files but do not build
340 *
341 * This option creates the output directory and key generated files
342 * but does not process the user's configuration script. It is used
343 * by internal tooling to snapshot the RTSC build settings implied by
344 * the configuro command line parameters.
345 */
346 @CommandOption("pkg")
347 config Bool mkPkgOnly = false;
348
349 /*!
350 * Create the configuration generated source files but do not build
351 *
352 * This option runs the configuration step but does not compile the
353 * generated source files. This option is used
354 * by internal tooling to eliminate unnecessary build steps.
355 */
356 @CommandOption("generationOnly")
357 config Bool generationOnly = false;
358
359 /*!
360 * Add compile options for C files in the configuration package
361 *
362 * This option accepts one or more compiler options that are added to
363 * the compiler command line when compiling C files in the generated
364 * configuration package.
365 * If multiple compiler options are given, the whole string containing
366 * options must be surrounded by quotes.
367 */
368 @CommandOption("compileOptions")
369 config String compileOptions = "";
370
371 /*!
372 * Add linker options for libraries in the configuration package
373 *
374 * This option accepts one or more linker options which are used to
375 * pull in the correct libraries during link.
376 * If multiple linker options are given, the whole string containing
377 * options must be surrounded by quotes.
378 */
379 @CommandOption("linkOptions")
380 config String linkOptions = "";
381
382 /*!
383 * Set the name of the compiler options file (default is "compiler.opt")
384 */
385 @CommandOption("oc")
386 config String compilerOptionsFile = "compiler.opt";
387
388 /*!
389 * Set the name of the linker command file (default is "linker.cmd")
390 */
391 @CommandOption("ol")
392 config String linkerCommandFile = "linker.cmd";
393
394 /*!
395 * Generate and build the configuration package
396 */
397 int gen(String infile);
398 }