-
-
- Custom Build Steps (#???) -
- Tool-chain Installation Support (#???) -
- Tool-chain Multi-version Support (#???) -
- Build Environment Varaibles (#???) -
- Build Macros (#???) -
- Custom Project Wizard Pages (#???) -
- Shared Tool Options (#???) +
- Custom Build Steps (#88922) +
- Tool-chain Installation Support (#87478) +
- Tool-chain Multi-version Support (#89872) +
- Build Environment Variables (#88497) +
- Build Macros (#89210) +
- Custom Project Wizard Pages (#90334) +
- Shared Tool Options (#90481)
1.1 Who Needs This Information
@@ -1201,7 +1202,17 @@ 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. The versionsSupported attribute contains a +list of supported versions of a particular tool chain. This indicates that there +is no need to perform a conversion when user imports/loads a project with one of +the supported tool chain versions. When a tool integrator decides to no longer +support a version of a tool chain, they continue to ship the old tool chain +definition and specify the id with version number of the tool chain definition +to convert to in the convertToId attribute. If changes to the project +information need to be performed by the conversion, the tool chain must provide +a converter extension to perform the conversion. If no converter extension is +provided, then there won’t be any conversion. See § 8.2 for additional +information.A tool-chain may define a
configuration level environment variable provider in the configurationEnvironmentSupplier attribute. See §
7.6 for additional information.
@@ -1438,7 +1449,9 @@ the schema table below.
MBS supports multiple versions of +a builder. The versionsSupported attribute contains a list +of supported versions of a particular builder. This indicates that there is no +need to perform a conversion when user imports/loads a project with one of the +supported builder versions. When a tool integrator decides to no longer support +a version of a builder, they continue to ship the old builder definition and +specify the id with version number of the new builder to convert to in the +convertToId attribute. If changes to the project information need to be +performed by the conversion, the tool chain definition must provide a converter +extension to perform the conversion. If no converter extension is provided, +then there won’t be any conversion. See § 8.2 for additional information.
Additional builder attributes are described in the schema table below.
3.6.1 Schema
@@ -1942,7 +1968,9 @@ track of this specific builder.A tool contains one or more +
A tool may contain one or more children of type option which define the tool command line settings that can be changed by the user.
-A tool contains one or more +
A tool may contain one or more children of type optionCategory. These are used to simplify the user’s managements of the tool‘s settings by dividing the options into a hierarchy of categories.
-A tool contains one or more +
A tool may contain one or more children of type inputType and outputType. These define the inputs and outputs of the tool in the detail necessary for build file generation.
-A tool contains one or more +
A tool may contain one or more children of type envVarBuildPath. These specify the names of the environment variables used by the tool for specifying the include and the library paths.
@@ -2126,6 +2156,17 @@ implementer must specify that in the outputFlag attribute. attribute allows the implementer to specify a class that implements theIManagedCommandLineGenerator
interface. An explanation of how to replace the default command line
generator can be found in § 7.4.
+MBS supports multiple versions of +a tool. The versionsSupported attribute contains a list of +supported versions of a particular tool. This indicates that there is no need to +perform a conversion when user imports/loads a project with one of the supported +tool versions. When a tool integrator decides to no longer support a version of +a tool, they continue to ship the old tool definition and specify the id with +version number of the tool to convert to in the convertToId attribute. +If changes to the project information need to be performed by the conversion, +the tool chain must provide a converter extension to perform the conversion. If +no converter extension is provided, then there won’t be any conversion. +See § 8.2 for additional information.
Additional tool attributes are described in the schema table below.
3.8.1 Schema
@@ -2392,7 +2433,9 @@ Gnu C compiler, or g++ for the Gnu C++ compiler.cSource .c
cHeader .h
cHeader .h
cxxSource .cpp,.cxx,.cc
cxxSource + .C,.cpp,.cxx,.cc
cxxHeader .hpp,.hh
cxxHeader .hpp,.hh,.hxx
asmSource .asm,.s
staticLibrary .lib,.a
sharedLibrary .dll,.so
sharedLibrary .dll,.so,.dylib
Calculated dependencies of an input type are not described by a separate input type, but are instead @@ -3184,7 +3234,9 @@ categories. This is the ID of the owner of the category.
The resourceConfiguration attributes are specified in the schema table below.
3.16.1 Schema
@@ -4068,9 +4120,8 @@ string containing the three version tokens -Tool integrators may supply this element to dynamically provided the -defintions that are otherwise specified in the buildDefinitions extension point. -Each configuration element returned from this IMangedConfigElementProvider +
Tool integrators may supply this element to dynamically provide the definitions that are otherwise specified in the buildDefinitions extension point. +Each configuration element returned from this IManagedConfigElementProvider interface is treated as if it were a direct sub-child of a buildDefinitions extension. As such it should conform to buildDefinitions.exsd. The only exception is it should not contain nested dynamicElementProvider elements.
@@ -4133,7 +4184,8 @@ presents to the user. The figure below shows how the list of project types is populated with any projectType whose isTest and isAbstract attribute are set tofalse. The value of the projectType's name
attribute is
-used to populate the drop-down list-box selection widget. Similarly,
+used to populate the drop-down list-box selection widget. See § 2.1.1 for a
+description of creating a new project. Similarly,
the configuration
check list is populated with all the defined configurations associated
with the selected projectType. @@ -4146,7 +4198,7 @@ with the selected projectType.
Figure 3 New project wizard
The contents of the build property page for a project are created by -examining the tools, option categories, and options defined for the +examining the tool-chains, tools, option categories, and options defined for the current configuration. In this section we will look at how the user interface interprets the information in the build model to display options to the user.
@@ -4165,12 +4217,12 @@ library built with GCC that has two configurations; ‘Release’ (not s alt="Project property page configuration selection/edit area">Figure 4 Configuration selection
Users change the build settings for options associated with -categories and tools. The UI relies on the information in the build +tool-chains and tools. The UI relies on the information in the build settings model for that information. The figure below shows how the tool -list, displayed in a tree view, is populated. Tools are the root +list, displayed in a tree view, is populated. Tools and tool-chain categories are the root elements of the tree. Categories are displayed as leaves of the tool -they belong to. In both cases, the name defined in the plug-in manifest +they belong to, or as root elements when they belong to a tool-chain. In all cases, the name defined in the plug-in manifest is used as the text of the tree elements. Note that the tool uses an externalized string to identify its name to help internationalize a tool @@ -4233,9 +4285,9 @@ take effect in the UI.
generator. The build file generator is one of the clients of the information stored in the build settings model. You can use the default build file generator that is supplied with the CDT (for Gnu makefiles), or -replace it with a customized generator depending on the variant of build utility that you wish to -use. The relationship between the builder, the build file generator, and -the dependency calculator are shown in the model below. +replace it with a customized generator depending on the variant of build utility +that you wish to use. The relationship between the builder, the build file +generator, and a compiler dependency calculator are shown in the model below.
@@ -4465,7 +4515,7 @@ extension point defined in the org.eclipse.cdt.managedbuilder.core
plug-in. This requires that you have access to the extension point and the
schema that describes it, which are available only from the SDK
version of CDT. To confirm that the SDK is installed, select Help > About Eclipse Platform >
+ style="font-weight: bold;">Help > About Eclipse SDK >
Feature Details and check that "Eclipse C/C++ Development Tools
(Source)" and "Eclipse C/C++ Development Tools SDK" appear in the list.
If they do not, simply install the SDK from the same update site you
@@ -4513,12 +4563,12 @@ you have a brand new project with an empty manifest file. You are now
ready to add tool definitions to the managed build system by
extending the buildDefinitions extension point.
-
-
- If the xml file for the plugin was not opened by default when you +
- If the MANIFEST.MF file for the plugin was not opened by default when you
switched to the Plug-in Development
perspective, double click on the
org.eclipse.cdt.example.toolchainproject in the Package Explorer -to expand it. Double click on -the plugin.xml file to edit +to expand it. Click on the expansion icon beside META-INF, and then double click on +the MANIFEST.MF file to edit its contents. - We have to add a dependency between our project and the
org.eclipse.cdt.managedbuilder.coreplug-in where the extension point is defined. Click on the Dependencies @@ -4591,14 +4641,15 @@ example.toolchain.configuration.release. - Now set the clean command for the configuration. For the purposes of
this example, click on the cleanCommand
property to edit it and
-enter
rm –f.
+enter - Finally, we should supply a default set of error parsers that
apply to the configuration. Error parsers are used by the CDT to map input
from the shell back to source code elements. For simplicity, assume
that all of the default error parsers could be used to understand error
messages for our new target. In the errorParsers property, add the
-following list
org.eclipse.cdt.core.MakeErrorParser;org.eclipse.cdt.core.GCCErrorParser;org.eclipse.cdt.core.GLDErrorParser;
-org.eclipse.cdt.core.GASErrorParser;org.eclipse.cdt.core.VCErrorParser
+following list
rm –f.
org.eclipse.cdt.core.MakeErrorParser;org.eclipse.cdt.core.GCCErrorParser;
+ org.eclipse.cdt.core.GLDErrorParser;org.eclipse.cdt.core.GASErrorParser;
+ org.eclipse.cdt.core.VCErrorParser
@@ -4694,21 +4745,7 @@ the tool
+
+6.10 Adding Input and Output Types
+Each tool describes its inputs and outputs in InputType and OutputType elements. Right click on Compiler to get the
+ context menu and select New > inputType. Name the inputType
+ Compiler Input and make
+ its id
+ example.toolchain.compiler.input. Our imaginary compiler only works on c
+ source files. Locate the sourceContentType property and set it to
+ org.eclipse.cdt.core.cSource. The build model needs to know if there are any special file
+extensions that indicate a file is a ‘header’ file. Set the
+ dependencyContentType
+property to be Set the primaryInput property to
+ true. Right click on Compiler to get the
+ context menu and select New > outputType. Name the outputType
+ Compiler Output and make
+ its id
+ example.toolchain.compiler.output. Let us
+assume that the output of the compiler is an object module that has the
+extension ‘o’. Set the value of the outputs
+property of the
+tool to The object modules created by your compiler
+ are typically used as a group by another tool, for example a linker or
+ archiver. Set the buildVariable property to be
+ OBJS. You would use the
+ same name as the buildVariable with
+ the inputType of this other tool. Set the primaryOutput property to
+ true.Compiler and make its natureFilter
property and select both from the list of choices.
- c,C.
-Note that there should not be any spaces between the values. Let us
-assume that the output of the compiler is an object module that has the
-extension ‘o’. Set the value of the outputs
-property of the
-tool to o.h,H.-o.ccc as the value for the command
property.
+
+6.11 Testing the ProjectTypeorg.eclipse.cdt.core.cHeader
+ and the
+ dependencyCalculator property to be
+
+ org.eclipse.cdt.managedbuilder.makegen.internal.DefaultIndexerDependencyCalculator.
+ o.
We have now defined enough information to create a project for our new example project-type, so let’s go test it out.
@@ -4726,7 +4818,7 @@ new example project-type, so let’s go test it out.@@ -4780,7 +4872,7 @@ command. That is because we have not defined any options yet. It is time to edit the tool definition again. +6.12 Adding Tool Options
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
are defined in the tool integration. We will create an option category, and then
@@ -4812,7 +4904,7 @@ option. Name the option Include paths and set the
includePath from the list of choices. Please
-refer to § 3.10 for a description of option value types and what
+refer to § 3.13 for a description of option value types and what
this decision implies.
Figure 9 MBS property page with tool, category, and options
+6.13 Taking the Next Step
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.13.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 @@ -4873,7 +4965,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.13.2 Defined Symbols and Header File Search Paths
There are elements of the CDT core that require build information @@ -4887,11 +4979,11 @@ promises to store the type and value of an option, it does not know anything about the contents. However, you can flag certain options as special so the build model will know to pay special attention to them. As the implementer of the tool integration, you should make sure your -specification has options of type “includePaths” and “definedSymbols”. -The build model will pay special attention to these options and answer +specification has options of type “includePaths” and “definedSymbols”. +The build model will pay special attention to these options and provide them to the appropriate clients in the CDT core without any further intervention on your part.
-6.12.3 Built-in +
6.13.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 @@ -4914,17 +5006,16 @@ 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.13.4 User-Specified Libraries and Object Modules
-Similarly, a user may want to specify external libraries to link -against in the final build step. The build model needs to be told to -pay -special attention to an option containing libraries so that when the -build file generator requests them, it can answer a valid list. Flag the +
Similarly, a user may want to specify external libraries to link against in +the final build step. The build model needs to be told to pay special attention +to an option containing libraries so that when the build file generator requests +them, it can provide 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.13.5 ProjectType and Other Element Hierarchies
One area of the build model that the tutorial does not touch on @@ -4945,11 +5036,11 @@ decision; you can declare a non-abstract element as the super-class of another element.
Since 2.1
-it is now possible to declare a configuration, tool-chain, tool, builder and targetPlatform independently of a project-type. So it
+it is possible to declare a configuration, tool-chain, tool, builder and targetPlatform independently of a project-type. So it
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.13.6 Publishing your Plug-in
The subject of packaging Eclipse plug-ins is well covered in the Platform Plug-in Developer Guide. @@ -4970,17 +5061,14 @@ Perspective, select the plugin.xml file for your plug-in in the package explorer. Open the File > Export... wizard. On the Select -page, chose File system from +page, chose Deployable Plugins and Fragments from the export destination list. Click the Next > button.
org.eclipse.cdt.example.toolchain
-is
-selected in the left-hand list and that only plugin.xml is selected in the
- right. To select an export destination, click the Browse... button beside
- the text box labeled To directory.
-Browse to the plugins
-subdirectory of your Eclipse installation. Click the Finish
+
+ Destination section, select Directory and click the Browse... button.
+Browse to your Eclipse installation. Deselect all Export Options. Click the Finish
button.IManagedDependencyGenerator
-shown in the figure below and specify that class in an inputType element,
+shown in the figure below and specify that class in the inputType element,
dependencyCalculator attribute.
-
In order to provide this functionality, the “isToolChainSupported” +
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 @@ -5524,7 +5612,7 @@ the buildPathResolver attribute in the envVarBuildPath definition must be specified. The value of this attribute should be set to the name of the class which implements the IBuildPathResolver interface. This allows the tool-integrator to provide his/her own - logic of resolving the environment variable values to build paths.
+ logic for resolving the environment variable values to build paths.public interface IBuildPathResolver {
diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif index 443cd8b87da..a67ec14d1f0 100644 Binary files a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif and b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif differ diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif index d1a9035bc43..faa1d2b6a30 100644 Binary files a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif and b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif differ diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif index d4bc0a0c049..d5eb4289289 100644 Binary files a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif and b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif differ