org.eclipse.cdt.managedbuilder.makegen
Interface IManagedDependencyCommands
- All Superinterfaces:
- IManagedDependencyInfo
- All Known Implementing Classes:
- DefaultGCCDependencyCalculator2Commands, DefaultGCCDependencyCalculator3Commands
public interface IManagedDependencyCommands
- extends IManagedDependencyInfo
- Since:
- 3.1
A Tool dependency calculator may implement this interface or
IManagedDependencyCalculator or IManagedDependencyPreBuild.
An object implementing the interface is returned from a call to
IManagedDependencyGenerator2.getDependencySourceInfo.
Discussion of Dependency Calculation:
There are two major, and multiple minor, modes of dependency calculation
supported by the MBS. The major modes are:
1. The build file generator invokes tool integrator provided methods
that calculate all dependencies using whatever method the tool
integrator wants. The build file generator then adds the dependencies
to the build file using the appropriate build file syntax.
See the IManagedDependencyCalculator interface for more information.
2. The build file generator and the tool-chain cooperate in creating and
using separate "dependency" files. The build file generator calls
the dependency calculator to get the dependency file names and to get
commands that need to be added to the build file. In this case,
dependency calculation is done at "build time", rather than at
"build file generation time" as in mode #1. This currently
supports the GNU concept of using .d files in GNU make.
There are multiple ways that these separate dependency files can
be created by the tool-chain and used by the builder.
a. In some cases (e.g., Fortran 90 using modules) the dependency files
must be created/updated prior to invoking the build of the project
artifact (e.g., an application). In this case, the dependency
generation step must occur separately before the main build.
See the IManagedDependencyPreBuild interface for more information.
b. In other cases (e.g., C/C++) the dependency files can be created as
a side effect of the main build. This implies that the up to date
dependency files are not required for the current build, but for
the next build. C/C++ builds can be treated in this manner as is
described in the following link:
http://sourceware.org/automake/automake.html#Dependency-Tracking-Evolution
Use the IManagedDependencyCommands interface defined in this file
for this mode.
Two sub-scenarios of this mode are to:
Create dependency files in the same invocation of the tool that
creates the tool's build artifact - by adding additional options
to the tool invocation command line.
Create dependency files in a separate invocation of the tool, or
by the invocation of another tool.
MBS can also help in the generation of the dependency files. Prior to
CDT 3.1, MBS and gcc cooperated in generating dependency files using the
following steps:
1. Gcc is invoked to perform the compilation that generates the object
file.
2. An "echo" command creates the .d file, adding the name of the .d
file to the beginning of the newly created .d file. Note that this
causes problems with some implementations of "echo" that don't
work exactly the way that we want (e.g., it doesn't support the -n
switch).
3. Gcc is invoked again with the appropriate additional command line
options to append its dependency file information to the .d file
that was created by "echo".
4. Steps 1 - 3 are invoked in the make file. Step 4 occurs after the
make invocation has finished. In step 4, MBS code post-processes
the .d files to add a dummy dependency for each header file, for
the reason explained in the link above.
This mode is no longer used by the default gcc implementation, but can
still be used by selecting the DefaultGCCDependencyCalculator.
Note for GNU make: these separate dependency files are "include"d by
a main makefile. Therefore, if the dependency files are required to
be up to date before the main build begins, they must be updated by
a separate invocation of make. Also, the configuration "clean" step
must be invoked by a separate invocation of make. This is so that
we can exclude the dependency files for a "make clean" invocation
using syntax like:
ifneq ($(MAKECMDGOALS), clean)
-include $(DEPS)
endif
Otherwise, because GNU make attempts to re-make make files, we
can end up with out of date or missing dependency files being
re-generated and then immediately "clean"ed.
Method Summary |
boolean |
areCommandsGeneric()
Returns true if the command lines and/or options returned by this interface
are not specific to the particular source file, but are only specific to,
at most, the configuration and tool. |
java.lang.String[] |
getDependencyCommandOptions()
Returns the command line options to be used to calculate dependencies. |
org.eclipse.core.runtime.IPath[] |
getDependencyFiles()
Returns the list of generated dependency files. |
java.lang.String[] |
getPostToolDependencyCommands()
Returns the command lines to be invoked after the normal tool invocation
to calculate dependencies. |
java.lang.String[] |
getPreToolDependencyCommands()
Returns the command lines to be invoked before the normal tool invocation
to calculate dependencies. |
getDependencyFiles
org.eclipse.core.runtime.IPath[] getDependencyFiles()
- Returns the list of generated dependency files.
The paths can be either relative to the top build directory, or absolute
in the file system.
- Returns:
- IPath[]
getPreToolDependencyCommands
java.lang.String[] getPreToolDependencyCommands()
- Returns the command lines to be invoked before the normal tool invocation
to calculate dependencies.
- Returns:
- String[] This can be null or an empty array if no dependency
generation command needs to be invoked before the normal
tool invocation.
getDependencyCommandOptions
java.lang.String[] getDependencyCommandOptions()
- Returns the command line options to be used to calculate dependencies.
The options are added to the normal tool invocation.
- Returns:
- String[] This can be null or an empty array if no additional
arguments need to be added to the tool invocation.
SHOULD THIS RETURN AN IOption[]?
getPostToolDependencyCommands
java.lang.String[] getPostToolDependencyCommands()
- Returns the command lines to be invoked after the normal tool invocation
to calculate dependencies.
- Returns:
- String[] This can be null or an empty array if no dependency
generation commands needs to be invoked after the normal
tool invocation
areCommandsGeneric
boolean areCommandsGeneric()
- Returns true if the command lines and/or options returned by this interface
are not specific to the particular source file, but are only specific to,
at most, the configuration and tool. If the build context is a resource
configuration, this method should return false if any of the command lines
and/or options are different than if the build context were the parent
configuration. This can be used by the build file generator in helping
to determine if a "pattern" (generic) rule can be used.
- Returns:
- boolean