1    /* 
     2     *  Copyright (c) 2013 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     * */
    12    /*!
    13     *  ======== Main ========
    14     *  Command-line configuration tool for IAR Embedded Workbench
    15     *
    16     *  This command-line tool computes the appropriate configuro options from the
    17     *  set of options passed from the IAR Workbench (for ex. target/platform
    18     *  from compile options). With these options, the xdc.tools.configuro tool
    19     *  is executed to compute the set of libraries, command-line flags and
    20     *  the other artifacts needed to build the application in IAR Workbench.
    21     *
    22     *  @a(INPUTS)
    23     *  @p(dlist)
    24     *    - `-o outdir (Optional)`
    25     *      Optionally an output directory can be provided.
    26     *    - `-c codegen_dir`
    27     *      Root directory of the code generation tools.
    28     *    - `--device device_name_string`
    29     *      The name of the device.
    30     *    - `--compileOptions compile_options_string`
    31     *      The command line options passed to the compiler.
    32     *    - `--linkOptions linker_options_string`
    33     *      The command line options passed to the linker.
    34     *    - `--profile profile`
    35     *      The build profile.
    36     *    - `--projFile project_file (Optional)`
    37     *      IAR Embedded Workbench project file. This is optional when
    38     *      infile.cfg is passed on command line.
    39     *    - `infile.cfg (Optional)`
    40     *      A user-supplied configuration script that names a set of RTSC
    41     *      modules, and optionally changes their configuration settings.
    42     *      If provided, it will override the --projFile option.
    43     *  @p
    44     *
    45     *  @a(OUTPUTS)
    46     *  @p(dlist)
    47     *    - `outdir/`
    48     *      A directory containing all generated build artifacts.
    49     *    - `outdir/compiler.defs`
    50     *      A file containing C compiler command-line flags. These flags must
    51     *      included on the compiler command line for any C source file that
    52     *      directly accesses the RTSC content. The flags define the header file
    53     *      and include paths to ensure object code compatibility between all
    54     *      all included content.
    55     *    - `outdir/linker.cmd`
    56     *      A file containing linker command-line flags. These flags must be
    57     *      included on the linker command line for the final link of the
    58     *      application. The flags list needed libraries and object files,
    59     *      and on some platforms define the embedded system memory map.
    60     *  @p
    61     *
    62     *  For example:
    63     *  @p(code)
    64     *      xs iar.tools.configuro -c "<codegen_dir>" --cc "<compiler>"
    65     *         --device "<device_name>" --cfgArgs "<cfg_script_args>"
    66     *         --compileOptions "<compiler_options>" --linkOptions "<link_options>"
    67     *         --profile "<profile>" infile.cfg
    68     *  @p
    69     */
    70    metaonly module Main inherits xdc.tools.ICmd {
    71    
    72        /*!
    73         * usage help message
    74         */
    75        override config String usage[] = [
    76            '[-o outdir (optional)]',
    77            '[-c codegen_dir]',
    78            '[--cc compiler_name_string]',
    79            '[--device device_name]',
    80            '[--cfgArgs args_string]',
    81            '[--compileOptions compile_options_string]',
    82            '[--linkOptions linker_options_string]',
    83            '[--profile profile]',
    84            '[--projFile project_file (optional)]',
    85            'infile.cfg (optional)'
    86        ];
    87    
    88    instance:
    89    
    90        /*!
    91         *  ======== output ========
    92         *  Pathname of the output directory
    93         *
    94         *  A directory containing the generated build artifacts, in particular
    95         *  the `compiler.defs` and `linker.cmd` files.
    96         *
    97         *  The last component of the output directory path must be a valid
    98         *  ANSI C identifier; i.e., it must consist entirely of alphanumeric or
    99         *  '_' characters and must not start with a number.  So, the names
   100         *  '0app' and 'app-test' are not valid but '0app/config' and
   101         *  'app-test/config' are valid.
   102         *
   103         *  This is optional parameter. By default, the output directory has the
   104         *  name `configPkg` and will be  within the `{#cfgDir}` directory.
   105         */
   106        @CommandOption("o")
   107        config String output = "";
   108    
   109        /*!
   110         *  ======== rootDir ========
   111         *  Root directory of the code generation tools
   112         *
   113         *  The path to the installation directory of the compiler and linker
   114         *  for the selected target. The definition of "installation directory"
   115         *  can vary from compiler to compiler, but is most commonly the
   116         *  directory that contains a "bin" subdirectory.
   117         */
   118        @CommandOption("c")
   119        config String rootDir = null;
   120    
   121        /*!
   122         *  ======== compiler ========
   123         *  @_nodoc
   124         *  The name of the compiler
   125         *
   126         *  The compiler name is required to find the target and platform
   127         *  xdc.tools.configuro options.
   128         */
   129        @CommandOption("cc")
   130        config String compiler = "";
   131    
   132        /*!
   133         *  ======== device ========
   134         *  The name of the device
   135         *
   136         *  The device name has to be passed to the xdc.tools.configuro tool.
   137         */
   138        @CommandOption("device")
   139        config String device = null;
   140    
   141        /*!
   142         *  ======== compileOptions ========
   143         *  Compile options used for building C files
   144         *
   145         *  The compiler options are required to find the target and platform
   146         *  options for xdc.tools.configuro.
   147         */
   148        @CommandOption("compileOptions")
   149        config String compileOptions = null;
   150    
   151        /*!
   152         *  ======== linkOptions ========
   153         *  Linker options used for linking libraries
   154         *
   155         *  The linker options are required to pull in the correct libraries
   156         *  during link.
   157         */
   158        @CommandOption("linkOptions")
   159        config String linkOptions = null;
   160    
   161        /*!
   162         *  ======== profile ========
   163         *  Build profile
   164         */
   165        @CommandOption("profile")
   166        config String profile = "";
   167    
   168        /*!
   169         *  ======== cfgArgs ========
   170         *  Optional arguments passed to configuration script
   171         *
   172         *  This option lets the user pass values into the configuration script
   173         *  from the command line. The argument is an expression in JavaScript
   174         *  syntax.  Its value is available in the configuration script under the
   175         *  name `Program.build.cfgArgs`.
   176         *
   177         *  The JavaScript expression is evaluated in the configuration domain
   178         *  after the platform package is imported, immediately before calling
   179         *  the user's configuration script.
   180         *
   181         *  This string has the same effect as the `cfgArgs` string in
   182         *  `{@link xdc.bld.Executable#Attrs}`.
   183         *
   184         *  You can pass multiple values to configuration scripts using the
   185         *  syntax of a JavaScript `Object` constant:
   186         *  @p(code)
   187         *      xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ... app.cfg
   188         *  @p
   189         *
   190         *  The configuration script can read the various fields as, e.g.:
   191         *  @p(code)
   192         *      if (Program.build.cfgArgs.foo == "hello") {
   193         *          :
   194         *      }
   195         *  @p
   196         *
   197         *  @a(Note)
   198         *  Different command line shells, such as UNIX `bash` verses Windows
   199         *  `cmd.exe`, interpret quotes on the command line very differently.
   200         *  As a result, the syntax necessary to pass a string such as "hello"
   201         *  to `configuro` can vary depending on the shell you use.
   202         *
   203         *  For most UNIX shells, it is possible to use single quotes around the
   204         *  use of double quotes as in the example above.  However, since Windows
   205         *  `cmd.exe` does not treat the single quote as a special character, it
   206         *  is necessary to use a backslash, '\', to ensure that the double quote
   207         *  characters are passed to the configuro tool.
   208         *
   209         *  Windows `cmd.exe`:
   210         *  @p(code)
   211         *      xs xdc.tools.configuro --cfgArgs "{foo:\"hello\", bar:2}" ...
   212         *  @p
   213         *
   214         *  UNIX `bash`, `ksh`, `csh`, ...:
   215         *  @p(code)
   216         *      xs xdc.tools.configuro --cfgArgs '{foo:"hello", bar:2}' ...
   217         *  @p
   218         *
   219         *  @see xdc.bld.Executable#Attrs
   220         */
   221        @CommandOption("cfgArgs")
   222        config String cfgArgs = "";
   223    
   224        /*!
   225         *  ======== projFile ========
   226         *  IAR Embedded project file.
   227         *
   228         *  This file is searched for the RTSC configuration file (.cfg).
   229         */
   230        @CommandOption("projFile")
   231        config String projFile = "";
   232    }
   233    /*
   234     *  @(#) iar.tools.configuro; 1, 0, 0,3; 2-18-2019 11:02:57; /db/ztree/library/trees/xdctools/xdctools-h03/src/
   235     */
   236