1    /* 
     2     * Copyright (c) 2010, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * 
    32     */
    33    
    34    /*
    35     *  ======== PackageBuildHelp.xdc ========
    36     */
    37    package ti.sdo.tools.build;
    38    
    39    import xdc.bld.Executable;
    40    import xdc.bld.Library;
    41    
    42    
    43    /*!
    44     *  ======== PackageBuildHelp ========
    45     *  Common package build support
    46     *
    47     *  This module is a helper module for your package build script
    48     *  (`package.bld`). It provides a high-level interface for defining
    49     *  your libraries and executables, and provides functions to generate
    50     *  your package interface (makefiles).
    51     */
    52    
    53    metaonly module PackageBuildHelp {
    54    
    55        /*!
    56         *  ======== LibAttrs ========
    57         *  Attributes for a library instances
    58         *
    59         *  An array of this type is passed to `PackageBuildHelp.makeLibraries`.
    60         *  Each element in the array describes the build properties for the
    61         *  library. Multiple library instances may be produced from a single
    62         *  `LibAttrs` element. For example, a library instance may be build for
    63         *  different profiles and/or different targets.
    64         *
    65         *  The `icw` array is used to limit which targets will be use for
    66         *  building the library. For example, if you have a library which
    67         *  should only be built for ARM, but you know the build model has a
    68         *  target for DSP, then set the `icw` array as follows to build only
    69         *  for the ARM targets and exclude the DSP targets.
    70         *
    71         *  @p(code)
    72         *  icw: [ "v5T" ]
    73         *  @p(text)
    74         *  Note that all ARM targets which accept v5T as an input isa will
    75         *  build the library using their output isa. For example, if the build
    76         *  model contains both GCArmv5T (isa=v5T) and GCArmv6 (isa=v6) targets,
    77         *  then both targets will build this library using their respective
    78         *  isa. However, if the build model contains the C64P (isa=64P) target,
    79         *  it will not be used to build this library because it cannot accept
    80         *  the v5T isa.
    81         *
    82         *  @a(See Also)
    83         *  {@link #makeLibraries} -- for additional examples
    84         *
    85         *  @field(name) The name of the library with an optional
    86         *  directory prefix.
    87         *
    88         *  @field(sources) An array of source files to be compiled
    89         *  for the library.
    90         *
    91         *  @field(icw) An array of strings listing isa's that a given target
    92         *  must be able to accept. Use this property to limit which targets
    93         *  will be used to build this library. See Details below.
    94         *
    95         *  @field(libAttrs) An xdc.bld.Library.Attrs object used to specify
    96         *  optional attributes of the library instance.
    97         */
    98        struct LibAttrs {
    99            String          name;           /*! library name */
   100            String          sources[];      /*! source files to build */
   101            String          icw[];          /*! array of input isa's */
   102            Library.Attrs   libAttrs;       /*! library attributes */
   103        };
   104    
   105        /*!
   106         *  ======== ProgAttrs ========
   107         *  Attributes for an executable instance
   108         *
   109         *  An array of this type is passed to `PackageBuildHelp.makeExecutables`.
   110         *  Each element in the array describes the build properties for the
   111         *  executable. Multiple executable instances may be produced from a
   112         *  single `ProgAttrs` element. For example, an executable instance may
   113         *  be build for different profiles, targets, and platforms.
   114         *
   115         *  The `icw` array is used to limit which targets will be use for
   116         *  building the executable. For example, if you have an executable
   117         *  which should only be built for ARM, but you know the build model
   118         *  has a target for DSP, then set the `icw` array as follows to build
   119         *  only for the ARM targets and exclude the DSP targets.
   120         *
   121         *  @p(code)
   122         *  icw: [ "v5T" ]
   123         *  @p(text)
   124         *  Note that all ARM targets which accept v5T as an input isa will
   125         *  build the executable using their output isa. For example, if the build
   126         *  model contains both GCArmv5T (isa=v5T) and GCArmv6 (isa=v6) targets,
   127         *  then both targets will build this executable using their respective
   128         *  isa. However, if the build model contains the C64P (isa=64P) target,
   129         *  it will not be used to build this executable because it cannot accept
   130         *  the v5T isa.
   131         *
   132         *  @p(text)
   133         *  Note: this property is more useful to building libraries than
   134         *  executables. The `isas` property is usually used when building
   135         *  executables.
   136         *
   137         *  @p(text)
   138         *  The `isas` array is used to control the executable's isa. Only those
   139         *  targets which have an output isa that matches any entry in this array
   140         *  will be used to build the executable. For example, if you have a
   141         *  program which should be built for ARM v5T or ARM v6 but not for ARM
   142         *  v7A, but you know the build model has targets for all three, then
   143         *  set the `isas` array as follows to get the desired output.
   144         *
   145         *  @p(code)
   146         *  isas: [ "v5T", "v6" ]
   147         *  @p(text)
   148         *  Note: although the GCArmv7A target accepts v5T and v6 isa as input,
   149         *  it will not participate in the build because it outputs v7A isa which
   150         *  not specified in the `isas` array.
   151         *
   152         *  @a(See Also)
   153         *  {@link #makeExecutables} -- for additional examples
   154         *
   155         *  @field(name) The name of the executable with an optional
   156         *  directory prefix.
   157         *
   158         *  @field(sources) An array of strings listing the source files
   159         *  to be compiled for the executables.
   160         *
   161         *  @field(platforms) An array of platform (and/or platform instance)
   162         *  names which are supported by this program. When this property is
   163         *  specified, the executable is built only for those platforms listed
   164         *  by this property, otherwise, the executable is built for all
   165         *  platforms specified in the target's platforms array property.
   166         *
   167         *  @field(icw) An array of strings listing isa's which are compatible
   168         *  for this executable. Use this property to limit which isa's the
   169         *  program will be built for.
   170         *
   171         *  @field(isas) An array of isa's the program should be built for.
   172         *
   173         *  @field(execAttrs) An xdc.bld.Executable.Attrs object used to specify
   174         *  optional attributes of the executable instance.
   175         */
   176        struct ProgAttrs {
   177            String              name;           /*! executable name */
   178            String              sources[];      /*! source files to build */
   179            String              platforms[];    /*! array of platform names */
   180            String              icw[];          /*! array of input isa's */
   181            String              isas[];         /*! array of output isa's */
   182            Executable.Attrs    execAttrs;      /*! executble attributes */
   183        };
   184    
   185        /*!
   186         *  ======== fileArray ========
   187         *  Record all source files and config scripts in given array
   188         *
   189         *  When this config param is assigned to a string array, each call
   190         *  to `PackageBuildHelp.makeExecutables` and
   191         *  `PackageBuildHelp.makeLibraries` will append all given source files
   192         *  and config scripts to the array.
   193         */
   194        config Any fileArray;
   195    
   196        /*!
   197         *  ======== skipExec ========
   198         *  Skip given program if function returns true
   199         *
   200         *  If you don't want your package to build a given executable based
   201         *  on certain build attributes, set this config param to a function
   202         *  defined in your package.bld script which returns true for any
   203         *  executable you do not want to build. 
   204         *
   205         *  This function can also be used to modify the program object just
   206         *  before building it. The following example show a function which
   207         *  adds a source file depending on the target.os property. It always
   208         *  returns false, because we don't want to skip the executable.
   209         *
   210         *  @p(code)
   211         *  PackageBuildHelp.skipExec = function(prog, targ, platName)
   212         *  {
   213         *      if (targ.os == undefined) {
   214         *          prog.sources.push("main_BIOS.c");
   215         *      }
   216         *      else {
   217         *          prog.sources.push("main_native.c");
   218         *      }
   219         *      return false;
   220         *  }
   221         *
   222         *  @b(ARGUMENTS)
   223         *  @p(dlist)
   224         *    - prog
   225         *      (`PackageBuildHelp.ProgAttrs`) An element from the `progAry`
   226         *      argument passed to the `PackageBuildHelp.makeExecutables`
   227         *      function.
   228         *    - targ
   229         *      (`xdc.bld.ITarget.Module`) The target used for building the
   230         *      current executable.
   231         *    - platName
   232         *      (`String`) The name of the platform used for the current
   233         *      executable.
   234         *  @p(text)
   235         */
   236        config Bool skipExec(ProgAttrs, xdc.bld.ITarget.Module, String);
   237    
   238        /*!
   239         *  ======== skipLib ========
   240         *  Skip given library if function returns true
   241         *
   242         *  If you don't want your package to build a given library based
   243         *  on certain build attributes, set this config param to a function
   244         *  defined in your package.bld script which returns true for any
   245         *  library you do not want to build. 
   246         *
   247         *  This function can also be used to modify the library object just
   248         *  before building it. The following example show a function which
   249         *  adds a source file depending on the target.os property. It always
   250         *  returns false, because we don't want to skip the library.
   251         *
   252         *  @p(code)
   253         *  PackageBuildHelp.skipLib = function(lib, targ)
   254         *  {
   255         *      if (targ.os == undefined) {
   256         *          lib.sources.push("util_BIOS.c");
   257         *      }
   258         *      else {
   259         *          lib.sources.push("util_native.c");
   260         *      }
   261         *      return false;
   262         *  }
   263         *
   264         *  @p(text)
   265         *  This example show a function which builds the library only if the
   266         *  library name contains the string "syslink" and the target's
   267         *  os (Operating System) property matches "Linux".
   268         *
   269         *  @p(code)
   270         *  PackageBuildHelp.skipLib = function(lib, targ)
   271         *  {
   272         *      if (lib.name.match(/syslink/)) {
   273         *          return targ.os != "Linux" ? true : false;
   274         *      }
   275         *      else {
   276         *          return false;
   277         *      }
   278         *  }
   279         *
   280         *  @b(ARGUMENTS)
   281         *  @p(dlist)
   282         *    - lib
   283         *      (`PackageBuildHelp.LibAttrs`) An element from the `libAry`
   284         *      argument passed to the `PackageBuildHelp.makeLibraries` function.
   285         *    - targ
   286         *      (`xdc.bld.ITarget.Module`) The target used for building the
   287         *      current library.
   288         *  @p(text)
   289         */
   290        config Bool skipLib(LibAttrs, xdc.bld.ITarget.Module);
   291    
   292        /*!
   293         *  ======== usePlatformInstanceName ========
   294         *  Use platform instance name when constructing executable pathname
   295         *
   296         *  The executable pathname is constructed using the following
   297         *  elements: 'bin', platform name, directory prefix used in
   298         *  program name, profile, and the executable basename. These
   299         *  elements are combined in the following pattern:
   300         *
   301         *  bin/platform/prefix/profile/name
   302         *  
   303         *  This config param controls the platform part of the pathname
   304         *  when using platform instances. When set to true, the platform
   305         *  instance name is used, otherwise, the platform base name is used.
   306         *  When using the default platform instance the platform base name
   307         *  is always used.
   308         */
   309        config Bool usePlatformInstanceName = false;
   310    
   311        /*!
   312         *  ======== skipPlatform ========
   313         *  Skip given platform if function returns true
   314         *
   315         *  If you do not want your package to build for a particular
   316         *  platform, set this config param to a function defined in your
   317         *  `package.bld` script which returns true for any platform you wish
   318         *  to skip.
   319         *
   320         *  The following example shows a function which skips any platform
   321         *  named `ti.platforms.evm3530`.
   322         *
   323         *  @p(code)
   324         *  PackageBuildHelp.skipPlatform = function(platName, targ)
   325         *  {
   326         *      return platName.match(/ti.platforms.evm3530/) ? true : false;
   327         *  }
   328         *
   329         *  @b(ARGUMENTS)
   330         *  @p(dlist)
   331         *    - platName
   332         *      (`String`) The name of the platform used for the current
   333         *      executable.
   334         *    - targ
   335         *      (`xdc.bld.ITarget.Module`) The target used for building the
   336         *      current executable.
   337         *  @p(text)
   338         */
   339        config Bool skipPlatform(String, xdc.bld.ITarget.Module);
   340    
   341        /*!
   342         *  ======== skipTarget ========
   343         *  Skip given target if function returns true
   344         *
   345         *  If you do not want your package to build for a particular
   346         *  target, set this config param to a function defined in your
   347         *  package.bld script which returns true for any target you wish
   348         *  to skip.
   349         *
   350         *  The following example shows a function which skips any target
   351         *  named `UCArm9`.
   352         *
   353         *  @p(code)
   354         *  PackageBuildHelp.skipTarget = function(targ)
   355         *  {
   356         *      return targ.name.match(/UCArm9/) ? true : false;
   357         *  }
   358         *
   359         *  @b(ARGUMENTS)
   360         *  @p(dlist)
   361         *    - targ
   362         *      (`xdc.bld.ITarget.Module`) The target used for building the
   363         *      current library or executable.
   364         *  @p(text)
   365         */
   366        config Bool skipTarget(xdc.bld.ITarget.Module);
   367    
   368        /*!
   369         *  ======== makeExecutables ========
   370         *  Add executables to the build model
   371         *
   372         *  This function iterates over the given `progAry` and adds each element
   373         *  to the build model, possibly multiple times to cover all combinations
   374         *  of platforms, targets, and profiles.
   375         *
   376         *  The following code adds a program called `program` to the build model
   377         *  for all combinations of platforms, targets, and profiles in the build
   378         *  model.
   379         *
   380         *  @p(code)
   381         *  var PackageBuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
   382         *  var progArray = new Array();
   383         *
   384         *  progArray.push(
   385         *      new PackageBuildHelp.ProgAttrs({
   386         *          name: "program",
   387         *          sources: [ "main.c", "core.c" ],
   388         *          execAttrs: {
   389         *              cfgScript: "server.cfg"
   390         *          }
   391         *      })
   392         *  );
   393         *
   394         *  PackageBuildHelp.makeExecutables(progArray, arguments);
   395         *
   396         *  @p(text)
   397         *  You can pass an array of profiles as the third (optional)
   398         *  argument to `PackageBuildHelp.makeExecutables`. This is useful
   399         *  for limiting the number of executables to build when the target
   400         *  defines additional profiles.
   401         *
   402         *  @p(code)
   403         *  PackageBuildHelp.makeExecutables(
   404         *      progArray, arguments, [ "debug", "release" ]);
   405         *
   406         *  @p(text)
   407         *  You may limit the build to a single profile using the XDCARGS
   408         *  command line option, provided the target supports the given profile.
   409         *
   410         *  @p(code)
   411         *  xdc -r XDCARGS="profile=coverage" all
   412         *
   413         *  @p(text)
   414         *  You may limit the build to a single platform using the XDCARGS
   415         *  command line option, provided the target supports the given platform.
   416         *
   417         *  @p(code)
   418         *  xdc -r XDCARGS="platform=ti.platforms.evm3530" all
   419         *
   420         *  @p(text)
   421         *  The profile and platform arguments may be combined in XDCARGS by
   422         *  separating them with white space.
   423         *
   424         *  @p(code)
   425         *  XDCARGS="profile=coverage platform=ti.platforms.evm3530"
   426         *
   427         *  @p(text)
   428         *  When specifying platforms, isas, or both it is important to ensure
   429         *  that all possible combinations are valid. In other words, each
   430         *  platform specified in the `platforms` array must have a core which
   431         *  is either capable of executing every isa specified in the `isas`
   432         *  array or, if `isas` is not specified, capable of executing code
   433         *  generated by every target in the build model. To avoid invalid
   434         *  combinations, specify either or both. Use multiple `ProgAttrs`
   435         *  instances to cover all desired combinations.
   436         *  
   437         *  The following example builds a program for the DSP on an
   438         *  OMAP3530 device and the same program for the VIDEO-M3 on a DM8168
   439         *  device.
   440         *
   441         *  @p(code)
   442         *  var BuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
   443         *  var progArray = new Array();
   444         *
   445         *  progArray.push(
   446         *      new BuildHelp.ProgAttrs({
   447         *          name: "server",
   448         *          platforms: [ "ti.platforms.evm3530" ],
   449         *          isas: [ "64P" ],
   450         *          sources: [ "server.c", "utils.c" ]
   451         *      })
   452         *  );
   453         *
   454         *  progArray.push(
   455         *      new BuildHelp.ProgAttrs({
   456         *          name: "server",
   457         *          platforms: [ "ti.platforms.evmDM8168" ],
   458         *          isas: [ "v7M" ],
   459         *          sources: [ "server.c", "utils.c" ]
   460         *      })
   461         *  );
   462         *
   463         *  BuildHelp.makeExecutables(progArray, arguments);
   464         *  @p(text)
   465         *  Note that combining these two entries into one would generate an
   466         *  invalid combination. For example, there is no core on the OMAP3530
   467         *  capable of running the v7M isa.
   468         *
   469         *  @param(progAry) An array of program attributes, one for each
   470         *  executable to build.
   471         *
   472         *  @param(arguments) The global arguments object passed to the build
   473         *  script which contains the arguments assigned to the XDCARGS
   474         *  environment variable used by the xdc command.
   475         *
   476         *  @param(profiles) Optional. (`String[]`) Array of profile names to
   477         *  build provided the target supports the profile. If not supported
   478         *  by the target, the profile is ignored. When omitted, all profiles
   479         *  defined in the target will be used. If a profile is specified in
   480         *  XDCARGS as described above, this parameter is ignored.
   481         */
   482        Void makeExecutables(
   483                ProgAttrs   progAry[],
   484                Any         arguments,
   485                Any         profiles = undefined
   486            );
   487    
   488        /*!
   489         *  ======== makeLibraries ========
   490         *  Add libraries to the build model
   491         *
   492         *  This function iterates over the given `libAry` and adds each element
   493         *  to the build model, possibly multiple times to cover all combinations
   494         *  of targets and profiles.
   495         *
   496         *  The following code adds a library called `rcm` to the build model
   497         *  for all combinations of targets and profiles in the build model.
   498         *
   499         *  @p(code)
   500         *  var PackageBuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
   501         *  var libArray = new Array();
   502         *
   503         *  libArray.push(
   504         *      new PackageBuildHelp.LibAttrs({
   505         *          name: "rcm",
   506         *          sources: [ "rcm.c" ],
   507         *      })
   508         *  );
   509         *
   510         *  PackageBuildHelp.makeLibraries(libArray, arguments);
   511         *
   512         *  @p(text)
   513         *  You can pass an array of profiles as the third (optional)
   514         *  argument to `PackageBuildHelp.makelibraries`. This is useful
   515         *  for limiting the number of libraries to build when the target
   516         *  defines additional profiles.
   517         *
   518         *  @p(code)
   519         *  PackageBuildHelp.makeLibraries(
   520         *      libArray, arguments, [ "debug", "release" ]);
   521         *
   522         *  @p(text)
   523         *  You may limit the build to a single profile using the XDCARGS
   524         *  command line option, provided the target supports the given profile.
   525         *
   526         *  @p(code)
   527         *  xdc -r XDCARGS="profile=debug" all
   528         *  @p(text)
   529         *
   530         *  @a(Examples)
   531         *  The following example builds the library only for ARM targets and
   532         *  only for the debug and release profiles.
   533         *
   534         *  @p(code)
   535         *  var BuildHelp = xdc.useModule('ti.sdo.tools.build.PackageBuildHelp');
   536         *  var libArray = new Array();
   537         *
   538         *  libArray.push(
   539         *      new BuildHelp.LibAttrs({
   540         *          name: "host",
   541         *          sources: [ "config_host.c" ],
   542         *          icw: [ "v5T" ]
   543         *      })
   544         *   );
   545         *
   546         *  BuildHelp.makeLibraries(libArray, arguments, ["debug","release"]);
   547         *  @p(text)
   548         *  If the build model contained the GCArmv5T, GCArmv6, and C64P targets,
   549         *  the following libraries would be produced. Note, the C64P target is
   550         *  excluded.
   551         *
   552         *  @p(code)
   553         *  lib/debug/host.av5T
   554         *  lib/debug/host.av6
   555         *  lib/release/host.av5T
   556         *  lib/release/host.av6
   557         *  @p(text)
   558         *
   559         *  @param(libAry) An array of library attributes, one for each
   560         *  library to build.
   561         *
   562         *  @param(arguments) The global arguments object passed to the build
   563         *  script which contains the arguments assigned to the XDCARGS
   564         *  environment variable used by the xdc command.
   565         *
   566         *  @param(profiles) Optional. (`String[]`) Array of profile names to
   567         *  build provided the target supports the profile. If not supported
   568         *  by the target, the profile is ignored. When omitted, all profiles
   569         *  defined in the target will be used. If a profile is specified in
   570         *  XDCARGS as described above, this parameter is ignored.
   571         */
   572        Void makeLibraries(
   573                LibAttrs    libAry[],
   574                Any         arguments,
   575                Any         profiles = undefined
   576            );
   577    }
   578    /*
   579     *  @(#) ti.sdo.tools.build; 1, 0, 0,33; 10-29-2010 17:24:29; /db/atree/library/trees/osal/osal-c12x/src/ xlibrary
   580    
   581     */
   582