1
/*******************************************************************************
2
* Copyright (c) 2003, 2010 Rational Software Corporation 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
9
* IBM Rational Software - Initial API and implementation
10
*******************************************************************************/
11
package org.eclipse.cdt.managedbuilder.core;
13
import java.util.List;
15
import org.eclipse.cdt.managedbuilder.internal.core.ManagedBuildInfo;
16
import org.eclipse.cdt.managedbuilder.makegen.IManagedDependencyGeneratorType;
17
import org.eclipse.core.runtime.IPath;
20
* There is a ManagedBuildInfo per CDT managed build project. Here are
21
* some notes on their usage:
22
* o You can look up the managed build info associated with a CDT
23
* project by using ManagedBuildManager.getBuildInfo(IProject).
24
* o Given a ManagedBuildInfo, you can retrieve the associated CDT
25
* managed build system project by using getManagedProject.
26
* o The usage model of a ManagedBuildInfo is:
27
* 1. Call setDefaultConfiguration to set the context
28
* 2. Call other methods (e.g. getBuildArtifactName) which get
29
* information from the default configuration, and the other managed
30
* build system model elements that can be reached from the
33
* @noextend This class is not intended to be subclassed by clients.
34
* @noimplement This interface is not intended to be implemented by clients.
36
public interface IManagedBuildInfo {
37
public static final String DEFAULT_CONFIGURATION = "defaultConfig"; //$NON-NLS-1$
38
public static final String DEFAULT_TARGET = "defaultTarget"; //$NON-NLS-1$
41
* Note: "Target" routines are only currently applicable when loading a CDT 2.0
42
* or earlier managed build project file (.cdtbuild)
46
* Add a new target to the build information for the receiver
48
* @deprecated as of CDT 7.0
51
public void addTarget(ITarget target);
54
* @return <code>true</code> if the build system knows how to
55
* build a file with the extension passed in the argument.
57
* @deprecated as of CDT 7.0
60
public boolean buildsFileType(String srcExt);
63
* Returns <code>IManagedCommandLineInfo</code> for source with extension
64
* The command line info contains values with
65
* build macros resolved to the makefile format.
66
* That is if a user has chosen to expand all macros in the buildfile,
67
* command line info contains values contain all macro references resolved, otherwise, if a user has
68
* chosen to keep the environment build macros unresolved, the command line info contains values contain
69
* the environment macro references converted to the buildfile variable format,
70
* all other macro references are resolved
72
* @param sourceExtension - source extension
73
* @param flags - build flags
74
* @param outputFlag - output flag for build tool
75
* @return IManagedCommandLineInfo
77
* @deprecated - use generateToolCommandLineInfo instead
80
public IManagedCommandLineInfo generateCommandLineInfo( String sourceExtension, String[] flags,
81
String outputFlag, String outputPrefix, String outputName, String[] inputResources );
84
* Returns <code>IManagedCommandLineInfo</code> for source with extension
85
* The command line info contains values with
86
* build macros resolved to the makefile format.
87
* That is if a user has chosen to expand all macros in the buildfile,
88
* command line info contains values contain all macro references resolved, otherwise, if a user has
89
* chosen to keep the environment build macros unresolved, the command line info contains values contain
90
* the environment macro references converted to the buildfile variable format,
91
* all other macro references are resolved
93
public IManagedCommandLineInfo generateToolCommandLineInfo( String sourceExtension, String[] flags,
94
String outputFlag, String outputPrefix, String outputName, String[] inputResources, IPath inputLocation, IPath outputLocation );
97
* Answers a <code>String</code> containing the arguments to be passed to make.
98
* For example, if the user has selected a build that keeps going on error, the
99
* answer would contain {"-k"}.
103
public String getBuildArguments();
107
* Answers the file extension for the receivers build goal without a separator.
109
* @return the extension or an empty string if none is defined
111
public String getBuildArtifactExtension();
114
* Returns the name of the artifact to build for the receiver.
116
* @return Name of the build artifact
118
public String getBuildArtifactName();
121
* Answers a <code>String</code> containing the make command invocation
122
* for the default configuration.
123
* @return build command
125
public String getBuildCommand();
128
* Answers the prebuild step for the default configuration
132
public String getPrebuildStep();
135
* Answers the postbuild step for the default configuration
139
public String getPostbuildStep();
142
* Answers the display string associated with the prebuild step for the default configuration
146
public String getPreannouncebuildStep();
149
* Answers the display string associated with the postbuild step for the default configuration
153
public String getPostannouncebuildStep();
156
* Answers the command needed to remove files on the build machine
158
public String getCleanCommand();
161
* Answers the name of the default configuration, for example <code>Debug</code>
162
* or <code>Release</code>.
164
* @return String name of default configuration
166
public String getConfigurationName();
169
* Answers a <code>String</code> array containing the names of all the configurations
170
* defined for the project.
172
* @return String[] of configuration names
174
public String[] getConfigurationNames();
177
* Get the default configuration associated with the receiver
179
* @return IConfiguration default
181
public IConfiguration getDefaultConfiguration();
183
public IManagedDependencyGeneratorType getDependencyGenerator(String sourceExtension);
186
* Returns a <code>String</code> containing the flags, including
187
* those overridden by the user, for the tool in the configuration
188
* defined by the argument.
189
* The string contains build macros resolved to the makefile format.
190
* That is if a user has chosen to expand all macros in the buildfile,
191
* the string contains all macro references resolved, otherwise, if a user has
192
* chosen to keep the environment build macros unresolved, the string contains
193
* the environment macro references converted to the buildfile variable format,
194
* all other macro references are resolved
196
* @deprecated - use getToolFlagsForConfiguration
199
public String getFlagsForConfiguration(String extension);
202
* Returns a <code>String</code> containing the flags, including
203
* those overridden by the user, for the tool in the configuration
204
* defined by the argument.
205
* The string contains build macros resolved to the makefile format.
206
* That is if a user has chosen to expand all macros in the buildfile,
207
* the string contains all macro references resolved, otherwise, if a user has
208
* chosen to keep the environment build macros unresolved, the string contains
209
* the environment macro references converted to the buildfile variable format,
210
* all other macro references are resolved
212
public String getToolFlagsForConfiguration(String extension, IPath inputLocation, IPath outputLocation);
215
* Returns a <code>String</code> containing the flags, including
216
* those overridden by the user, for the tool that handles the
217
* type of source file defined by the argument.
218
* The string contains build macros resolved to the makefile format.
219
* That is if a user has chosen to expand all macros in the buildfile,
220
* the string contains all macro references resolved, otherwise, if a user has
221
* chosen to keep the environment build macros unresolved, the string contains
222
* the environment macro references converted to the buildfile variable format,
223
* all other macro references are resolved
225
* @deprecated - use getToolFlagsForSource
228
public String getFlagsForSource(String extension);
231
* Returns a <code>String</code> containing the flags, including
232
* those overridden by the user, for the tool that handles the
233
* type of source file defined by the argument.
234
* The string contains build macros resolved to the makefile format.
235
* That is if a user has chosen to expand all macros in the buildfile,
236
* the string contains all macro references resolved, otherwise, if a user has
237
* chosen to keep the environment build macros unresolved, the string contains
238
* the environment macro references converted to the buildfile variable format,
239
* all other macro references are resolved
241
public String getToolFlagsForSource(String extension, IPath inputLocation, IPath outputLocation);
244
* Answers the libraries the project links in.
246
public String[] getLibsForConfiguration(String extension);
249
* Returns the ManagedProject associated with this build info
251
* @return IManagedProject
253
public IManagedProject getManagedProject( );
256
* Answers the extension that will be built by the current configuration
257
* for the extension passed in the argument or <code>null</code>.
259
public String getOutputExtension(String resourceExtension);
262
* Answers the flag to be passed to the build tool to produce a specific output
263
* or an empty <code>String</code> if there is no special flag. For example, the
264
* GCC tools use the '-o' flag to produce a named output, for example
265
* gcc -c foo.c -o foo.o
267
public String getOutputFlag(String outputExt);
270
* Answers the prefix that should be prepended to the name of the build
271
* artifact. For example, a library foo, should have the prefix 'lib' and
272
* the extension '.a', so the final goal would be 'libfoo.a'
274
* @return the prefix or an empty string
276
public String getOutputPrefix(String outputExtension);
279
* Returns the currently selected configuration. This is used while the project
280
* property pages are displayed
282
* @return IConfiguration
284
public IConfiguration getSelectedConfiguration();
287
* @return the target specified in the argument.
289
* @deprecated as of CDT 7.0
292
public ITarget getTarget(String id);
295
* Get all of the targets associated with the receiver.
296
* @return List<ITarget>
298
* @deprecated as of CDT 7.0
301
public List<ITarget> getTargets();
304
* Returns a <code>String</code> containing the command-line invocation
305
* for the tool associated with the output extension.
307
* @param extension the file extension of the output file
308
* @return a String containing the command line invocation for the tool
310
public String getToolForConfiguration(String extension);
313
* Returns a <code>String</code> containing the command-line invocation
314
* for the tool associated with the source extension.
316
* @param sourceExtension the file extension of the file to be built
317
* @return a String containing the command line invocation for the tool
319
public String getToolForSource(String sourceExtension);
322
* Returns a <code>ITool</code> for the tool associated with the
325
* @param extension the file extension of the input file
328
public ITool getToolFromInputExtension(String extension);
331
* Returns a <code>ITool</code> for the tool associated with the
334
* @param extension the file extension of the output file
337
public ITool getToolFromOutputExtension(String extension);
340
* @param extension the file extension of the build target
342
* @return a <code>String</code> array containing the contents of the
343
* user objects option, if one is defined for the target.
345
public String[] getUserObjectsForConfiguration(String extension);
349
* Answers the version of the build information in the format
350
* @return a <code>String</code> containing the build information
353
public String getVersion();
356
* Answers true if the build model has been changed by the user.
360
public boolean isDirty();
363
* Answers <code>true</code> if the extension matches one of the special
364
* file extensions the tools for the configuration consider to be a header file.
366
* @param ext the file extension of the resource
369
public boolean isHeaderFile(String ext);
372
* Gets the read only status of Managed Build Info
374
* @return <code>true</code> if Managed Build Info is read only
375
* otherwise returns <code>false</code>
377
public boolean isReadOnly();
380
* Gets the "valid" status of Managed Build Info. Managed Build Info is invalid
381
* if the loading of, or conversion to, the Managed Build Info failed.
383
* @return <code>true</code> if Managed Build Info is valid,
384
* otherwise returns <code>false</code>
386
public boolean isValid();
389
* Answers whether the receiver has been changed and requires the
390
* project to be rebuilt. When a project is first created, it is
391
* assumed that the user will need it to be fully rebuilt. However
392
* only option and tool command changes will trigger the build
393
* information for an existing project to require a rebuild.
395
* Clients can reset the state to force or clear the rebuild status
396
* using <code>setRebuildState()</code>
397
* @see ManagedBuildInfo#setRebuildState(boolean)
399
* @return <code>true</code> if the resource managed by the
400
* receiver needs to be rebuilt
402
public boolean needsRebuild();
404
public void removeTarget(String id);
407
* Set the primary configuration for the receiver.
409
* @param configuration The <code>IConfiguration</code> that will be used as the default
412
public void setDefaultConfiguration(IConfiguration configuration);
415
* @return boolean indicating if setDefaultConfiguration was successful
417
public boolean setDefaultConfiguration(String configName);
420
* Sets the dirty flag for the build model to the value of the argument.
422
public void setDirty(boolean isDirty);
425
* Sets the valid flag for the build model to the value of the argument.
427
public void setValid(boolean isValid);
430
* Sets the ManagedProject associated with this build info
432
public void setManagedProject(IManagedProject project);
435
* sets the read only status of Managed Build Info
437
public void setReadOnly(boolean readOnly);
440
* Sets the rebuild state in the receiver to the value of the argument.
441
* This is a potentially expensive option, so setting it to true should
442
* only be done if a project resource or setting has been modified in a
443
* way that would invalidate the previous build.
445
* @param rebuild <code>true</code> will force a rebuild the next time the project builds
447
public void setRebuildState(boolean rebuild);
450
* Sets the currently selected configuration. This is used while the project
451
* property pages are displayed
453
* @param configuration the user selection
455
public void setSelectedConfiguration(IConfiguration configuration);