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