1 2 3 4 5 6 7 8 9 10 11
12 /*!
13 * ======== Main ========
14 * Command-line configuration tool for IAR Embedded Workbench
15 *
16 * This command-line tool computes the appropriate configuro options from the
17 * set of options passed from the IAR Workbench (for ex. target/platform
18 * from compile options). With these options, the xdc.tools.configuro tool
19 * is executed to compute the set of libraries, command-line flags and
20 * the other artifacts needed to build the application in IAR Workbench.
21 *
22 * @a(INPUTS)
23 * @p(dlist)
24 * - `-o outdir (Optional)`
25 * Optionally an output directory can be provided.
26 * - `-c codegen_dir`
27 * Root directory of the code generation tools.
28 * - `--device device_name_string`
29 * The name of the device.
30 * - `--compileOptions compile_options_string`
31 * The command line options passed to the compiler.
32 * - `--linkOptions linker_options_string`
33 * The command line options passed to the linker.
34 * - `--profile profile`
35 * The build profile.
36 * - `--projFile project_file (Optional)`
37 * IAR Embedded Workbench project file. This is optional when
38 * infile.cfg is passed on command line.
39 * - `infile.cfg (Optional)`
40 * A user-supplied configuration script that names a set of RTSC
41 * modules, and optionally changes their configuration settings.
42 * If provided, it will override the --projFile option.
43 * @p
44 *
45 * @a(OUTPUTS)
46 * @p(dlist)
47 * - `outdir/`
48 * A directory containing all generated build artifacts.
49 * - `outdir/compiler.defs`
50 * A file containing C compiler command-line flags. These flags must
51 * included on the compiler command line for any C source file that
52 * directly accesses the RTSC content. The flags define the header file
53 * and include paths to ensure object code compatibility between all
54 * all included content.
55 * - `outdir/linker.cmd`
56 * A file containing linker command-line flags. These flags must be
57 * included on the linker command line for the final link of the
58 * application. The flags list needed libraries and object files,
59 * and on some platforms define the embedded system memory map.
60 * @p
61 *
62 * For example:
63 * @p(code)
64 * xs iar.tools.configuro -c "<codegen_dir>" --cc "<compiler>"
65 * --device "<device_name>" --cfgArgs "<cfg_script_args>"
66 * --compileOptions "<compiler_options>" --linkOptions "<link_options>"
67 * --profile "<profile>" infile.cfg
68 * @p
69 */
70 metaonly module Main inherits xdc.tools.ICmd {
71
72 /*!
73 * usage help message
74 */
75 override config String usage[] = [
76 '[-o outdir (optional)]',
77 '[-c codegen_dir]',
78 '[--cc compiler_name_string]',
79 '[--device device_name]',
80 '[--cfgArgs args_string]',
81 '[--compileOptions compile_options_string]',
82 '[--linkOptions linker_options_string]',
83 '[--profile profile]',
84 '[--projFile project_file (optional)]',
85 'infile.cfg (optional)'
86 ];
87
88 instance:
89
90 /*!
91 * ======== output ========
92 * Pathname of the output directory
93 *
94 * A directory containing the generated build artifacts, in particular
95 * the `compiler.defs` and `linker.cmd` files.
96 *
97 * The last component of the output directory path must be a valid
98 * ANSI C identifier; i.e., it must consist entirely of alphanumeric or
99 * '_' characters and must not start with a number. So, the names
100 * '0app' and 'app-test' are not valid but '0app/config' and
101 * 'app-test/config' are valid.
102 *
103 * This is optional parameter. By default, the output directory has the
104 * name `configPkg` and will be within the `{#cfgDir}` directory.
105 */
106 @CommandOption("o")
107 config String output = "";
108
109 /*!
110 * ======== rootDir ========
111 * Root directory of the code generation tools
112 *
113 * The path to the installation directory of the compiler and linker
114 * for the selected target. The definition of "installation directory"
115 * can vary from compiler to compiler, but is most commonly the
116 * directory that contains a "bin" subdirectory.
117 */
118 @CommandOption("c")
119 config String rootDir = null;
120
121 /*!
122 * ======== compiler ========
123 * @_nodoc
124 * The name of the compiler
125 *
126 * The compiler name is required to find the target and platform
127 * xdc.tools.configuro options.
128 */
129 @CommandOption("cc")
130 config String compiler = "";
131
132 /*!
133 * ======== device ========
134 * The name of the device
135 *
136 * The device name has to be passed to the xdc.tools.configuro tool.
137 */
138 @CommandOption("device")
139 config String device = null;
140
141 /*!
142 * ======== compileOptions ========
143 * Compile options used for building C files
144 *
145 * The compiler options are required to find the target and platform
146 * options for xdc.tools.configuro.
147 */
148 @CommandOption("compileOptions")
149 config String compileOptions = null;
150
151 /*!
152 * ======== linkOptions ========
153 * Linker options used for linking libraries
154 *
155 * The linker options are required to pull in the correct libraries
156 * during link.
157 */
158 @CommandOption("linkOptions")
159 config String linkOptions = null;
160
161 /*!
162 * ======== profile ========
163 * Build profile
164 */
165 @CommandOption("profile")
166 config String profile = "";
167
168 /*!
169 * ======== cfgArgs ========
170 * Optional arguments passed to configuration script
171 *
172 * This option lets the user pass values into the configuration script
173 * from the command line. The argument is an expression in JavaScript
174 * syntax. Its value is available in the configuration script under the
175 * name `Program.build.cfgArgs`.
176 *
177 * The JavaScript expression is evaluated in the configuration domain
178 * after the platform package is imported, immediately before calling
179 * the user's configuration script.
180 *
181 * This string has the same effect as the `cfgArgs` string in
182 * `{@link xdc.bld.Executable#Attrs}`.
183 *
184 * You can pass multiple values to configuration scripts using the
185 * syntax of a JavaScript `Object` constant:
186 * @p(code)
187 * xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ... app.cfg
188 * @p
189 *
190 * The configuration script can read the various fields as, e.g.:
191 * @p(code)
192 * if (Program.build.cfgArgs.foo == "hello") {
193 * :
194 * }
195 * @p
196 *
197 * @a(Note)
198 * Different command line shells, such as UNIX `bash` verses Windows
199 * `cmd.exe`, interpret quotes on the command line very differently.
200 * As a result, the syntax necessary to pass a string such as "hello"
201 * to `configuro` can vary depending on the shell you use.
202 *
203 * For most UNIX shells, it is possible to use single quotes around the
204 * use of double quotes as in the example above. However, since Windows
205 * `cmd.exe` does not treat the single quote as a special character, it
206 * is necessary to use a backslash, '\', to ensure that the double quote
207 * characters are passed to the configuro tool.
208 *
209 * Windows `cmd.exe`:
210 * @p(code)
211 * xs xdc.tools.configuro --cfgArgs "{foo:\"hello\", bar:2}" ...
212 * @p
213 *
214 * UNIX `bash`, `ksh`, `csh`, ...:
215 * @p(code)
216 * xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ...
217 * @p
218 *
219 * @see xdc.bld.Executable#Attrs
220 */
221 @CommandOption("cfgArgs")
222 config String cfgArgs = "";
223
224 /*!
225 * ======== projFile ========
226 * IAR Embedded project file.
227 *
228 * This file is searched for the RTSC configuration file (.cfg).
229 */
230 @CommandOption("projFile")
231 config String projFile = "";
232 }
233 234 235
236