1    /* 
     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     * */
    12    /*
    13     *  ======== Repository.xdc ========
    14     */
    15    package xdc.bld;
    16    
    17    /*!
    18     *  ======== Repository ========
    19     *  Model of a package repository
    20     */
    21    metaonly module Repository {
    22    
    23        /*!
    24         *  ======== Attrs ========
    25         *  Optional attributes for a repository
    26         *
    27         *  @field(releases)  This array contains releases that will contain the
    28         *          repository.  Thus, a single repository can be part of any set 
    29         *          of releases.  Each repository is always added to the 
    30         *          package's "default release" in addition to any releases
    31         *          specified in the releases array.
    32         *
    33         *  @field(search) By default, the release archives of all packages added
    34         *          to a repository are required to exist in the package's release
    35         *          output directory at the time the repository is created.
    36         *
    37         *          However, if this flag is set to `true`, each package's release
    38         *          will be searched for at the time that the makefile for the
    39         *          package containing this repository is created.  This allows
    40         *          package releases that exist before this repository is being
    41         *          built to more easily be added to this repository.
    42         *
    43         *          For example, package release archives can be moved to arbitrary
    44         *          directories after they are created but before a package containing
    45         *          a repository that includes these releases is built.
    46         *
    47         *          Package releases are searched for by looking in the following
    48         *          locations (in order): the package's release archive output
    49         *          directory, along the specified `archivePath`, and finally along
    50         *          the current package path.
    51         *
    52         *          If a package release archive cannot be found in the package's 
    53         *          release output directory or along the `archivePath`, the package
    54         *          path will be searched for the package itself (not its release 
    55         *          archive).  So, if the package appears on the package path _and_ 
    56         *          it's a released package with the specified release name, the 
    57         *          package will simply be copied into this repository.
    58         *
    59         *          Finally, if the package release can't be found, and error is
    60         *          thrown.
    61         *
    62         *  @field(archivePath) This ';' separated list of directories is used to
    63         *          find package release archives when the `search` flag is set to
    64         *          `true`.  If `archivePath` is `null`, no search path will be
    65         *          used and the package release itself (not the archive) may be found
    66         *          along the package path.
    67         *
    68         *  @see #attrs
    69         */
    70        struct Attrs {
    71            Release.Instance releases[];    /*! releases this repo is a part of */
    72            Bool             search;        /*! true => search path for packages */
    73            String           archivePath;   /*! search path for package archives */
    74        };
    75    
    76    instance:
    77        /*!
    78         *  ======== create ========
    79         *  @_nodoc
    80         *  Instances should only be created via PackageContents.addRepository()
    81         */
    82        create();
    83    
    84        /*!
    85         *  ======== name ========
    86         *  The repository's directory name
    87         */
    88        config String name;
    89    
    90        /*!
    91         *  ======== attrs ========
    92         *  The repository's attributes
    93         */
    94        config Attrs attrs;
    95    
    96        /*!
    97         *  ======== addPackages ========
    98         *  Add specified package releases to this repository
    99         *
   100         *  @param(names) An array of strings naming package releases to be added
   101         *          to the repository.  Package releases are named as follows:
   102         *          @p(code)
   103         *              <pkgName>:<releaseName>
   104         *          @p
   105         *          where `<pkgName>` is the name of the package to add to the
   106         *          repository and `<releaseName>` is the name of one of that
   107         *          package's releases.  A package release name may be either the
   108         *          archive file name (relative to the package's base directory)
   109         *          of the release archive or the name used create the release in
   110         *          package named `<pkgName>`.
   111         *
   112         *          For example, if the package `ti.bios` had a release named
   113         *          `exports/ti_bios,src`, the following statements would add
   114         *          this release to the repository named `packages`:
   115         *          @p(code)
   116         *              var r = Pkg.addRepository("packages");
   117         *              r.addPackages(["ti.bios:exports/ti_bios,src"]);
   118         *          @p
   119         *
   120         *          Alternatively, one can specify the archive file name:
   121         *          @p(code)
   122         *              var r = Pkg.addRepository("packages");
   123         *              r.addPackages(["ti.bios:exports/ti_bios,src.tar"]);
   124         *          @p
   125         *
   126         *          It is possible to get a list of release archive names from a
   127         *          package via the
   128         *          `{@link xdc.bld.BuildEnvironment#getReleaseDescs()}`
   129         *          method.  For example, to get the physical archive name of the
   130         *          default release of the `ti.bios` package, the following loop
   131         *          can be added to a build script:
   132         *          @p(code)
   133         *              var archiveName;
   134         *              var rels = Build.getReleaseDescs('ti.bios');
   135         *              for (var j = 0; j < rels.length; j++) {
   136         *                  if (rels[j].label == "default") {
   137         *                      archiveName = rels[j].aname;
   138         *                      break;
   139         *                  }
   140         *              }
   141         *              // archiveName is now set to the file name of the ti.bios
   142         *              // default release archive (or undefined)
   143         *          @p
   144         *
   145         *  @see xdc.bld.BuildEnvironment#getReleaseDescs()
   146         */
   147        Void addPackages(String names[]);
   148    }
   149    /*
   150     *  @(#) xdc.bld; 1, 0, 2,0; 2-20-2019 10:21:42; /db/ztree/library/trees/xdc/xdc-F09/src/packages/
   151     */
   152