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