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 * ======== Library.xdc ========
14 */
15 package xdc.bld;
16
17 /*!
18 * ======== Library ========
19 * Model of a searchable collection of object files
20 *
21 * A library is a collection of one or more object files that is searched
22 * to resolve undefined references at link time.
23 *
24 * Instances of this module represent a target independent collection of
25 * object files that implement a single set of APIs. Thus, a library is
26 * really a container of target-specific archives which contain the object
27 * files necessary to implement a common API. Although, a library may
28 * contain target dependent APIs, each library is expected to
29 * encapsulate the same basic functionality independent of the target.
30 *
31 * Instances must be created via the
32 * `{@link xdc.bld.PackageContents#addLibrary()}` function; this
33 * ensures that each library created appears in the package's manifest and
34 * that it properly "inherits" appropriate default attributes from the
35 * containing package.
36 *
37 * Library instances are initially create without *any* objects; this ensures
38 * that the developer complete control over what objects should be in each
39 * library. Thus, even modules declared in a package's specification,
40 * `package.xdc`, must be explicitly added to each library in the package
41 * (via `{@link #addObjects()}`).
42 */
43 metaonlymodule Library {
44 /*!
45 * ======== Attrs ========
46 * Optional attributes for a Library instance.
47 *
48 * Unspecified attributes are "inherited" from
49 * `{@link xdc.bld.PackageContents#Attrs}`; i.e., if one of fields in this
50 * structure is unspecified *and* this field's name matches a field name
51 * in `{@link xdc.bld.PackageContents#attrs}`, then this field's value
52 * defaults to the value in specified by
53 * `{@link xdc.bld.PackageContents#attrs}`. This mechanism makes it
54 * possible to establish package-wide default values for any of the
55 * "inherited" attributes.
56 *
57 * Suppose, for example, that you want all archives in this
58 * package to be build with the '`release`' profile, but one particular
59 * archive must be built with '`debug`' (because it is a source example).
60 * The following build script fragment shows how this can be
61 * accomplished:
62 * @p(code) 63 * Pkg.attrs.profile = 'release';
64 * var lib = Pkg.addLibrary('example', ..., {profile: 'debug'});
65 * @p 66 * @field(incs) This string contains include path options used by
67 * the compiler (or assembler) to locate include files; e.g.,
68 * "`-I ../../include -I ../c55xx`". Note that the syntax of
69 * this string may be target dependent.
70 *
71 * @field(defs) This string contains options used by the
72 * compiler (or assembler) to define macros; e.g.,
73 * "`-D_C6xxx -DDEBUG=1`". Note that the syntax of
74 * this string may be target dependent.
75 *
76 * @field(aopts) This string contains options used by the assembler
77 * to produce object files; e.g., "`-mP1`". Note that the syntax
78 * of this string may be target dependent.
79 *
80 * @field(copts) This string contains options used by the C/C++
81 * compiler to produce object files; e.g., "`-o3 -mi1`". Note
82 * that the syntax of this string may be target dependent.
83 *
84 * @field(aropts) This string contains options used by the archiver
85 * produce archive files; e.g., "`-q`". Note
86 * that the syntax of this string may be target dependent.
87 *
88 * @field(exportSrc) If this field is set to true, the sources
89 * specified via `{@link #addObjects}()`
90 * will be part of the releases named in the releases
91 * array. If it is unspecified (or set to `null`) and the
92 * release specifies that sources are to be exported,
93 * the sources will be part of the release. In
94 * all other cases, the sources are not part of the
95 * release.
96 *
97 * @field(suffix) If this string is set to a non-`null` value, it
98 * specifies the suffix (or extension) of the archive produced.
99 * This suffix is used in lieu of the default suffix
100 * ("`.a<targ_suffix>`", where `<targ_suffix>` is the suffix
101 * property of the target used to create the archive). So,
102 * care must be taken when creating multiple libraries for
103 * different targets to ensure that the resulting archive names
104 * are unique.
105 *
106 * @field(profile) This string names a profile defined by the
107 * library's target. The profile specifies a set of compiler,
108 * assembler, and archiver options that are to be used when
109 * producing the archive. Note that these tool options are
110 * in addition to any options specified via `aopts`, `copts`,
111 * etc.
112 *
113 * @field(releases) This array contains releases that will contain the
114 * library. Thus, a single library can be part of any set of
115 * releases. Each library is always added to the package's
116 * "default release" in addition to any releases specified in
117 * the releases array.
118 *
119 * @see #attrs
120 * @see xdc.bld.PackageContents#Attrs
121 */
122 struct Attrs {
123 String profile; /*! target options profile */
124 String aopts; /*! asm options for objects */
125 String copts; /*! C/C++ options for objects */
126 String defs; /*! definitions for added objects */
127 String incs; /*! include options for objects */
128 String aropts; /*! library-specific archiver options */
129 String suffix; /*! optional suffix of library name; e.g.,".lib" */
130 Bool exportSrc; /*! if true, export library sources to releases */
131 Release.Instance releases[]; /*! releases this library is a part of */
132 };
133
134 instance:
135 /*!
136 * ======== create ========
137 * @_nodoc 138 * Instances should only be created via PackageContents.addLibrary()
139 */
140 create();
141
142 /*!
143 * ======== name ========
144 * The base name of the library.
145 *
146 * This name names a sub-directory in the package directory that
147 * contains all the object files and archives created for each of the
148 * targets specified.
149 *
150 * The name of each library is `<name>/<name>.a<target_suffix>`, where
151 * `<name>` is the base name and `<target_suffix>` is the suffix property
152 * of the target for which the library is built. For example, one is
153 * building a `"hello"` library for big endian C62 the library's file
154 * name is "`hello/hello.a62e`"
155 */
156 config String name;
157
158 /*!
159 * ======== target ========
160 * The target used to build objects added to this library.
161 */
162 config ITarget.Module target;
163
164 /*!
165 * ======== attrs ========
166 * This library's optional attributes.
167 *
168 * These attributes are "inherited" by all objects added to this
169 * library; i.e., any object attribute that is undefined but is
170 * defined here will be assigned the value from these attributes.
171 *
172 * Similarly, any unspecified attributes that also appear in
173 * `{@link xdc.bld.PackageContents#Attrs}` are inherited from
174 * `{@link xdc.bld.PackageContents#attrs}`.
175 *
176 * @see xdc.bld.PackageContents#Attrs
177 */
178 config Library.Attrs attrs;
179
180 /*!
181 * ======== addObjects ========
182 * Add specified object to be built and archived into this library.
183 *
184 * Examples
185 *
186 * 1. Locate a source file whose name starts with "fir" with
187 * an extension supported by the library's target, compile it
188 * and add to the library lib:
189 * @p(code) 190 * lib.addObjects(["fir"]);
191 * @p 192 * If fir.c exists compile and add to lib, if fir.asm exists
193 * assemble and add to lib, etc. If no such file is located,
194 * an warning is emitted.
195 *
196 * 2. Compile `fir.c` and `iir.c` and add to the library `lib`:
197 * @p(code) 198 * lib.addObjects(["fir.c", "iir.c"]);
199 * @p 200 * 3. Names may include sub-directory prefixes. In this case, the
201 * source will be located in a sub-directory of the current
202 * package. The following statement declares that the file
203 * "`foo/fir.c`" should be compiled and added to the library
204 * `lib`:
205 * @p(code) 206 * lib.addObjects(["foo/fir.c"]);
207 * @p 208 * As in the previous examples, the extension ".c" is optional.
209 * In case an extension is not supplied, each extension
210 * understood by the target will be tried until a source file
211 * is located.
212 *
213 * 4. It is also possible to supply file specific compilation
214 * options.
215 * @p(code) 216 * lib.addObjects(["fir.c", "iir.c"], {defs: "-D_DEBUG"});
217 * @p 218 * In this case, both files `fir.c` and `iir.c` will be compiled
219 * with the "`-D_DEBUG`" flag. Any setting of `attrs.defs` in the
220 * library or package is overridden by this definition.
221 *
222 * @param(names) array of base names of the sources of object files
223 * to be created and archived into the library.
224 * See NOTE in `{@link xdc.bld}` for filename rules.
225 *
226 * @param(objAttrs) optional `{@link Object#Attrs}` for the array of
227 * objects added; all objects named by `names` will be
228 * given the attributes `objAttrs`.
229 *
230 * @a(returns) `void`
231 *
232 * @a(throws) `Error` exceptions are thrown for fatal errors
233 *
234 */
235 Void addObjects(String names[], Object.Attrs objAttrs = {});
236 }
237 /*
238 * @(#) xdc.bld; 1, 0, 2,283; 6-23-2010 14:02:58; /db/ztree/library/trees/xdc/xdc-v41x/src/packages/
239 */
240