1    /* --COPYRIGHT--,EPL
     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     * --/COPYRIGHT--*/
    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    metaonly module Main inherits xdc.tools.ICmd {
    58    
    59        /*!
    60         * usage help message
    61         */
    62        override config String usage[] = [
    63            '[-v | -q]',
    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] [--generationOnly]',
    74            '[--compileOptions compile_options_string]',
    75            '[--oc compiler.opt] [--ol linker.cmd]',
    76            'infile.cfg'
    77        ];
    78    
    79    instance:
    80        /*!
    81         *  Pathname of the output directory
    82         *
    83         *  A directory containing the generated build artifacts, in particular
    84         *  the `compiler.opt` and `linker.cmd` files.
    85         *
    86         *  The last component of the output directory path must be a valid
    87         *  ANSI C identifier; i.e., it must consist entirely of alphanumeric or
    88         *  '_' characters and must not start with a number.  So, the names
    89         *  '0app' and 'app-test' are not valid but '0app/config' and
    90         *  'app-test/config' are valid.
    91         *
    92         *  By default, the output directory has the same name as the
    93         *  configuration script, minus the `.cfg` extension, within the same
    94         *  parent directory as this script.  As a result, the directory name
    95         *  constraint above applies to the name of the configuration script.
    96         */
    97        @CommandOption("o")
    98        config String output = null;
    99    
   100        /*!
   101         *  Name of the RTSC target module
   102         *
   103         *  The name of a RTSC target module to use, for example
   104         *  `ti.targets.C64P`.
   105         *
   106         *  If no `config.bld` file is given, then this is a required
   107         *  parameter.
   108         *
   109         *  If a `config.bld` file is given then this parameter is optional,
   110         *  and by default the target will be
   111         *  {@link xdc.bld.BuildEnvironment#targets `Build.targets[0]`} from the
   112         *  user's `config.bld`. If `Build.targets` contains more than one entry,
   113         *  then this option can be used to override that default.
   114         */
   115        @CommandOption("t")
   116        config String target = null;
   117    
   118        /*!
   119         *  Root directory of the code generation tools
   120         *
   121         *  The path to the installation directory of the compiler and linker
   122         *  for the selected target. The definition of "installation directory"
   123         *  can vary from compiler to compiler, but is most commonly the
   124         *  directory that contains a "bin" subdirectory.
   125         *
   126         *  If no `config.bld` file is given, then this is a required
   127         *  parameter.
   128         *
   129         *  If a `config.bld` file is given then this parameter is optional,
   130         *  and by default the compiler will be the one configured there.
   131         *  This option can still be used, to override the default established
   132         *  in `config.bld`.
   133         */
   134        @CommandOption("c")
   135        config String rootdir = null;
   136    
   137        /*!
   138         *  Name of the RTSC platform package (and optionally instance)
   139         *
   140         *  The name of a RTSC platform package to use, using the syntax
   141         *  `my.pkg.name` or `my.pkg.name:instanceName`. For example,
   142         *  `ti.platforms.sim64Pxx` or `ti.platforms.generic:custom`.
   143         *
   144         *  This is an optional parameter, and by default the platform is
   145         *  the one that the selected target names as its default. The user
   146         *  may override this default in their `config.bld` or by using this
   147         *  parameter.
   148         *
   149         *  The optional `:instanceName` suffix names a pre-configured variant
   150         *  of the platform, which can be set up either in the user's
   151         *  `config.bld` or in the platform package itself. For more details, see
   152         *  {@link xdc.bld.BuildEnvironment#platformTable `Build.platformTable`}
   153         *  and the {@link xdc.platform.IPlatform `IPlatform`} interface.
   154         */
   155        @CommandOption("p")
   156        config String platform = null;
   157    
   158        /*!
   159         *  Build profile to use
   160         *
   161         *  The name of the build profile to use for the RTSC content, for
   162         *  example 'release' or 'debug'. The list of allowed profiles is
   163         *  determined by the RTSC target module named.
   164         */
   165        @CommandOption("r")
   166        config String profile = 'release';
   167    
   168        /*!
   169         *  Read build environment from the named `config.bld` file
   170         *
   171         *  A `config.bld` file can optionally be used to hold the values
   172         *  of the target, compiler root directory, platform, and other
   173         *  more advanced options. This is a convenient way to share a common
   174         *  build environment between multiple projects.
   175         *
   176         *  The format of the file is JavaScript statements with the XDCscript
   177         *  extensions. The script should set the properties of the
   178         *  {@link xdc.bld.BuildEnvironment `Build`} global object.
   179         *
   180         *  If no `config.bld` file is given then the target and compiler
   181         *  root directory are required command-line parameters.
   182         */
   183        @CommandOption("b")
   184        config String configbld = null;
   185    
   186        /*!
   187         *  Use a `config.bld` found along the package path
   188         *
   189         *  Find a `config.bld` by searching the package path, instead of
   190         *  via an explicit pathname. Looks for a file named `config.bld` in
   191         *  any of the directories named along the package path, in order. The
   192         *  directories are not searched recursively.
   193         */
   194        @CommandOption("cb")
   195        config Bool searchForConfigBld = false;
   196    
   197        /*!
   198         *  Set a Java property in the configuration script
   199         *
   200         *  Allows values to be injected from the command line into the
   201         *  `config.bld` file. For example, the option `-Dmyprop=myval`
   202         *  creates a property named `myprop` with string value `"myval"`.
   203         *  This can be read in `config.bld` using the XDCscript syntax
   204         *  `environment["myprop"]`.
   205         */
   206        @CommandOption("D")
   207        config String defines[] = [];
   208    
   209        /*!
   210         *  Set the name of the RTSC runtime package
   211         *
   212         *  The name of a package containing pre-built libraries containing
   213         *  the {@link xdc.runtime} modules.  If this parameter is `null` (or
   214         *  `undefined`) the name of the rts package is taken from the target
   215         *  (`{@link xdc.bld.ITarget#rtsName}`).  If this parameter is set to
   216         *  the empty string (""), then no rts package is included in the
   217         *  configuration.  Finally, if this parameter is non-`null` and
   218         *  non-empty, it should be the name of a package along the package
   219         *  path that can supply pre-built versions of the modules in the
   220         *  `{@link xdc.runtime}` package.
   221         *
   222         *  @see xdc.bld.ITarget#rtsName
   223         *  @see xdc.bld.Executable#Attrs
   224         */
   225        @CommandOption("rtsName")
   226        config String rtsName = null;
   227    
   228        /*!
   229         *  ======== cfgArgs ========
   230         *  Optional arguments passed to configuration script
   231         *
   232         *  This option lets the user pass values into the configuration script
   233         *  from the command line. The argument is an expression in JavaScript
   234         *  syntax.  Its value is available in the configuration script under the
   235         *  name `Program.build.cfgArgs`.
   236         *
   237         *  The JavaScript expression is evaluated in the configuration domain
   238         *  after the platform package is imported, immediately before calling
   239         *  the user's configuration script.
   240         *
   241         *  This string has the same effect as the `cfgArgs` string in
   242         *  `{@link xdc.bld.Executable#Attrs}`.
   243         *
   244         *  You can pass multiple values to configuration scripts using the
   245         *  syntax of a JavaScript `Object` constant:
   246         *  @p(code)
   247         *      xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ... app.cfg
   248         *  @p
   249         *
   250         *  The configuration script can read the various fields as, e.g.:
   251         *  @p(code)
   252         *      if (Program.build.cfgArgs.foo == "hello") {
   253         *          :
   254         *      }
   255         *  @p
   256         *    
   257         *  @a(Note)
   258         *  Different command line shells, such as UNIX `bash` verses Windows
   259         *  `cmd.exe`, interpret quotes on the command line very differently.
   260         *  As a result, the syntax necessary to pass a string such as "hello"
   261         *  to `configuro` can vary depending on the shell you use.
   262         *
   263         *  For most UNIX shells, it is possible to use single quotes around the
   264         *  use of double quotes as in the example above.  However, since Windows
   265         *  `cmd.exe` does not treat the single quote as a special character, it
   266         *  is necessary to use a backslash, '\', to ensure that the double quote
   267         *  characters are passed to the configuro tool.
   268         *
   269         *  Windows `cmd.exe`:
   270         *  @p(code)
   271         *      xs xdc.tools.configuro --cfgArgs "{foo:\"hello\", bar:2}" ...
   272         *  @p
   273         *
   274         *  UNIX `bash`, `ksh`, `csh`, ...:
   275         *  @p(code)
   276         *      xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ...
   277         *  @p
   278         *
   279         *  @see xdc.bld.Executable#Attrs
   280         */
   281        @CommandOption("cfgArgs")
   282        config String cfgArgs = null;
   283    
   284        /*!
   285         *  Linker command file template
   286         *
   287         *  If this option is provided it overrides the template supplied by
   288         *  the platform, giving the caller complete control over the generated
   289         *  linker command file.
   290         *
   291         *  @see xdc.cfg.Program#linkTemplate
   292         */
   293        @CommandOption("linkTemplate")
   294        config String linkTemplate = null;
   295        
   296        /*!
   297         *  Show verbose details during build
   298         *
   299         *  This option produces the same verbose output as the `xdc` command
   300         *  with the `XDCOPTIONS=v` parameter.
   301         */
   302        @CommandOption("v")
   303        config Bool verbose = false;
   304    
   305        /*!
   306         *  Minimize details during build
   307         *
   308         *  This option produces the same output as the `xdc` command
   309         *  with the `XDCOPTIONS=qq` parameter.
   310         */
   311        @CommandOption("q")
   312        config Bool quiet = false;
   313    
   314        /*!
   315         *  Exclude packages matching regexp from compatibility checking
   316         *
   317         *  A JavaScript regular expression that is used to select packages that
   318         *  should be excluded from the set of packages checked during
   319         *  configuration.
   320         *
   321         *  @see xdc.cfg
   322         */
   323        @CommandOption("x")
   324        config String exclude = null;
   325    
   326        /*!
   327         *  Treat package version incompatibilites as warnings
   328         *
   329         *  If set to "`true`", force any incompatibilities detected to be
   330         *  treated as warnings only; otherwise incompatibilities are fatal.
   331         *
   332         *  @see xdc.cfg
   333         */
   334        @CommandOption("w")
   335        config Bool warn = false;
   336    
   337        /*!
   338         *  Read infile.tcf in addition to infile.cfg
   339         *
   340         *  The .tcf file optionally configures DSP/BIOS 5.X . This allows a
   341         *  single program to use both DSP/BIOS 5.X and RTSC-based content.
   342         */
   343        @CommandOption("tcf")
   344        config Bool hasTconf = false;
   345    
   346        /*!
   347         *  Add the DSP/BIOS 5.X include directory to the compiler options
   348         *
   349         *  The directory is located in "include" in package "ti.bios".
   350         */
   351        @CommandOption("bios5")
   352        config Bool bios5Incs = false;
   353    
   354        /*!
   355         *  Create the build model generated output files but do not build
   356         *
   357         *  This option creates the output directory and key generated files
   358         *  but does not process the user's configuration script. It is used
   359         *  by internal tooling to snapshot the RTSC build settings implied by
   360         *  the configuro command line parameters.
   361         */
   362        @CommandOption("pkg")
   363        config Bool mkPkgOnly = false;
   364    
   365        /*!
   366         *  Create the configuration generated source files but do not build
   367         *
   368         *  This option runs the configuration step but does not compile the
   369         *  generated source files.  This option is used 
   370         *  by internal tooling to eliminate unnecessary build steps.
   371         */
   372        @CommandOption("generationOnly")
   373        config Bool generationOnly = false;
   374    
   375        /*!
   376         *  Add compile options for C files in the configuration package
   377         *
   378         *  This option accepts one or more compiler options that are added to
   379         *  the compiler command line when compiling C files in the generated
   380         *  configuration package.
   381         *  If multiple compiler options are given, the whole string containing
   382         *  options must be surrounded by quotes.
   383         */
   384        @CommandOption("compileOptions")
   385        config String compileOptions = "";
   386    
   387        /*!
   388         *  Set the name of the compiler options file (default is "compiler.opt")
   389         */
   390        @CommandOption("oc")
   391        config String compilerOptionsFile = "compiler.opt";
   392    
   393        /*!
   394         *  Set the name of the linker command file (default is "linker.cmd")
   395         */
   396        @CommandOption("ol")
   397        config String linkerCommandFile = "linker.cmd";
   398    
   399        /*!
   400         *  Generate and build the configuration package
   401         */
   402        int gen(String infile);
   403    }