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