Much of the text in this document is taken from the managed build system (MBS) +design documents that are contained in the Eclipse Bugzilla data base. The +authors of these documents include Mikhail Sennikovsky, Bob Monteleone, Sunil +Davasam, Chris Recoskie, Lars Kurth, and Bala Torati. These design +documents are a source of additional information regarding particular MBS +functionality. Note that these documents are not necessarily kept up to +date after the initial design, where-as this document attempts to be up to date. +Here is a list of some of the documents:
+1.1 Who Needs This Information
The information in this document describes the design of the managed
-build system (MBS) and discusses how to add new tool-chain definitions to it
+build system and discusses how to add new tool-chain definitions to it
through the buildDefinitions extension point. It is
intended for someone
who wants to understand how the managed build system works, or is
@@ -209,7 +227,7 @@ collection (GCC). If you have
access to GCC tools on your platform and find the predefined project-types
sufficient for your
needs, then you do not need to modify anything. Please
-feel free to skip sections 3, 6, and 7 as they are primarily concerned
+feel free to skip sections 3, 6, 7 and 8, as they are primarily concerned
with adding new tool integrations to the build model.
If you are working with tools other than GCC, or you wish to create
project-types that CDT does not support out of the box, then you have to
@@ -278,13 +296,12 @@ defined by the user, but others will be built into the tools themselves
so the user will be unaware of them. The CDT parser
described in the previous section needs
to know about the entire set to properly parse source files. It is the
-responsibility of the MBS to answer both the user-supplied and built-in
-paths and symbols to the parser. Of the two, the user-supplied include
-paths and defines are trivial as they are entered by the user through
-the UI. The built-in compiler settings on the other hand, are quite a
-bit harder to decipher and the solution will vary from tool to
-tool. A discussion of the possible solutions is provided in §
-6.9.3.
+responsibility of the MBS to answer both the user-supplied and built-in paths
+and symbols to the parser. Of the two, the user-supplied include paths and
+defines are trivial as they are entered by the user through the UI. The built-in
+compiler settings on the other hand, are quite a bit harder to decipher and the
+solution will vary from tool to tool. A discussion of the possible solutions is
+provided in § 6.12.
1.2.4 Tool Definitions and Settings Storage
A key feature of the managed build system is that it is extensible. Tool integrators @@ -351,7 +368,7 @@ contains the following primary objects:An ordered set of tools used to transform the project resources into the final output (build - artifact) of the project. A tool integrator can provide a family + artifacts) of the project. A tool integrator can provide a family of tool-chains that support different host/target platform combinations, and different versions of the tool-chain.
Many of the MBS elements require the specification of the id attribute. The attribute value typically takes a form similar to Eclipse @@ -845,7 +862,12 @@ UI.
style="border-style: none solid solid none; border-width: medium 1pt 1pt medium; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" valign="top" height="49"> The name of a class that implements the IConfigurationNameProvider - interface in order to provide a default name for a configuration. + interface in order to provide a default name for a configuration. + The configuration names in a user's project must be unique. A + projectType can contain configuration children with the same name. + In this case, a configurationNameProvider must be specified to make the + names unique before they are displayed to the user in the New Project + and New Configuration dialog boxes.The prebuildStep, +preannounceBuildStep, postbuildStep and postannouncebuildStep +attributes define a custom build step to be run before and/or after the the +build steps defined by the tool-chain. These attributes are not typically +defined in the manifest file, but are instead added by a user from the +configuration properties user interface.
Additional configuration attributes are described in the schema table below.
3.4.1 Schema
| @@ -1145,7 +1174,7 @@ track of this specific configuration. |
The toolChain element represents -the tool chain in the user model. It is a tool-integrator-defined, ordered set +the tool chain in the user model. It is a tool-integrator-defined set of tools that transform the project’s input into the project’s outputs. A tool-chain can be defined as part of a configuration, or as an independent specification that is referenced in a separate configuration via the toolChain @@ -1160,20 +1189,19 @@ of type builder. This defines the “build” or “make” drive the transformation of the inputs into outputs.
Typically a tool-chain is hosted only on a limited subset of operating system/architecture combinations. For -example, it does not make much sense to allow a user to try to build a Solaris shared -library project if they are running Eclipse and the CDT on Windows. You can +example, it does not make much sense to allow a user to try to build a Solaris +shared library project if they are running Eclipse and CDT on Windows. You can specify the operating systems and architectures that the tool-chain is supported on as a comma-separated list in the osList and archList attributes.
-A tool-chain may be associated -with a scanner configuration profile that defines how to discover built-in compiler defines and -includes search paths.
A tool-chain should specify the targetTool attribute to identify the tool that runs to generate the primary -build output. If this is not specified, then MBS uses the file extension +build output. If this is not specified, MBS uses the file extension of the build artifact name supplied by the user. This will work when the user uses one of the extensions expected by the tool, but will not work if they do not.
+MBS supports multiple versions of +a tool-chain???
A tool-chain may define a
configuration level environment variable provider in the configurationEnvironmentSupplier attribute. See §
7.6 for additional information.
@@ -1183,6 +1211,9 @@ configuration
level macro provider in the configurationMacroSupplier attribute. See §
7.8 for additional information.
A tool-chain may be associated +with a scanner configuration profile that defines how to discover built-in compiler defines and +includes search paths.
Additional tool-chain attributes are described in the schema table below.
3.5.1 Schema
@@ -1259,7 +1290,7 @@ the schema table below.The name of a class that implements the + + IManagedIsToolChainSupported interface. This provides a + method to be called to determine if support for the tool-chain is + currently installed on the system. MBS uses this information in + order to filter the choices presented to the CDT user and to inform the + user when support needed by their project is not installed. If the + isToolChainSupported callback is not provided by the tool-chain + definition, the tool-chain is treated as supported. If all + configurations defined for the given project type are not supported the + project type is treated as unsupported.
+
6.1 Setting up your Environment
Tool integrations are specified by extending the buildDefinitions
@@ -4430,7 +4471,7 @@ Feature Details and check that "Eclipse C/C++ Development Tools
If they do not, simply install the SDK from the same update site you
used to install the CDT.
+
6.2 Creating your Plug-in Project
@@ -4464,7 +4505,7 @@ button. style="font-weight: bold;">Plug-in Development perspective, answer Yes. -+
You have installed the CDT source and
@@ -4505,7 +4546,7 @@ as the ID for the
extension, and Example Tool Chain
for the Name.
-
+
Now we will add a new projectType, configuration, toolChain, builder,
targetPlatform and an example tool to
@@ -4529,7 +4570,7 @@ Executable for our projectType.
to false.
-
+
We have now added a basic project-type definition. We now want to define a
@@ -4560,7 +4601,8 @@ following list org.eclipse.cdt.core.MakeErrorParser;org.eclipse.cdt.core.G
org.eclipse.cdt.core.GASErrorParser;org.eclipse.cdt.core.VCErrorParser
Each configuration requires a toolChain child that defines the set of tools used by the configuration.
@@ -4587,7 +4629,8 @@ you are running on a version of Solaris, orother if none
of the above apply.
-6.7 Adding a Builder
+ +6.7 Adding a BuilderEach toolChain can have a builder child that describes the build utility used by the tool-chain to create the build artifacts of the configuration.
@@ -4607,7 +4650,7 @@ example.toolchain.builder. style="font-weight: bold;">Command property, click on it to edit the value, and entermake.
-+
Each toolChain can have a targetPlatform child that describes the target
@@ -4636,7 +4679,8 @@ are running this tutorial on Linux or Solaris, enter the value org.eclipse
If you are running the tutorial on Windows, enter the value org.eclipse.cdt.core.PE.
+
+6.9 Adding a Tool
Each toolChain describes the set of tools used by the build utility to create the build artifacts of the configuration.
@@ -4673,7 +4717,7 @@ real tool, so just enterccc as the value for the command
property.
-+
We have now defined enough information to create a project for our @@ -4735,7 +4779,7 @@ not have any way to edit the settings for the tool other than the tool command. That is because we have not defined any options yet. It is time to edit the tool definition again.
-+
Users expect to be able to change the settings for their build tools through the property page for a project. What they see is controlled by the way options @@ -4810,14 +4854,14 @@ debugging your run-time workbench. You should see something like this.
title="" alt="Tutorial project property page">+
The purpose of the tutorial you just followed was to become familiar with the steps involved in creating a simple tool-chain and to get a feeling for how the choices you make in the specification of options affect the UI. In this section, we will discuss some additional points that you need to consider before specifying your own tool integration.
-6.12.1 Adding More +
6.12.1 Adding More Tools
Unless you just happen to have a compiler on your system that is invoked with ‘ccc’, the example tool we created is not going to build @@ -4829,7 +4873,7 @@ compiler and “something else” is usually sufficient, but you may hav to define additional tools if your tool-chain requires intermediate build steps to function properly.
-6.12.2 Defined +
6.12.2 Defined Symbols and Header File Search Paths
There are elements of the CDT core that require build information @@ -4847,7 +4891,7 @@ specification has options of type “includePaths” and “definedS The build model will pay special attention to these options and answer them to the appropriate clients in the CDT core without any further intervention on your part.
-6.12.3 Built-in +
6.12.3 Built-in Symbols and Search Paths
We have automated the discovery of paths and symbols for standard GCC compilers that are building targets for the platform they are @@ -4870,7 +4914,7 @@ for the user to edit these values if something changes is to directly edit the plug-in manifest where the extension is specified. Please refer to § 3.11 for more details on specifying list option values. -
6.12.4 User-Specified +
6.12.4 User-Specified Libraries and Object Modules
Similarly, a user may want to specify external libraries to link @@ -4880,7 +4924,7 @@ special attention to an option containing libraries so that when the build file generator requests them, it can answer a valid list. Flag the option value type as “libs” for external libraries or “userObjs” for object modules.
-6.12.5 ProjectType and Other +
6.12.5 ProjectType and Other Element Hierarchies
One area of the build model that the tutorial does not touch on
@@ -4905,7 +4949,7 @@ it is now possible to declare a configuration, tool-chain, tool, builder and tar
is possible to declare a complete set of elements once, and use superClass references to those
elements inside many projectTypes.
6.12.6 Publishing +
6.12.6 Publishing your Plug-in
The subject of packaging Eclipse plug-ins is well covered in the Platform Plug-in Developer Guide. @@ -5126,7 +5170,30 @@ default MBS implementation does not modify any of the command line parts. uses the parts and the pattern to generate the complete command line that can be retrieved using IManagedCommandLineInfo.getCommandLine.
-7.5 Determining if a Tool Chain is Installed
+7.5 Determining if a Tool Chain is Installed
+A tool-chain definition can provide a method to be called +to determine if support for the tool-chain is currently installed on the +system. MBS uses this information in order to filter the choices presented to +the CDT user and to inform the user when support needed by their project is not +installed. If the method is not provided by the tool-chain definition, the +tool-chain is treated as supported. If all configurations defined for the +given project type are not supported the project type is treated as unsupported.
+In order to provide this functionality, the “isToolChainSupported” +attribute in the toolChain +definition must be specified. The value of this attribute should be set to the +name of the class which implements the IManagedIsToolChainSupported +interface.
+public interface +IManagedIsToolChainSupported{
+boolean +isSupported(IToolChain toolChain, PluginVersionIdentifier version, String +instance);
+}
++
The version +argument specifies the version of the ToolChain, or null if the ToolChain does +not have a version number. The instance argument is currently null. It will be +used when “Multi-Instance” support is implemented.
7.6 Defining Environment Variables
A tool-integrator can provide a method to be called that identifies the default environment variables for the tool-chain. These would typically include the @@ -5929,5 +5996,6 @@ Elements
This element is supported in the same manner as in CDT 2.0, with the exception that the dynamic elements returned by the provider must use the new object model.
+