metaonly module xdc.tools.configuro.Main
index URL

Command implementation

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. [ more ... ]
XDCscript usage meta-domain sourced in xdc/tools/configuro/Main.xdc
var Main = xdc.useModule('xdc.tools.configuro.Main');
module-wide config parameters
    Main.usage// usage help message = 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]',
        '[--tcf] [--bios5] [--pkg] [--generationOnly]',
        '[--compileOptions compile_options_string]',
        '[--oc compiler.opt] [--ol linker.cmd]',
        'infile.cfg'
    ];
module-wide functions
    Main.exec// 'xs' script entry point(Any args) returns Any
    Main.main// 'xs' shell entry point(Any args) returns Any
per-instance config parameters
    var params = new Main.Params// Instance config-params object;
        params.bios5Incs// Add the DSP/BIOS 5.X include directory to the compiler options = Bool false;
        params.cfgArgs// Optional arguments passed to configuration script = String null;
        params.compileOptions// Add compile options for C files in the configuration package = String "";
        params.compilerOptionsFile// Set the name of the compiler options file (default is "compiler.opt") = String "compiler.opt";
        params.configbld// Read build environment from the named config.bld file = String null;
        params.defines// Set a Java property in the configuration script = String[] [ ];
        params.exclude// Exclude packages matching regexp from compatibility checking = String null;
        params.generationOnly// Create the configuration generated source files but do not build = Bool false;
        params.hasTconf// Read infile.tcf in addition to infile.cfg = Bool false;
        params.linkTemplate// Linker command file template = String null;
        params.linkerCommandFile// Set the name of the linker command file (default is "linker.cmd") = String "linker.cmd";
        params.mkPkgOnly// Create the build model generated output files but do not build = Bool false;
        params.output// Pathname of the output directory = String null;
        params.platform// Name of the RTSC platform package (and optionally instance) = String null;
        params.profile// Build profile to use = String 'release';
        params.quiet// Minimize details during build = Bool false;
        params.rootdir// Root directory of the code generation tools = String null;
        params.rtsName// Set the name of the RTSC runtime package = String null;
        params.searchForConfigBld// Use a config.bld found along the package path = Bool false;
        params.target// Name of the RTSC target module = String null;
        params.verbose// Show verbose details during build = Bool false;
        params.warn// Treat package version incompatibilites as warnings = Bool false;
per-instance functions
    inst.gen// Generate and build the configuration package(String infile) returns Int
    inst.run// Underlying implementation(Cmdr.Instance cmdr, String[] args) returns Any
 
DETAILS
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.
INPUTS
infile.cfg
A user-supplied configuration script that names a set of RTSC modules, and optionally changes their configuration settings.
OUTPUTS
outdir/
A directory containing all generated build artifacts.
outdir/compiler.opt
A file containing C compiler command-line flags. These flags must included on the compiler command line for any C source file that directly accesses the RTSC content. The flags define the header file include paths, and machine-mode compiler flags to ensure object code compatibility between all included content.
outdir/linker.cmd
A file containing linker command-line flags. These flags must be included on the linker command line for the final link of the application. The flags list needed libraries and object files, and on some platforms define the embedded system memory map.
For example:
      xs xdc.tools.configuro myconfig.cfg
config Main.usage  // module-wide
index URL

usage help message

XDCscript usage meta-domain
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]',
    '[--tcf] [--bios5] [--pkg] [--generationOnly]',
    '[--compileOptions compile_options_string]',
    '[--oc compiler.opt] [--ol linker.cmd]',
    'infile.cfg'
];
Main.exec()  // module-wide
index URL

'xs' script entry point

XDCscript usage meta-domain
Main.exec(Any args) returns Any
Main.main()  // module-wide
index URL

'xs' shell entry point

XDCscript usage meta-domain
Main.main(Any args) returns Any
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Main.Params;
// Instance config-params object
    params.bios5Incs = Bool false;
    // Add the DSP/BIOS 5.X include directory to the compiler options
    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.hasTconf = Bool false;
    // Read infile.tcf in addition to infile.cfg
    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.bios5Incs  // instance
index URL

Add the DSP/BIOS 5.X include directory to the compiler options

XDCscript usage meta-domain
var params = new Main.Params;
  ...
params.bios5Incs = Bool false;
DETAILS
The directory is located in "include" in package "ti.bios".
config Main.cfgArgs  // instance
index URL

Optional arguments passed to configuration script

XDCscript usage meta-domain
var params = new Main.Params;
  ...
params.cfgArgs = String null;
DETAILS
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 the use of single quotes around the string value 'hello' on the command line. This is the easiest way to quote a JavaScript string constant that is compatible with the enclosing double quotes, which are for the benefit of the command line shell.
SEE
xdc.bld.Executable.Attrs
config Main.compileOptions  // instance
index URL

Add compile options for C files in the configuration package

XDCscript usage meta-domain
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.compilerOptionsFile  // instance
index URL

Set the name of the compiler options file (default is "compiler.opt")

XDCscript usage meta-domain
var params = new Main.Params;
  ...
params.compilerOptionsFile = String "compiler.opt";
config Main.configbld  // instance
index URL

Read build environment from the named config.bld file

XDCscript usage meta-domain
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.defines  // instance
index URL

Set a Java property in the configuration script

XDCscript usage meta-domain
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.exclude  // instance
index URL

Exclude packages matching regexp from compatibility checking

XDCscript usage meta-domain
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
xdc.cfg
config Main.generationOnly  // instance
index URL

Create the configuration generated source files but do not build

XDCscript usage meta-domain
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.hasTconf  // instance
index URL

Read infile.tcf in addition to infile.cfg

XDCscript usage meta-domain
var params = new Main.Params;
  ...
params.hasTconf = Bool false;
DETAILS
The .tcf file optionally configures DSP/BIOS 5.X . This allows a single program to use both DSP/BIOS 5.X and RTSC-based content.
config Main.linkTemplate  // instance
index URL

Linker command file template

XDCscript usage meta-domain
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
xdc.cfg.Program.linkTemplate
config Main.linkerCommandFile  // instance
index URL

Set the name of the linker command file (default is "linker.cmd")

XDCscript usage meta-domain
var params = new Main.Params;
  ...
params.linkerCommandFile = String "linker.cmd";
config Main.mkPkgOnly  // instance
index URL

Create the build model generated output files but do not build

XDCscript usage meta-domain
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.output  // instance
index URL

Pathname of the output directory

XDCscript usage meta-domain
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. 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.
config Main.platform  // instance
index URL

Name of the RTSC platform package (and optionally instance)

XDCscript usage meta-domain
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.profile  // instance
index URL

Build profile to use

XDCscript usage meta-domain
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.quiet  // instance
index URL

Minimize details during build

XDCscript usage meta-domain
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.rootdir  // instance
index URL

Root directory of the code generation tools

XDCscript usage meta-domain
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.rtsName  // instance
index URL

Set the name of the RTSC runtime package

XDCscript usage meta-domain
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
xdc.bld.ITarget.rtsName, xdc.bld.Executable.Attrs
config Main.searchForConfigBld  // instance
index URL

Use a config.bld found along the package path

XDCscript usage meta-domain
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.target  // instance
index URL

Name of the RTSC target module

XDCscript usage meta-domain
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.verbose  // instance
index URL

Show verbose details during build

XDCscript usage meta-domain
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.warn  // instance
index URL

Treat package version incompatibilites as warnings

XDCscript usage meta-domain
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
xdc.cfg
Main.gen()  // instance
index URL

Generate and build the configuration package

XDCscript usage meta-domain
inst.gen(String infile) returns Int
Main.run()  // instance
index URL

Underlying implementation

XDCscript usage meta-domain
inst.run(Cmdr.Instance cmdr, String[] args) returns Any
generated on Tue, 24 Aug 2010 15:39:21 GMT