1 /* --COPYRIGHT--,EPL
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 * --/COPYRIGHT--*/
12 /*
13 * ======== Object.xdc ========
14 */
15 package xdc.bld;
16
17 /*!
18 * ======== Object ========
19 * Model of a compiled (or assembled) form of a source file.
20 *
21 * Instances of this module represent object files. Instances must be
22 * created via either the `{@link xdc.bld.Library#addObjects()}` or
23 * `{@link xdc.bld.Executable#addObjects()}` functions; this ensures that each
24 * object file created appears in the package's manifest and that it
25 * properly "inherits" appropriate default attributes from the containing
26 * library or executable.
27 */
28 metaonlymodule Object {
29 /*!
30 * ======== Attrs ========
31 * Optional attributes for an Object instance
32 *
33 * Unspecified attributes are "inherited" from
34 * `{@link xdc.bld.Executable#Attrs}`
35 * (`{@link xdc.bld.Library#Attrs}`) if this Object is added to an
36 * `{@link xdc.bld.Executable}` (`{@link xdc.bld.Library}`); i.e., if one
37 * of fields in this structure is unspecified *and* this field's name
38 * matches a field name in `{@link xdc.bld.Executable#attrs}`,
39 * then this field's value defaults to the value in specified by
40 * `{@link xdc.bld.Executable#attrs}`. This mechanism makes it possible
41 * to establish executable-wide default value for any of the "inherited"
42 * attributes.
43 *
44 * Suppose, for example, that you want all object files in this package
45 * to be build with the '`-o4`' optimization flag, but one particular file
46 * must be built with '`-o2`' (because the optimizer has a bug that it
47 * causes it to fail on this file). The following build script fragment
48 * shows how this can be accomplished:
49 * @p(code) 50 * var exe = Pkg.addExecutable(..., {copts: '-o4'});
51 * exe.addObjects(['complex'], {copts: '-o2'});
52 * exe.addObjects(['foo', 'bar', ...]);
53 * @p 54 * Since many `Executable.attrs` are "inherited" from
55 * `{@link xdc.bld.PackageContents#attrs}`, it is also possible to
56 * establish package-wide default for these attributes.
57 *
58 * @field(profile) This string names a profile defined by the
59 * target used to produce the object file. The profile
60 * specifies a set of compiler and assembler options that are
61 * to be used when producing the object. Note that these tool
62 * options are in addition to any options specified via aopts,
63 * copts, etc.
64 *
65 * @field(incs) This string contains include path options used by
66 * the compiler (or assembler) to locate include files; e.g.,
67 * "`-I ../../include -I ../c55xx`". Note that the syntax of
68 * this string may be target dependent.
69 *
70 * @field(defs) This string contains options used by the
71 * compiler (or assembler) to define macros; e.g.,
72 * "`-D_C6xxx -DDEBUG=1`". Note that the syntax of
73 * this string may be target dependent.
74 *
75 * @field(aopts) This string contains options used by the assembler
76 * to produce object files; e.g., "`-mP1`". Note that the syntax
77 * of this string may be target dependent.
78 *
79 * @field(copts) This string contains options used by the C/C++
80 * compiler to produce object files; e.g., "`-o3 -mi1`". Note
81 * that the syntax of this string may be target dependent.
82 *
83 * @field(preBuilt) If equal to `true`, this Boolean flag indicates
84 * that this object does not need to be built from sources; e.g.,
85 * it has been pre-built and delivered as a binary file without
86 * sources or some custom rule already built this object file.
87 * For pre-built objects, no rule will be created to remove the
88 * file as part of a package clean operation, the relative path
89 * to the file must be fully specified, and all other Object
90 * attributes are ignored.
91 *
92 * @see #attrs
93 * @see xdc.bld.PackageContents#Attrs
94 * @see xdc.bld.Library#Attrs
95 * @see xdc.bld.Executable#Attrs
96 */
97 struct Attrs {
98 String profile; /*! target options profile */
99 String aopts; /*! asm options for this object */
100 String copts; /*! C/C++ options for this object */
101 String defs; /*! definitions for this object */
102 String incs; /*! include options for this object */
103 Bool preBuilt;/*! don't create a rule to generate this file */
104 };
105
106 instance:
107 /*!
108 * ======== create ========
109 * @_nodoc 110 * Instances should only be created via Executable.addObjects()
111 */
112 create();
113
114 /*!
115 * ======== name ========
116 * The base name of the object file.
117 *
118 * This name is passed as the name field of the
119 * `{@link xdc.bld.ITarget#CompileGoal}`. The object file's name is
120 * composed as follows:
121 * @p(code) 122 * <name>.o<target_suffix>
123 * @p 124 * where `<name>` is name and `<target_suffix>` is the suffix defined
125 * by each target that the file is built for.
126 */
127 config String name;
128
129 /*!
130 * ======== attrs ========
131 * This instance's attributes.
132 *
133 * These attributes (unless otherwise specified) are "inherited" from
134 * the container object that contains this instance.
135 *
136 * @see xdc.bld.PackageContents#Attrs
137 * @see xdc.bld.Executable#Attrs
138 * @see xdc.bld.Library#Attrs
139 */
140 config Object.Attrs attrs;
141 }
142 /*
143 * @(#) xdc.bld; 1, 0, 2,241; 6-21-2010 15:08:52; /db/ztree/library/trees/xdc/xdc-u19x/src/packages/
144 */
145