This command allows RTSC content, in the form of reusable modules built
using the XDCtools tooling, to be imported into a system integrator's
embedded application. It is the recommended method for integrating RTSC
content into non-RTSC application build environments.
Configuro lets the system integrator identify and customize the RTSC
content they wish to use, and computes a set of libraries, command-line
flags and other artifacts to include in their application build. By
changing the values of configuration settings, the integrator can
trade off the functionality, memory footprint, and even performance of
the RTSC content to best meet the needs of their application.
config Main.usage // module-wide |
 |
usage help message
Main.usage = String[] [
'[-v | -q]',
'[-@ optionsfile]',
'[-o outdir]',
'[-b config_bld | -c codegen_dir | --cb]',
'[-t target] [-p platform[:instance]] [-r profile]',
'[-Dname=value]',
'[-w | -x regexp]',
'[--rtsName pkg_name]',
'[--cfgArgs args_string]',
'[--linkTemplate linker_template]',
'[--pkg] [--generationOnly]',
'[--compileOptions compile_options_string]',
'[--linkOptions linker_options_string]',
'[--oc compiler.opt] [--ol linker.cmd]',
'infile.cfg'
];
Main.exec() // module-wide |
 |
xs script entry point
Main.exec(Any args) returns Any
DETAILS
This function is called from within other XDCscript scripts and
performs the same operations as
main() except that,
rather than output the return value of
inst.run(), this value
is simply returned to the caller of
exec().
Main.main() // module-wide |
 |
xs shell entry point
Main.main(Any args) returns Any
DETAILS
This function
- creates a no-arg instance, inst, of the module inheriting
this interface;
- parses command line arguments placing all options in the config
params of the inheriting module;
- creates a xdc.tools.Cmdr instance, cmdr;
- calls inst.run() with the cmdr and any command
line command line arguments not parsed as options; and
- outputs the return result from inst.run()
Instance Config Parameters |
 |
var params = new Main.Params;
// Instance config-params object
params.cfgArgs = String null;
// Optional arguments passed to configuration script
params.compileOptions = String "";
// Add compile options for C files in the configuration package
params.compilerOptionsFile = String "compiler.opt";
// Set the name of the compiler options file (default is "compiler.opt")
params.configbld = String null;
// Read build environment from the named config.bld file
params.defines = String[] [ ];
// Set a Java property in the configuration script
params.exclude = String null;
// Exclude packages matching regexp from compatibility checking
params.generationOnly = Bool false;
// Create the configuration generated source files but do not build
params.linkOptions = String "";
// Add linker options for libraries in the configuration package
params.linkTemplate = String null;
// Linker command file template
params.linkerCommandFile = String "linker.cmd";
// Set the name of the linker command file (default is "linker.cmd")
params.mkPkgOnly = Bool false;
// Create the build model generated output files but do not build
params.output = String null;
// Pathname of the output directory
params.platform = String null;
// Name of the RTSC platform package (and optionally instance)
params.profile = String 'release';
// Build profile to use
params.quiet = Bool false;
// Minimize details during build
params.rootdir = String null;
// Root directory of the code generation tools
params.rtsName = String null;
// Set the name of the RTSC runtime package
params.searchForConfigBld = Bool false;
// Use a config.bld found along the package path
params.target = String null;
// Name of the RTSC target module
params.verbose = Bool false;
// Show verbose details during build
params.warn = Bool false;
// Treat package version incompatibilites as warnings
config Main.Params.cfgArgs // instance |
 |
Optional arguments passed to configuration script
var params = new Main.Params;
...
params.cfgArgs = String null;
DETAILS
This option lets the user pass values into the configuration script
from the command line. The argument is an expression in JavaScript
syntax. Its value is available in the configuration script under the
name Program.build.cfgArgs.
The JavaScript expression is evaluated in the configuration domain
after the platform package is imported, immediately before calling
the user's configuration script.
This string has the same effect as the
cfgArgs string in
xdc.bld.Executable.Attrs.
You can pass multiple values to configuration scripts using the
syntax of a JavaScript Object constant:
xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ... app.cfg
The configuration script can read the various fields as, e.g.:
if (Program.build.cfgArgs.foo == "hello") {
:
}
NOTE
Different command line shells, such as UNIX bash verses Windows
cmd.exe, interpret quotes on the command line very differently.
As a result, the syntax necessary to pass a string such as "hello"
to configuro can vary depending on the shell you use.
For most UNIX shells, it is possible to use single quotes around the
use of double quotes as in the example above. However, since Windows
cmd.exe does not treat the single quote as a special character, it
is necessary to use a backslash, '\', to ensure that the double quote
characters are passed to the configuro tool.
Windows cmd.exe:
xs xdc.tools.configuro --cfgArgs "{foo:\"hello\", bar:2}" ...
UNIX bash, ksh, csh, ...:
xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ...
SEE
config Main.Params.compileOptions // instance |
 |
Add compile options for C files in the configuration package
var params = new Main.Params;
...
params.compileOptions = String "";
DETAILS
This option accepts one or more compiler options that are added to
the compiler command line when compiling C files in the generated
configuration package.
If multiple compiler options are given, the whole string containing
options must be surrounded by quotes.
config Main.Params.compilerOptionsFile // instance |
 |
Set the name of the compiler options file (default is "compiler.opt")
var params = new Main.Params;
...
params.compilerOptionsFile = String "compiler.opt";
config Main.Params.configbld // instance |
 |
Read build environment from the named config.bld file
var params = new Main.Params;
...
params.configbld = String null;
DETAILS
A config.bld file can optionally be used to hold the values
of the target, compiler root directory, platform, and other
more advanced options. This is a convenient way to share a common
build environment between multiple projects.
The format of the file is JavaScript statements with the XDCscript
extensions. The script should set the properties of the
Build global object.
If no config.bld file is given then the target and compiler
root directory are required command-line parameters.
config Main.Params.defines // instance |
 |
Set a Java property in the configuration script
var params = new Main.Params;
...
params.defines = String[] [ ];
DETAILS
Allows values to be injected from the command line into the
config.bld file. For example, the option -Dmyprop=myval
creates a property named myprop with string value "myval".
This can be read in config.bld using the XDCscript syntax
environment["myprop"].
config Main.Params.exclude // instance |
 |
Exclude packages matching regexp from compatibility checking
var params = new Main.Params;
...
params.exclude = String null;
DETAILS
A JavaScript regular expression that is used to select packages that
should be excluded from the set of packages checked during
configuration.
SEE
config Main.Params.generationOnly // instance |
 |
Create the configuration generated source files but do not build
var params = new Main.Params;
...
params.generationOnly = Bool false;
DETAILS
This option runs the configuration step but does not compile the
generated source files. This option is used
by internal tooling to eliminate unnecessary build steps.
config Main.Params.linkOptions // instance |
 |
Add linker options for libraries in the configuration package
var params = new Main.Params;
...
params.linkOptions = String "";
DETAILS
This option accepts one or more linker options which are used to
pull in the correct libraries during link.
If multiple linker options are given, the whole string containing
options must be surrounded by quotes.
config Main.Params.linkTemplate // instance |
 |
Linker command file template
var params = new Main.Params;
...
params.linkTemplate = String null;
DETAILS
If this option is provided it overrides the template supplied by
the platform, giving the caller complete control over the generated
linker command file.
SEE
config Main.Params.linkerCommandFile // instance |
 |
Set the name of the linker command file (default is "linker.cmd")
var params = new Main.Params;
...
params.linkerCommandFile = String "linker.cmd";
config Main.Params.mkPkgOnly // instance |
 |
Create the build model generated output files but do not build
var params = new Main.Params;
...
params.mkPkgOnly = Bool false;
DETAILS
This option creates the output directory and key generated files
but does not process the user's configuration script. It is used
by internal tooling to snapshot the RTSC build settings implied by
the configuro command line parameters.
config Main.Params.output // instance |
 |
Pathname of the output directory
var params = new Main.Params;
...
params.output = String null;
DETAILS
A directory containing the generated build artifacts, in particular
the compiler.opt and linker.cmd files.
The last component of the output directory path must be a valid
ANSI C identifier; i.e., it must consist entirely of alphanumeric or
'_' characters and must not start with a number. So, the names
'0app' and 'app-test' are not valid but '0app/config' and
'app-test/config' are valid.
By default, the output directory has the same name as the
configuration script, minus the .cfg extension, within the same
parent directory as this script. As a result, the directory name
constraint above applies to the name of the configuration script.
config Main.Params.platform // instance |
 |
Name of the RTSC platform package (and optionally instance)
var params = new Main.Params;
...
params.platform = String null;
DETAILS
The name of a RTSC platform package to use, using the syntax
my.pkg.name or my.pkg.name:instanceName. For example,
ti.platforms.sim64Pxx or ti.platforms.generic:custom.
This is an optional parameter, and by default the platform is
the one that the selected target names as its default. The user
may override this default in their config.bld or by using this
parameter.
The optional
:instanceName suffix names a pre-configured variant
of the platform, which can be set up either in the user's
config.bld or in the platform package itself. For more details, see
Build.platformTable
and the
IPlatform interface.
config Main.Params.profile // instance |
 |
Build profile to use
var params = new Main.Params;
...
params.profile = String 'release';
DETAILS
The name of the build profile to use for the RTSC content, for
example 'release' or 'debug'. The list of allowed profiles is
determined by the RTSC target module named.
config Main.Params.quiet // instance |
 |
Minimize details during build
var params = new Main.Params;
...
params.quiet = Bool false;
DETAILS
This option produces the same output as the xdc command
with the XDCOPTIONS=qq parameter.
config Main.Params.rootdir // instance |
 |
Root directory of the code generation tools
var params = new Main.Params;
...
params.rootdir = String null;
DETAILS
The path to the installation directory of the compiler and linker
for the selected target. The definition of "installation directory"
can vary from compiler to compiler, but is most commonly the
directory that contains a "bin" subdirectory.
If no config.bld file is given, then this is a required
parameter.
If a config.bld file is given then this parameter is optional,
and by default the compiler will be the one configured there.
This option can still be used, to override the default established
in config.bld.
config Main.Params.rtsName // instance |
 |
Set the name of the RTSC runtime package
var params = new Main.Params;
...
params.rtsName = String null;
DETAILS
The name of a package containing pre-built libraries containing
the
xdc.runtime modules. If this parameter is
null (or
undefined) the name of the rts package is taken from the target
(
xdc.bld.ITarget.rtsName). If this parameter is set to
the empty string (""), then no rts package is included in the
configuration. Finally, if this parameter is non-
null and
non-empty, it should be the name of a package along the package
path that can supply pre-built versions of the modules in the
xdc.runtime package.
SEE
config Main.Params.searchForConfigBld // instance |
 |
Use a config.bld found along the package path
var params = new Main.Params;
...
params.searchForConfigBld = Bool false;
DETAILS
Find a config.bld by searching the package path, instead of
via an explicit pathname. Looks for a file named config.bld in
any of the directories named along the package path, in order. The
directories are not searched recursively.
config Main.Params.target // instance |
 |
Name of the RTSC target module
var params = new Main.Params;
...
params.target = String null;
DETAILS
The name of a RTSC target module to use, for example
ti.targets.C64P.
If no config.bld file is given, then this is a required
parameter.
If a
config.bld file is given then this parameter is optional,
and by default the target will be
Build.targets[0] from the
user's
config.bld. If
Build.targets contains more than one entry,
then this option can be used to override that default.
config Main.Params.verbose // instance |
 |
Show verbose details during build
var params = new Main.Params;
...
params.verbose = Bool false;
DETAILS
This option produces the same verbose output as the xdc command
with the XDCOPTIONS=v parameter.
config Main.Params.warn // instance |
 |
Treat package version incompatibilites as warnings
var params = new Main.Params;
...
params.warn = Bool false;
DETAILS
If set to "true", force any incompatibilities detected to be
treated as warnings only; otherwise incompatibilities are fatal.
SEE
Main.gen() // instance |
 |
Generate and build the configuration package
inst.gen(String infile) returns Int
Main.run() // instance |
 |
Underlying implementation of the command
DETAILS
Since this method is used to support both command line tools and
other XDCscript scripts, it is important to avoid explicit
termination of the JVM via java.lang.System.exit(); doing so
precludes callers from handling failures.
Implementations should instead call