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