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