metaonly module iar.tools.configuro.Main

Command implementation

This command-line tool computes the appropriate configuro options from the set of options passed from the IAR Workbench (for ex. target/platform from compile options). With these options, the xdc.tools.configuro tool is executed to compute the set of libraries, command-line flags and the other artifacts needed to build the application in IAR Workbench. [ more ... ]
Configuration settings sourced in iar/tools/configuro/Main.xdc
var Main = xdc.useModule('iar.tools.configuro.Main');
module-wide config parameters
    Main.usage// usage help message = String[] [
        '[-o outdir (optional)]',
        '[-c codegen_dir]',
        '[--cc compiler_name_string]',
        '[--device device_name]',
        '[--cfgArgs args_string]',
        '[--compileOptions compile_options_string]',
        '[--linkOptions linker_options_string]',
        '[--profile profile]',
        '[--projFile project_file (optional)]',
        'infile.cfg (optional)'
    ];
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.compileOptions// Compile options used for building C files = String null;
        params.device// The name of the device = String null;
        params.linkOptions// Linker options used for linking libraries = String null;
        params.output// Pathname of the output directory = String "";
        params.profile// Build profile = String "";
        params.projFile// IAR Embedded project file = String "";
        params.rootDir// Root directory of the code generation tools = String null;
per-instance functions
    inst.run// Underlying implementation of the command(Cmdr.Instance cmdr, String[] args) returns Any
 
DETAILS
This command-line tool computes the appropriate configuro options from the set of options passed from the IAR Workbench (for ex. target/platform from compile options). With these options, the xdc.tools.configuro tool is executed to compute the set of libraries, command-line flags and the other artifacts needed to build the application in IAR Workbench.
INPUTS
-o outdir (Optional)
Optionally an output directory can be provided.
-c codegen_dir
Root directory of the code generation tools.
--device device_name_string
The name of the device.
--compileOptions compile_options_string
The command line options passed to the compiler.
--linkOptions linker_options_string
The command line options passed to the linker.
--profile profile
The build profile.
--projFile project_file (Optional)
IAR Embedded Workbench project file. This is optional when infile.cfg is passed on command line.
infile.cfg (Optional)
A user-supplied configuration script that names a set of RTSC modules, and optionally changes their configuration settings. If provided, it will override the --projFile option.
OUTPUTS
outdir/
A directory containing all generated build artifacts.
outdir/compiler.defs
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 and include paths to ensure object code compatibility between all 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 iar.tools.configuro -c "<codegen_dir>" --cc "<compiler>"
         --device "<device_name>" --cfgArgs "<cfg_script_args>"
         --compileOptions "<compiler_options>" --linkOptions "<link_options>"
         --profile "<profile>" infile.cfg
 
config Main.usage  // module-wide

usage help message

Configuration settings
Main.usage = String[] [
    '[-o outdir (optional)]',
    '[-c codegen_dir]',
    '[--cc compiler_name_string]',
    '[--device device_name]',
    '[--cfgArgs args_string]',
    '[--compileOptions compile_options_string]',
    '[--linkOptions linker_options_string]',
    '[--profile profile]',
    '[--projFile project_file (optional)]',
    'infile.cfg (optional)'
];
 
 
Main.exec()  // module-wide

xs script entry point

Configuration settings
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

Configuration settings
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

Configuration settings
var params = new Main.Params;
// Instance config-params object
    params.cfgArgs = String "";
    // Optional arguments passed to configuration script
    params.compileOptions = String null;
    // Compile options used for building C files
    params.device = String null;
    // The name of the device
    params.linkOptions = String null;
    // Linker options used for linking libraries
    params.output = String "";
    // Pathname of the output directory
    params.profile = String "";
    // Build profile
    params.projFile = String "";
    // IAR Embedded project file
    params.rootDir = String null;
    // Root directory of the code generation tools
 
config Main.Params.cfgArgs  // instance

Optional arguments passed to configuration script

Configuration settings
var params = new Main.Params;
  ...
params.cfgArgs = String "";
 
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

Compile options used for building C files

Configuration settings
var params = new Main.Params;
  ...
params.compileOptions = String null;
 
DETAILS
The compiler options are required to find the target and platform options for xdc.tools.configuro.
 
config Main.Params.device  // instance

The name of the device

Configuration settings
var params = new Main.Params;
  ...
params.device = String null;
 
DETAILS
The device name has to be passed to the xdc.tools.configuro tool.
 
config Main.Params.linkOptions  // instance

Linker options used for linking libraries

Configuration settings
var params = new Main.Params;
  ...
params.linkOptions = String null;
 
DETAILS
The linker options are required to pull in the correct libraries during link.
 
config Main.Params.output  // instance

Pathname of the output directory

Configuration settings
var params = new Main.Params;
  ...
params.output = String "";
 
DETAILS
A directory containing the generated build artifacts, in particular the compiler.defs 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.
This is optional parameter. By default, the output directory has the name configPkg and will be within the {#cfgDir} directory.
 
config Main.Params.profile  // instance

Build profile

Configuration settings
var params = new Main.Params;
  ...
params.profile = String "";
 
 
config Main.Params.projFile  // instance

IAR Embedded project file

Configuration settings
var params = new Main.Params;
  ...
params.projFile = String "";
 
DETAILS
This file is searched for the RTSC configuration file (.cfg).
 
config Main.Params.rootDir  // instance

Root directory of the code generation tools

Configuration settings
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.
 
Main.run()  // instance

Underlying implementation of the command

Configuration settings
inst.run(Cmdr.Instance cmdr, String[] args) returns Any
 
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
generated on Fri, 22 Feb 2019 01:33:34 GMT