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 * ======== 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(objList) String
123 * @param(archArgs) `{@link xdc.bld.ITarget#ArchiveGoal}`
124 * @param(result) `{@link xdc.bld.ITarget#CommandSet}`
125 */
126 function archive(container, lib, objList, archArgs, result);
127
128 /*!
129 * ======== compile ========
130 * Compile command filter
131 *
132 * This method is called for every object created by the package's
133 * build script (via `{@link xdc.bld.Executable#addObjects()}`,
134 * `{@link xdc.bld.Library#addObjects()}`, ...).
135 *
136 * @param(container) String
137 * @param(target) `{@link xdc.bld.ITarget}.Module`
138 * @param(goal) String goal file
139 * @param(compArgs) `{@link xdc.bld.ITarget#CompileGoal}` the file to
140 * compile
141 * @param(result) `{@link xdc.bld.ITarget#CommandSet}`
142 */
143 function compile(container, target, goal, compArgs, result);
144
145 /*!
146 * ======== getGenTab ========
147 * Get table of files to be generated during configuration
148 *
149 * This method is called during makefile generation to obtain
150 * a list of additional files to be generated during configuration.
151 *
152 * @param(acfg) `{@link xdc.bld.Configuration}` or Assembly
153 * @param(cfgDir) String directory name where generated config files
154 * are placed
155 * @param(configName) String base name of the configuration
156 * @a(RETURNS) array of `{@link #GenDesc}`
157 */
158 function getGenTab(acfg, cfgDir, configName);
159
160 /*!
161 * ======== getDefs ========
162 * Get table of macro definitions
163 *
164 * This method is called during makefile generation to obtain
165 * a list of macro definitions that are to be added to the
166 * generated makefile. These macros can then be referenced by
167 * commands added via a filter function (`{@link #archive()}`,
168 * `{@link #compile()}` or `{@link #link()}`).
169 *
170 * @a(RETURNS) array of `{@link #MacroDesc}`
171 */
172 function getDefs();
173
174 /*!
175 * ======== link ========
176 * Link command filter
177 *
178 * This method is called for every executable created by the package's
179 * build script (via `{@link xdc.bld.PackageContents#addExecutable()}`,
180 * ...).
181 *
182 * @param(container) String
183 * @param(cfgbase) String
184 * @param(prog) Executable or Assembly
185 * @param(objList) String
186 * @param(linkArgs) `{@link xdc.bld.ITarget#LinkGoal}`
187 * @param(result) `{@link xdc.bld.ITarget#CommandSet}`
188 */
189 function link(container, cfgBase, prog, objList, linkArgs, result);
190 }
191 /*
192 * @(#) xdc.bld; 1, 0, 2,340; 6-14-2011 11:49:19; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
193 */
194