| metaonly module xdc.bld.Library |
 |
 |
 |
Model of a searchable collection of object files
A library is a collection of one or more object files that is searched
to resolve undefined references at link time.
[ more ... ]
| usage | meta-domain | sourced in xdc/bld/Library.xdc |
var Library = xdc.useModule('xdc.bld.Library');
module-wide constants & types
obj.profile// target options profile = String ...
obj.aopts// asm options for objects = String ...
obj.copts// C/C++ options for objects = String ...
obj.defs// definitions for added objects = String ...
obj.incs// include options for objects = String ...
obj.aropts// library-specific archiver options = String ...
obj.suffix// optional suffix of library name; e.g.,".lib" = String ...
obj.exportSrc// if true, export library sources to releases = Bool ...
per-instance config parameters
per-instance functions
inst.addObjects// Add specified object to be built and archived into this library(String[] names , Object.Attrs objAttrs ) returns Void
DETAILS
A library is a collection of one or more object files that is searched
to resolve undefined references at link time.
Instances of this module represent a target independent collection of
object files that implement a single set of APIs. Thus, a library is
really a container of target-specific archives which contain the object
files necessary to implement a common API. Although, a library may
contain target dependent APIs, each library is expected to
encapsulate the same basic functionality independent of the target.
Instances must be created via the
xdc.bld.PackageContents.addLibrary() function; this
ensures that each library created appears in the package's manifest and
that it properly "inherits" appropriate default attributes from the
containing package.
Library instances are initially create without *any* objects; this ensures
that the developer complete control over what objects should be in each
library. Thus, even modules declared in a package's specification,
package.xdc, must be explicitly added to each library in the package
(via addObjects()).
| struct Library.Attrs |
|
Optional attributes for a Library instance
| usage | meta-domain |
var obj = new Library.Attrs;
obj.profile = String ...
// target options profile
obj.aopts = String ...
// asm options for objects
obj.copts = String ...
// C/C++ options for objects
obj.defs = String ...
// definitions for added objects
obj.incs = String ...
// include options for objects
obj.aropts = String ...
// library-specific archiver options
obj.suffix = String ...
// optional suffix of library name; e.g.,".lib"
obj.exportSrc = Bool ...
// if true, export library sources to releases
obj.releases = Release.Instance[] ...
// releases this library is a part of
FIELDS
incs
— This string contains include path options used by
the compiler (or assembler) to locate include files; e.g.,
"-I ../../include -I ../c55xx". Note that the syntax of
this string may be target dependent.
defs
— This string contains options used by the
compiler (or assembler) to define macros; e.g.,
"-D_C6xxx -DDEBUG=1". Note that the syntax of
this string may be target dependent.
aopts
— This string contains options used by the assembler
to produce object files; e.g., "-mP1". Note that the syntax
of this string may be target dependent.
copts
— This string contains options used by the C/C++
compiler to produce object files; e.g., "-o3 -mi1". Note
that the syntax of this string may be target dependent.
aropts
— This string contains options used by the archiver
produce archive files; e.g., "-q". Note
that the syntax of this string may be target dependent.
exportSrc
— If this field is set to true, the sources
specified via addObjects()
will be part of the releases named in the releases
array. If it is unspecified (or set to null) and the
release specifies that sources are to be exported,
the sources will be part of the release. In
all other cases, the sources are not part of the
release.
suffix
— If this string is set to a non-null value, it
specifies the suffix (or extension) of the archive produced.
This suffix is used in lieu of the default suffix
(".a<targ_suffix>", where <targ_suffix> is the suffix
property of the target used to create the archive). So,
care must be taken when creating multiple libraries for
different targets to ensure that the resulting archive names
are unique.
profile
— This string names a profile defined by the
library's target. The profile specifies a set of compiler,
assembler, and archiver options that are to be used when
producing the archive. Note that these tool options are
in addition to any options specified via aopts, copts,
etc.
releases
— This array contains releases that will contain the
library. Thus, a single library can be part of any set of
releases. Each library is always added to the package's
"default release" in addition to any releases specified in
the releases array.
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.
Suppose, for example, that you want all archives in this
package to be build with the 'release' profile, but one particular
archive must be built with 'debug' (because it is a source example).
The following build script fragment shows how this can be
accomplished:
Pkg.attrs.profile = 'release';
var lib = Pkg.addLibrary('example', ..., {profile: 'debug'});
SEE
| Instance Config Parameters |
|
| usage | meta-domain |
var params = new Library.Params;
// Instance config-params object
// This library's optional attributes
params.name = String undefined;
// The base name of the library
// The target used to build objects added to this library
| config Library.attrs // instance |
|
This library's optional attributes
| usage | meta-domain |
DETAILS
These attributes are "inherited" by all objects added to this
library; i.e., any object attribute that is undefined but is
defined here will be assigned the value from these attributes.
Similarly, any unspecified attributes that also appear in
xdc.bld.PackageContents.Attrs are inherited from
xdc.bld.PackageContents.attrs.
SEE
| config Library.name // instance |
|
The base name of the library
| usage | meta-domain |
var params = new Library.Params;
...
params.name = String undefined;
DETAILS
This name names a sub-directory in the package directory that
contains all the object files and archives created for each of the
targets specified.
The name of each library is <name>/<name>.a<target_suffix>, where
<name> is the base name and <target_suffix> is the suffix property
of the target for which the library is built. For example, one is
building a "hello" library for big endian C62 the library's file
name is "hello/hello.a62e"
| config Library.target // instance |
|
The target used to build objects added to this library
| usage | meta-domain |
| Library.addObjects() // instance |
|
Add specified object to be built and archived into this library
| usage | meta-domain |
ARGUMENTS
names
— array of base names of the sources of object files
to be created and archived into the library.
See NOTE in xdc.bld for filename rules.
objAttrs
— optional Object.Attrs for the array of
objects added; all objects named by names will be
given the attributes objAttrs.
DETAILS
Examples
1. Locate a source file whose name starts with "fir" with
an extension supported by the library's target, compile it
and add to the library lib:
lib.addObjects(["fir"]);
If fir.c exists compile and add to lib, if fir.asm exists
assemble and add to lib, etc. If no such file is located,
an warning is emitted.
2. Compile fir.c and iir.c and add to the library lib:
lib.addObjects(["fir.c", "iir.c"]);
3. Names may include sub-directory prefixes. In this case, the
source will be located in a sub-directory of the current
package. The following statement declares that the file
"foo/fir.c" should be compiled and added to the library
lib:
lib.addObjects(["foo/fir.c"]);
As in the previous examples, the extension ".c" is optional.
In case an extension is not supplied, each extension
understood by the target will be tried until a source file
is located.
4. It is also possible to supply file specific compilation
options.
lib.addObjects(["fir.c", "iir.c"], {defs: "-D_DEBUG"});
In this case, both files fir.c and iir.c will be compiled
with the "-D_DEBUG" flag. Any setting of attrs.defs in the
library or package is overridden by this definition.
RETURNS
void
THROWS
Error exceptions are thrown for fatal errors
generated on Thu, 27 Sep 2012 23:21:21 GMT