metaonly module xdc.bld.Release
index URL

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. [ more ... ]
XDCscript usage meta-domain sourced in xdc/bld/Release.xdc
var Release = xdc.useModule('xdc.bld.Release');
module-wide constants & types
    var obj = new Release.Attrs// Optional Release attributes;
        obj.archiver// "tar" or "zip"; defaults to "tar" = String  ...
        obj.compress// if true, compress package archive = Bool  ...
        obj.exportDoc// if true, export generated docs = Bool  ...
        obj.exportExe// if true, export program executables = Bool  ...
        obj.exportCfg// if true, export program cfg scripts = Bool  ...
        obj.exportSrc// if true, export all package sources = Bool  ...
        obj.exportAll// if true, export all files in package = Bool  ...
        obj.relScript// release files post-processing script = String  ...
        obj.relScriptArgs// optional arguments to relScript = String  ...
        obj.prefix// prefix for name of install of archive = String  ...
        obj.label// uninterpreted label for this release = String  ...
    var obj = new Release.Desc// A description of a release;
        obj.name// the name used to create the release = String  ...
        obj.aname// the file name of the archive = String  ...
        obj.label// the label given to the release = String  ...
per-instance config parameters
    var params = new Release.Params// Instance config-params object;
        params.attrs// This instance's attributes = Release.Attrs undefined;
        params.excludeDirs// List of directory base names to exclude = String[] undefined;
        params.name// The name of the release = String undefined;
        params.otherFiles// Additional files to add to this release = String[] undefined;
 
DETAILS
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.
struct Release.Attrs
index URL

Optional Release attributes

XDCscript usage meta-domain
var obj = new Release.Attrs;
 
    obj.archiver = String  ...
    // "tar" or "zip"; defaults to "tar"
    obj.compress = Bool  ...
    // if true, compress package archive
    obj.exportDoc = Bool  ...
    // if true, export generated docs
    obj.exportExe = Bool  ...
    // if true, export program executables
    obj.exportCfg = Bool  ...
    // if true, export program cfg scripts
    obj.exportSrc = Bool  ...
    // if true, export all package sources
    obj.exportAll = Bool  ...
    // if true, export all files in package
    obj.relScript = String  ...
    // release files post-processing script
    obj.relScriptArgs = String  ...
    // optional arguments to relScript
    obj.prefix = String  ...
    // prefix for name of install of archive
    obj.label = String  ...
    // uninterpreted label for this release
FIELDS
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.
exportDoc — If this field is set to true, generated documentation will be part of the release.
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.
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.
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.
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 Manifest for more information about release scripts and what they can do.
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 argumants[] array are formed from the white space separated elements of relScriptArgs. If this string is null or empty, the arguments[] array has length 0.
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 xdc.bld.BuildEnvironment.getReleaseDescs()
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 xdc.bld.PackageContents.releasePrefix is used.
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.
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 Attrs.compress field is implicitly set to true.
DETAILS
Unspecified attributes are "inherited" from 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 xdc.bld.PackageContents.Attrs, then this field's value defaults to the value in specified by 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 attrs.exportSrc attribute is set to true).
SEE
attrs
struct Release.Desc
index URL

A description of a release

XDCscript usage meta-domain
var obj = new Release.Desc;
 
    obj.name = String  ...
    // the name used to create the release
    obj.aname = String  ...
    // the file name of the archive
    obj.label = String  ...
    // the label given to the release
DETAILS
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()
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Release.Params;
// Instance config-params object
    params.attrs = Release.Attrs undefined;
    // This instance's attributes
    params.excludeDirs = String[] undefined;
    // List of directory base names to exclude
    params.name = String undefined;
    // The name of the release
    params.otherFiles = String[] undefined;
    // Additional files to add to this release
config Release.attrs  // instance
index URL

This instance's attributes

XDCscript usage meta-domain
var params = new Release.Params;
  ...
params.attrs = Release.Attrs undefined;
DETAILS
Unless explicitly specified, these attributes are "inherited" from the package's attributes (xdc.bld.PackageContents.attrs)
SEE
xdc.bld.PackageContents.attrs
config Release.excludeDirs  // instance
index URL

List of directory base names to exclude

XDCscript usage meta-domain
var params = new Release.Params;
  ...
params.excludeDirs = String[] undefined;
DETAILS
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 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, PackageContents.excludeDirs
config Release.name  // instance
index URL

The name of the release

XDCscript usage meta-domain
var params = new Release.Params;
  ...
params.name = String undefined;
DETAILS
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 Release.otherFiles  // instance
index URL

Additional files to add to this release

XDCscript usage meta-domain
var params = new Release.Params;
  ...
params.otherFiles = String[] undefined;
DETAILS
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.
generated on Tue, 24 Aug 2010 15:39:30 GMT