1 /* --COPYRIGHT--,EPL
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 * --/COPYRIGHT--*/
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 metaonlymodule Main inherits xdc.tools.ICmd {
58
59 /*!
60 * usage help message
61 */
62 overrideconfig 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 '[--tcf] [--bios5] [--pkg] [--generationOnly]',
74 '[--compileOptions compile_options_string]',
75 '[--oc compiler.opt] [--ol linker.cmd]',
76 'infile.cfg'
77 ];
78
79 instance:
80 /*!
81 * Pathname of the output directory
82 *
83 * A directory containing the generated build artifacts, in particular
84 * the `compiler.opt` and `linker.cmd` files.
85 *
86 * The last component of the output directory path must be a valid
87 * ANSI C identifier; i.e., it must consist entirely of alphanumeric or
88 * '_' characters and must not start with a number. So, the names
89 * '0app' and 'app-test' are not valid but '0app/config' and
90 * 'app-test/config' are valid.
91 *
92 * By default, the output directory has the same name as the
93 * configuration script, minus the `.cfg` extension, within the same
94 * parent directory as this script. As a result, the directory name
95 * constraint above applies to the name of the configuration script.
96 */
97 @CommandOption("o")
98 config String output = null;
99
100 /*!
101 * Name of the RTSC target module
102 *
103 * The name of a RTSC target module to use, for example
104 * `ti.targets.C64P`.
105 *
106 * If no `config.bld` file is given, then this is a required
107 * parameter.
108 *
109 * If a `config.bld` file is given then this parameter is optional,
110 * and by default the target will be
111 * {@link xdc.bld.BuildEnvironment#targets `Build.targets[0]`} from the
112 * user's `config.bld`. If `Build.targets` contains more than one entry,
113 * then this option can be used to override that default.
114 */
115 @CommandOption("t")
116 config String target = null;
117
118 /*!
119 * Root directory of the code generation tools
120 *
121 * The path to the installation directory of the compiler and linker
122 * for the selected target. The definition of "installation directory"
123 * can vary from compiler to compiler, but is most commonly the
124 * directory that contains a "bin" subdirectory.
125 *
126 * If no `config.bld` file is given, then this is a required
127 * parameter.
128 *
129 * If a `config.bld` file is given then this parameter is optional,
130 * and by default the compiler will be the one configured there.
131 * This option can still be used, to override the default established
132 * in `config.bld`.
133 */
134 @CommandOption("c")
135 config String rootdir = null;
136
137 /*!
138 * Name of the RTSC platform package (and optionally instance)
139 *
140 * The name of a RTSC platform package to use, using the syntax
141 * `my.pkg.name` or `my.pkg.name:instanceName`. For example,
142 * `ti.platforms.sim64Pxx` or `ti.platforms.generic:custom`.
143 *
144 * This is an optional parameter, and by default the platform is
145 * the one that the selected target names as its default. The user
146 * may override this default in their `config.bld` or by using this
147 * parameter.
148 *
149 * The optional `:instanceName` suffix names a pre-configured variant
150 * of the platform, which can be set up either in the user's
151 * `config.bld` or in the platform package itself. For more details, see
152 * {@link xdc.bld.BuildEnvironment#platformTable `Build.platformTable`}
153 * and the {@link xdc.platform.IPlatform `IPlatform`} interface.
154 */
155 @CommandOption("p")
156 config String platform = null;
157
158 /*!
159 * Build profile to use
160 *
161 * The name of the build profile to use for the RTSC content, for
162 * example 'release' or 'debug'. The list of allowed profiles is
163 * determined by the RTSC target module named.
164 */
165 @CommandOption("r")
166 config String profile = 'release';
167
168 /*!
169 * Read build environment from the named `config.bld` file
170 *
171 * A `config.bld` file can optionally be used to hold the values
172 * of the target, compiler root directory, platform, and other
173 * more advanced options. This is a convenient way to share a common
174 * build environment between multiple projects.
175 *
176 * The format of the file is JavaScript statements with the XDCscript
177 * extensions. The script should set the properties of the
178 * {@link xdc.bld.BuildEnvironment `Build`} global object.
179 *
180 * If no `config.bld` file is given then the target and compiler
181 * root directory are required command-line parameters.
182 */
183 @CommandOption("b")
184 config String configbld = null;
185
186 /*!
187 * Use a `config.bld` found along the package path
188 *
189 * Find a `config.bld` by searching the package path, instead of
190 * via an explicit pathname. Looks for a file named `config.bld` in
191 * any of the directories named along the package path, in order. The
192 * directories are not searched recursively.
193 */
194 @CommandOption("cb")
195 config Bool searchForConfigBld = false;
196
197 /*!
198 * Set a Java property in the configuration script
199 *
200 * Allows values to be injected from the command line into the
201 * `config.bld` file. For example, the option `-Dmyprop=myval`
202 * creates a property named `myprop` with string value `"myval"`.
203 * This can be read in `config.bld` using the XDCscript syntax
204 * `environment["myprop"]`.
205 */
206 @CommandOption("D")
207 config String defines[] = [];
208
209 /*!
210 * Set the name of the RTSC runtime package
211 *
212 * The name of a package containing pre-built libraries containing
213 * the {@link xdc.runtime} modules. If this parameter is `null` (or
214 * `undefined`) the name of the rts package is taken from the target
215 * (`{@link xdc.bld.ITarget#rtsName}`). If this parameter is set to
216 * the empty string (""), then no rts package is included in the
217 * configuration. Finally, if this parameter is non-`null` and
218 * non-empty, it should be the name of a package along the package
219 * path that can supply pre-built versions of the modules in the
220 * `{@link xdc.runtime}` package.
221 *
222 * @see xdc.bld.ITarget#rtsName
223 * @see xdc.bld.Executable#Attrs
224 */
225 @CommandOption("rtsName")
226 config String rtsName = null;
227
228 /*!
229 * ======== cfgArgs ========
230 * Optional arguments passed to configuration script
231 *
232 * This option lets the user pass values into the configuration script
233 * from the command line. The argument is an expression in JavaScript
234 * syntax. Its value is available in the configuration script under the
235 * name `Program.build.cfgArgs`.
236 *
237 * The JavaScript expression is evaluated in the configuration domain
238 * after the platform package is imported, immediately before calling
239 * the user's configuration script.
240 *
241 * This string has the same effect as the `cfgArgs` string in
242 * `{@link xdc.bld.Executable#Attrs}`.
243 *
244 * You can pass multiple values to configuration scripts using the
245 * syntax of a JavaScript `Object` constant:
246 * @p(code) 247 * xs xdc.tools.configuro --cfgArgs "{foo:'hello';bar:2}" ... app.cfg
248 * @p 249 *
250 * The configuration script can read the various fields as, e.g.:
251 * @p(code) 252 * if (Program.build.cfgArgs.foo == "hello") {
253 * :
254 * }
255 * @p 256 *
257 * Note the use of single quotes around the string value `'hello'` on
258 * the command line. This is the easiest way to quote a JavaScript
259 * string constant that is compatible with the enclosing double
260 * quotes, which are for the benefit of the command line shell.
261 *
262 * @see xdc.bld.Executable#Attrs
263 */
264 @CommandOption("cfgArgs")
265 config String cfgArgs = null;
266
267 /*!
268 * Linker command file template
269 *
270 * If this option is provided it overrides the template supplied by
271 * the platform, giving the caller complete control over the generated
272 * linker command file.
273 *
274 * @see xdc.cfg.Program#linkTemplate
275 */
276 @CommandOption("linkTemplate")
277 config String linkTemplate = null;
278
279 /*!
280 * Show verbose details during build
281 *
282 * This option produces the same verbose output as the `xdc` command
283 * with the `XDCOPTIONS=v` parameter.
284 */
285 @CommandOption("v")
286 config Bool verbose = false;
287
288 /*!
289 * Minimize details during build
290 *
291 * This option produces the same output as the `xdc` command
292 * with the `XDCOPTIONS=qq` parameter.
293 */
294 @CommandOption("q")
295 config Bool quiet = false;
296
297 /*!
298 * Exclude packages matching regexp from compatibility checking
299 *
300 * A JavaScript regular expression that is used to select packages that
301 * should be excluded from the set of packages checked during
302 * configuration.
303 *
304 * @see xdc.cfg
305 */
306 @CommandOption("x")
307 config String exclude = null;
308
309 /*!
310 * Treat package version incompatibilites as warnings
311 *
312 * If set to "`true`", force any incompatibilities detected to be
313 * treated as warnings only; otherwise incompatibilities are fatal.
314 *
315 * @see xdc.cfg
316 */
317 @CommandOption("w")
318 config Bool warn = false;
319
320 /*!
321 * Read infile.tcf in addition to infile.cfg
322 *
323 * The .tcf file optionally configures DSP/BIOS 5.X . This allows a
324 * single program to use both DSP/BIOS 5.X and RTSC-based content.
325 */
326 @CommandOption("tcf")
327 config Bool hasTconf = false;
328
329 /*!
330 * Add the DSP/BIOS 5.X include directory to the compiler options
331 *
332 * The directory is located in "include" in package "ti.bios".
333 */
334 @CommandOption("bios5")
335 config Bool bios5Incs = false;
336
337 /*!
338 * Create the build model generated output files but do not build
339 *
340 * This option creates the output directory and key generated files
341 * but does not process the user's configuration script. It is used
342 * by internal tooling to snapshot the RTSC build settings implied by
343 * the configuro command line parameters.
344 */
345 @CommandOption("pkg")
346 config Bool mkPkgOnly = false;
347
348 /*!
349 * Create the configuration generated source files but do not build
350 *
351 * This option runs the configuration step but does not compile the
352 * generated source files. This option is used
353 * by internal tooling to eliminate unnecessary build steps.
354 */
355 @CommandOption("generationOnly")
356 config Bool generationOnly = false;
357
358 /*!
359 * Add compile options for C files in the configuration package
360 *
361 * This option accepts one or more compiler options that are added to
362 * the compiler command line when compiling C files in the generated
363 * configuration package.
364 * If multiple compiler options are given, the whole string containing
365 * options must be surrounded by quotes.
366 */
367 @CommandOption("compileOptions")
368 config String compileOptions = "";
369
370 /*!
371 * Set the name of the compiler options file (default is "compiler.opt")
372 */
373 @CommandOption("oc")
374 config String compilerOptionsFile = "compiler.opt";
375
376 /*!
377 * Set the name of the linker command file (default is "linker.cmd")
378 */
379 @CommandOption("ol")
380 config String linkerCommandFile = "linker.cmd";
381
382 /*!
383 * Generate and build the configuration package
384 */
385 int gen(String infile);
386 }