/* --COPYRIGHT--,EPL
 *  Copyright (c) 2008 Texas Instruments and others.
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  which accompanies this distribution, and is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 * 
 *  Contributors:
 *      Texas Instruments - initial implementation
 * 
 * --/COPYRIGHT--*/
/*
 *  ======== Release.xdc ========
 */
package xdc.bld;

/*!
 *  ======== Release ========
 *  Model of an archive of all files that are part of a release.
 *
 *  Release instances define a container object that represents all files that
 *  are part of a release of a package.  A release may, for example, include
 *  just the files necessary to support a particular ISA even though the
 *  package as a whole can support multiple ISAs.
 *
 *  Each Release instance is realized as a tar file containing the files
 *  that are part of a release of a package.
 */
metaonly module Release {

    /*!
     *  ======== Attrs ========
     *  Optional Release attributes
     *
     *  Unspecified attributes are "inherited" from
     *  `{@link xdc.bld.PackageContents#Attrs}`; i.e., if one of fields in
     *  this structure is unspecified *and* this field's name matches a field
     *  name in `{@link xdc.bld.PackageContents#Attrs}`, then
     *  this field's value defaults to the value in specified by
     *  `{@link xdc.bld.PackageContents#attrs}`.  This mechanism makes it
     *  possible to establish package-wide default values for any of the
     *  "inherited" attributes.
     *
     *  However, elements added to a release can "override" these attributes.
     *  For example, when an executable is added to a release and the
     *  executable's attributes specify `'exportSrc = false'`, the release
     *  will not contain the executable's sources (even if the release's
     *  `{@link #attrs}.exportSrc` attribute is set to `true`).
     *
     *  @field(exportCfg)  If this field is set to `true`, configuration
     *          scripts will be part of the release.  If it is unspecified
     *          (or set to `null`), program configuration scripts will not
     *          be added to this release.
     *
     *  @field(exportDoc)  If this field is set to `true`,  generated
     *          documentation will be part of the release.
     *
     *  @field(exportSrc)  If this field is set to `true`, sources
     *          used to produce object files will be part of the release.
     *          If it is unspecified (or set to `null`), no sources will
     *          be part of this release.
     *
     *  @field(exportExe)  If this field is set to `true`, executables
     *          will be part of the release.  If it is unspecified (or set
     *          to `null`), executables will not be part of this release.
     *
     *  @field(exportAll)  If this field is set to `true`, all files
     *          in this package that are not known to be generated are in
     *          the release.  If it is unspecified (or set to `null`), these
     *          files will not be added to this release.
     *
     *          Note that the set of files specified by `exportAll` is
     *          determined at the time the package's makefile is generated.
     *          If one of these files is subsequently removed before the
     *          release is built, the build of the release will fail; a file
     *          required by the release no longer exists.  If the file is
     *          not really required for the release, you must trigger a
     *          rebuild for the generated makefiles; either touch
     *          `package.bld` or remove the generated makefile and re-build
     *          the release.
     *
     *  @field(relScript)  If this field is non-`null`, the string names a
     *          "release script" that is run to post-process the
     *          files that are part of a release.  Like
     *          configuration scripts, the string names a script
     *          file that is searched for first in the in package's
     *          base directory, and then along the package path.  See
     *          `{@link Manifest}` for more information about release scripts
     *          and what they can do.
     *
     *  @field(relScriptArgs)  If this field is non-`null`, the string is
     *          used to initialize the `arguments[]` array which is
     *          accessible to the release script named by `relScript`.  The
     *          elements of the `arguments[]` array are formed from the white
     *          space separated elements of `relScriptArgs`.  If this string
     *          is `null` or empty, the `arguments[]` array has length `0`.
     *
     *  @field(label)  This string allows one to "tag" each release with a
     *          label that can be used by other tools to select appropriate
     *          releases.  For example, the label might contain customer names.
     *
     *          This label is not interpreted by the XDC tools.  It is simply 
     *          recorded in the package's build model XML file
     *          (`package/package.bld.xml`) and retrieved via
     *          `{@link xdc.bld.BuildEnvironment#getReleaseDescs()}`
     *
     *  @field(prefix)  This string allows one to "export" each release to a
     *          location outside of the package.  `prefix` is prepended
     *          to the name of the release name to form the name of the
     *          release archive.
     *
     *          For example, setting `prefix` to `"../"` implies that a 
     *          release named `"exports/foo"` generates an archive file named
     *          `foo.tar` in the directory `"../exports"`.
     *
     *          `prefix` must either begin with the '^' character or
     *          be a path that is relative to the package's "base"
     *          directory; i.e., the directory containing the package's
     *          specification file `package.xdc`.
     *
     *          If `prefix` begins with the '^' character, the
     *          remainder of the string is treated as though it is relative
     *          to the package's repository.  In effect, the '^' character is
     *          replaced with an appropriate number of '../' sequences to
     *          sufficient to navigate to the package's repository.
     *
     *          If it is not specified (or set to `null`) the current setting
     *          of `{@link xdc.bld.PackageContents#releasePrefix}` is used.
     *
     *  @field(compress) If this field is set to `true`, the release
     *          archive file will be compressed; otherwise, the
     *          archive will not be compressed.  Archives are compressed
     *          via `gzip`; compressed archives are `.tar.gz` files.
     *
     *  @field(archiver) This field names the archiver to use when creating a
     *          release.  Two archivers are currently supported:
     *          "tar" and "zip".  If the archiver is set to "zip"
     *          the `{@link #Attrs.compress}` field is implicitly set to
     *          `true`.
     *
     *  @see #attrs
     */
    struct Attrs {
        String  archiver;       /*! "tar" or "zip"; defaults to "tar" */
        Bool    compress;       /*! if `true`, compress package archive */
        Bool    exportDoc;      /*! if `true`, export generated docs */
        Bool    exportExe;      /*! if `true`, export program executables */
        Bool    exportCfg;      /*! if `true`, export program cfg scripts */
        Bool    exportSrc;      /*! if `true`, export all package sources */
        Bool    exportAll;      /*! if `true`, export all files in package */
        String  relScript;      /*! release files post-processing script */
        String  relScriptArgs;  /*! optional arguments to relScript */
        String  prefix;         /*! prefix for name of install of archive */
        String  label;          /*! uninterpreted label for this release */
    };

    /*!
     *  ======== Desc ========
     *  A description of a release
     *
     *  This structure provides information about a release that can be
     *  used to select from multiple releases provided by a package.
     *
     *  @see xdc.bld.BuildEnvironment#getReleaseDescs()
     */
    struct Desc {
        String name;    /*! the name used to create the release */
        String aname;   /*! the file name of the archive */
        String label;   /*! the label given to the release */
    };
    
    /*!
     *  ======== DescArray ========
     *  An array of release descriptors
     */
    typedef Desc DescArray[];

instance:
    /*!
     *  ======== create ========
     *  @_nodoc
     *  Instances should only be created via PackageContents.addRelease()
     */
    create();

    /*!
     *  ======== name ========
     *  The name of the release.
     *
     *  This name is the base name of the generated tar file containing all
     *  files that make up the release.  For example, if the name of the
     *  release is "foo" then the file "foo.tar" (located in the same
     *  directory as package.bld) is a tar file containing the release files.
     *
     *  Note that each package has at least one release defined, the default
     *  release.  The default release's name is the name of the package with
     *  '.'s replaced with '_'s.  For example, the default release name for
     *  the package "foo.bar" is "foo_bar" and the generated tar file is
     *  named "foo_bar.tar".
     */
    config String name;
    
    /*!
     *  ======== attrs ========
     *  This instance's attributes.
     *
     *  Unless explicitly specified, these attributes are "inherited" from
     *  the package's attributes (`{@link xdc.bld.PackageContents#attrs}`)
     *
     *  @see xdc.bld.PackageContents#attrs
     */
    config Release.Attrs attrs;

    /*!
     *  ======== otherFiles ========
     *  Additional files to add to this release.
     *
     *  This is an array of arbitrary files that are to be included
     *  in this release of the package.
     *
     *  Only those files that are not already directly (or indirectly) named
     *  by adding programs or libraries to this release need to appear in
     *  this array.
     */
    config String otherFiles[];

    /*!
     *  ======== excludeDirs ========
     *  List of directory base names to exclude
     *
     *  This is an array of arbitrary directory "base names" that should
     *  be excluded in this release of the package.  This list only
     *  excludes directories that would otherwise be added due to the
     *  recursive include of a parent directory.
     *
     *  For example, if a directory is specified in `{@link #otherFiles}`
     *  all of its sub-directories will be added unless those sub-directories
     *  are named in the `excludeDirs` list.
     *
     *  This list is often used to exclude "hidden" directories added by
     *  change control systems and IDEs (`.svn`, `.git`, `.settings`, ...).
     *
     *  @see #otherFiles
     *  @see PackageContents#excludeDirs
     */
    config String excludeDirs[];
}