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 * ======== ITargetFilter ========
14 * User-supplied filter of a target's command set
15 *
16 * This interface defines a set of user-supplied methods that are invoked
17 * during the Build Model's makefile generation process. These methods
18 * can augment or modify the commands that are placed in the generated
19 * makefiles. For example, an `ITargetFilter` module can add pre or post
20 * build steps for virtually any generated file.
21 *
22 * Filters can:
23 * @p(nlist) 24 * - modify or augment the commands returned by a target's compile,
25 * link and archive methods via `{@link #compile}`, `{@link #link}`,
26 * and `{@link #archive}`;
27 * - add new definitions to the generated makefiles usable by the
28 * command added above via `{@link #getDefs}`; and
29 * - specify new files to be generated during the configuration process
30 * that may be used during or after the link process via
31 * `{@link #getGenTab}`.
32 * @p 33 * Filters are created implicitly when a target's profile
34 * (`{@link xdc.bld.ITarget#profiles}`) that references the filter is used.
35 * To use a filter, one must configure a profile's option set
36 * (`{@link xdc.bld.ITarget#OptionSet}`) in the build configuration script
37 * `config.bld`. It is possible to add filters to existing profiles (such
38 * as `"debug"` and `"release"`) or to create entirely new profiles that
39 * utilize the filters.
40 *
41 * When modifying existing profiles, no changes to individual packages using
42 * these profiles is required; one simply has to clean and rebuild these
43 * packages for the filters to have an effect.
44 *
45 * By adding new profiles, one can ensure that existing build artifacts are
46 * unchanged and only those packages that want to take advantage of a filter
47 * can do so easily by adding a new build artifact that uses the new
48 * profile; for example, see `{@link xdc.bld.Library#Attrs}`.
49 */
50 metaonlyinterface ITargetFilter
51 {
52 /*!
53 * ======== InstDesc ========
54 * `ITargetFilter` Instance descriptor
55 *
56 * This structure provides the information necessary to create an
57 * instance of an `ITargetFilter`.
58 *
59 * @see xdc.bld.ITarget#OptionSet
60 */
61 struct InstDesc {
62 String moduleName; /*! name of a module implementing `ITargetFilter`*/
63 Any params; /*! params passed to ITargetFilter.create() */
64 };
65
66 /*!
67 * ======== GenDesc ========
68 * Configuration file generation descriptor
69 *
70 * This structure is used to specify a new file to be generated during
71 * the configuration process.
72 *
73 * Templates are expanded in the context of the Configuration domain;
74 * as a result, the contents of the generated file can be a function
75 * of an executable's `{@link xdc.cfg.Program}` object. Template names
76 * are interpreted using the `xdc.findFile()` method to
77 * locate the template file name. Templates can, therefore, be
78 * contained in any package located along the package path.
79 *
80 * Names of files to be generated are always interpreted relative to
81 * the base directory of the package for which makefiles are being
82 * generated.
83 *
84 * @see #getGenTab
85 */
86 struct GenDesc {
87 String template; /*! name of the template to expand */
88 String file; /*! the name of the file to generate */
89 };
90
91 /*!
92 * ======== MacroDesc ========
93 * Macro definition descriptor
94 *
95 * This structure is used to specify macro name-value pairs that are
96 * added to the generated makefiles. These names can be used
97 * by commands added via the filter's `{@link #archive()}`,
98 * `{@link #compile()}`, or `{@link #link()}` methods.
99 *
100 * Using symbolic values in lieu of embeddeding explicit paths or values
101 * enables the end-user to re-define these values without requiring
102 * regeneration of makefiles.
103 *
104 * @see #getDefs
105 */
106 struct MacroDesc {
107 String name; /*! name of the macro */
108 String value; /*! the name value of the macro name */
109 };
110
111 instance:
112
113 /*!
114 * ======== archive ========
115 * Archive command filter
116 *
117 * This method is called for every archive created by the package's
118 * build script (via `{@link xdc.bld.PackageContents#addLibrary()}`).
119 *
120 * @param(container) String
121 * @param(lib) `{@link xdc.bld.Library}`
122 * @param(archArgs) `{@link xdc.bld.ITarget#ArchiveGoal}`
123 * @param(result) `{@link xdc.bld.ITarget#CommandSet}`
124 */
125 function archive(container, lib, objList, archArgs, result);
126
127 /*!
128 * ======== compile ========
129 * Compile command filter
130 *
131 * This method is called for every object created by the package's
132 * build script (via `{@link xdc.bld.Executable#addObjects()}`,
133 * `{@link xdc.bld.Library#addObjects()}`, ...).
134 *
135 * @param(container) String
136 * @param(target) `{@link xdc.bld.ITarget}.Module`
137 * @param(goal) String goal file
138 * @param(compArgs) `{@link xdc.bld.ITarget#CompileGoal}` the file to
139 * compile
140 * @param(result) `{@link xdc.bld.ITarget#CommandSet}`
141 */
142 function compile(container, target, goal, compArgs, result);
143
144 /*!
145 * ======== getGenTab ========
146 * Get table of files to be generated during configuration
147 *
148 * This method is called during makefile generation to obtain
149 * a list of additional files to be generated during configuration.
150 *
151 * @param(prog) `{@link xdc.bld.Executable}` or Assembly
152 * @param(cfgDir) String directory where generated config files are
153 * placed
154 * @param(configName) String base name of the configuration
155 * @a(RETURNS) array of `{@link #GenDesc}`
156 */
157 function getGenTab(prog, cfgDir, configName);
158
159 /*!
160 * ======== getDefs ========
161 * Get table of macro definitions
162 *
163 * This method is called during makefile generation to obtain
164 * a list of macro definitions that are to be added to the
165 * generated makefile. These macros can then be referenced by
166 * commands added via a filter function (`{@link #archive()}`,
167 * `{@link #compile()}` or `{@link #link()}`).
168 *
169 * @a(RETURNS) array of `{@link #MacroDesc}`
170 */
171 function getDefs();
172
173 /*!
174 * ======== link ========
175 * Link command filter
176 *
177 * This method is called for every executable created by the package's
178 * build script (via `{@link xdc.bld.PackageContents#addExecutable()}`,
179 * ...).
180 *
181 * @param(container) String
182 * @param(cfgbase) String
183 * @param(prog) Executable or Assembly
184 * @param(objList) String
185 * @param(linkArgs) `{@link xdc.bld.ITarget#LinkGoal}`
186 * @param(result) `{@link xdc.bld.ITarget#CommandSet}`
187 */
188 function link(container, cfgBase, prog, objList, linkArgs, result);
189 }
190 /*
191 * @(#) xdc.bld; 1, 0, 2,215; 7-29-2009 14:53:06; /db/ztree/library/trees/xdc-t56x/src/packages/
192 */
193