Managed Build System Extensibility Document This document describes the design of the managed build system and how to extend it.

1 Introduction

NOTE: the document describes the CDT Managed Build System (MBS) 3.x functionality. Although there have been lots of significant changes made to the Build System in the 4.0, the document still remains valid since all the 4.0 build system changes were made by extending the MBS functionality described in this document. As of CDT 8.0, MBS 4.0 is still used although with a number of improvements not necessarily reflected in this document.

Please refer to the "What's new in the CDT Build System 4.0" document for the list and description of additional new functionality presented in CDT 4.0

C and C++ developers are a diverse group. The tools they use, the processes they follow, and the level of support they expect from their development environments vary widely. The CDT provides a framework for integrating those tools into Eclipse and the managed build system is part of that framework. Understanding how the managed build system works, and what steps are required to extend it is the focus of this document.

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:

• 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

The information in this document describes the design of the managed 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 interested in adding their own tool-chain specification to it.

The CDT managed build system comes configured to generate Gnu makefiles to build executables, static libraries, and shared libraries using the Gnu compiler 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, 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, you can add a description of your project-type/toolchain and make the CDT pick up the information you provide with your definitions. With the CDT 4.0 you can do this for both cases whether you are willing the CDT to automatically generate makefiles for your project or not.

If you choose to add your own tools to the managed build system, it is assumed that you are familiar with XML and the Eclipse extension point mechanism. Having made the standard disclaimer, it should be said that the tutorial in § 6 presents a cookbook approach to adding a new tool specification, so you can always jump right in and refer to the online help in the Platform Plug-in Developer Guide if you get stuck.

1.2 Managed Build System Overview

The managed build system consists of several components that interact to build a project. At the core of the managed build system is the build model. It is the central clearing house for all the build-related information that internal and external clients require. There are three internal clients; the user interface components, a build file generator that is responsible for generating correct build files for a project when it is built, and the built-in parser supplied with the CDT. The external clients are the end-user, who interacts with the build model through the user interface, and tool integrators who supply tool definitions to the build model. The diagram below shows the basic set of relationships between these components.

Figure 1 Managed build system overview

1.2.1 External Users

From the perspective of the build system, there are two external users. The first is the end-user who interacts with it through the UI elements described in § 5. The UI includes a new project wizard that relies on the build system to tell it what kinds of new projects can be created. When the project has been created, the project property page uses the information in the build system to populate its display. The user can change the information associated with the tools for a project through the property page and the build system is responsible for saving those changes between sessions. The second external user is the tool integrator who adds information about their tool-chain to a plug-in manifest as described in the tutorial in § 6. The tool integrator is the primary audience for this document.

1.2.2 Internal Users

There are three internal clients of the information in the managed build system. The first is the build file generator that creates correct build files for a project based on the tools and settings defined for the project in the build system. The second is the built-in CDT parser that relies on the build system to tell it about the include paths and defined preprocessor symbols for a given project so that it can properly construct an internal representation of the compilation unit the file belongs to. The third client is the UI component of the build system that queries the build model for the tools and options defined for a project to build its display and store the user settings.

1.2.3 Built-in Compiler Settings

1.2.4 Tool Definitions and Settings Storage

1.3 The Standard Build System

There is also a standard build system supplied as part of the CDT framework that is unrelated to the managed build system. The standard system provides a small set of tools to build a user’s projects. The user is expected to supply a makefile which includes enough information to build their project. The UI allows the user to switch between targets defined in the makefile, and can dynamically discover build settings at run-time to allow the parser to function correctly.

The decision to use the standard or managed build system is a trade-off. For users with an existing project that already has a set of working makefiles, or for users that prefer (or need) to write their own makefiles, the standard system may be perfect. However, many users find writing and maintaining makefiles for projects to be a chore. For these users, the trade-off for the convenience of not having to maintain them is the flexibility of being in control of the makefiles.

2 User Model

The CDT user’s model of the MBS contains the following primary objects: 

2.1 User Scenarios

The following sections describe how the user interacts with MBS.  Text in red indicates MBS functionality that is not yet implemented, but is intended to be implemented in future releases of MBS.

2.1.1 Creating a New Project

The CDT user’s experience with the MBS begins when she creates a new Managed Make project.  The user picks the type of project to create from the list of project types defined in the installed manifest files.  The list of project types is, by default, filtered by:

·        The project type must contain at least one default configuration that uses a tool-chain that supports the host operating system and architecture.

·        If the project type implements the method of verifying that its support has been installed, the method must return TRUE.

·        The user may remove installed and possibly-installed (i.e. the project type does NOT implement the method of verifying that its support has been installed) project types from future consideration by turning them off in the MBS Preferences page.

The user may turn off project type filtering, however configurations that use tool-chains that are not installed will not be able to be built on the host system.

After selecting the project type, the user selects 1 … n configurations for her new project from the list of configurations defined in the project type.  Different configurations can use different tool-chains. The list of configurations is, by default, filtered by:

·        The tool-chain used by the configuration must support the host operating system and architecture.

·        If the tool-chain implements the method of verifying that its support has been installed, the method must return TRUE.

The user may turn off configuration filtering, however configurations that use tool-chains that are not installed will not be able to be built on the host system.

After selecting the initial set of configurations for the project, the user can select any of the standard tabs in the “Additional Project Settings” page in order to customize additional options that are common to all Managed Build system projects (e.g., the projects that the new project depends upon, etc.).

The user can proceed to any additional pages provided by the project type in order to customize project type specific options.  For example, these additional options can result in generating initial code for the project and/or setting tool options that are different from the project type defaults.

After creating the new project, the user can use any of the Eclipse methods of adding files to the project.

2.1.2 Adding a New Configuration

The user can create a new configuration based upon the settings used by one of the existing configurations.  The user can select a different tool-chain from the project type if desired.  This allows a project type to be defined (e.g., “Gnu Executable”) that contains tool-chains for multiple combinations of host and target platforms, and/or for multiple versions of a tool-chain.  It should be easy for a user to take an existing CDT project to a different host system and quickly create a configuration that builds on that host system using a version of the tool-chain that supports the new host.

The user can also pick 1 … n configurations from the list of default configurations defined in the project type.  The list of configurations is, by default, filtered as specified above.

2.1.3 Modifying the Tool-chain of the Configuration

The user can select a configuration and modify the following attributes of the tool-chain:

1. The command used to invoke a particular tool in the tool-chain.
2. The set of error parsers to be used with the build output and the order that the error parsers will be invoked
3. The binary parser to be used with the build binary outputs.
4. The set of file extensions that are processed by a tool.
5. The addition of Custom Build steps before or after the build.  The user specifies the commands to be executed by the step.
6. The mapping of an individual resource to a Custom Build step.  The user specifies the commands to be executed by the step, the input dependencies of the step, and the output files that are created by the step.
7. The mapping of a set of file extensions to a Custom Build step.  The user specifies the commands to be executed by the step, the input dependencies of the step, and the output resources that are created by the step.
8. The tool-chain itself:  The user can change the tool-chain to be used with the configuration.  All applicable settings are automatically transferred to the new tool-chain.
9. The mapping of an individual resource to a tool:  The available tools come from the configuration’s tool-chain, from a different tool-chain or from individually defined tools.
10. The mapping of a set file extensions to a category of tools or a specific tool:  The user can modify the current assignments and add new assignments.  The available tools come from the configuration’s tool-chain, from a different tool-chain or from individually defined tools.

2.1.4 Modifying the Tool Options of the Configuration

The user can modify the options of an individual configuration, or he can make changes to a set of configurations that he has selected.  The user can select a set of configurations individually or by selecting a “category” of configurations.  The names of the categories are defined by the configuration provider – “debug” and “release” are commonly supported.  Categories which group configurations by target platform could also be useful. 

The user can modify the options of a tool used by the configuration.  A tool can verify that the new value is valid and an error message will be displayed if the value is not valid.  The current value of a build setting is bolded if the value if different from the default value for the tool.  The user can easily set the value back to the default value without knowing what the default value is.

The user can modify certain “well known” build settings for multiple selected configurations, even when the configurations do not use the same tool-chain.

The user can use Build Macros in all options that accept text.  MBS pre-defines many useful macros and allows tool integrators and the CDT user to define additional macros.  Additional macros can be defined in the MBS preferences page and for individual projects or configurations.  Build Macros are referenced in strings by enclosing them in braces, preceded by a dollar sign.

Tool integrators may define property setting “wizards” that modify sets of tool options in order to reach an overall user-desired goal.  An example would be a “Most Highly Optimized Build” wizard that set options on multiple tools.

2.1.5 Modifying the Tool Options of an Individual File

The user can specify different configuration specific build settings for individual files in the project. The current value of a build setting is bolded if the value is different from the value in the configuration.  The user can easily set the value back to the configuration value without knowing what that value is.

The user can add or remove a Custom Build step for an individual resource.  The step can execute before or after the tool assigned to the resource, or they can execute instead of the tool assigned to the resource.  The user specifies the tool command line, the input dependencies of the step, and the output resources that are created by the step.

The user can mark individual files to not be used in the building of the selected configuration(s).

2.1.6 Building a Configuration

The user can build projects from within the Eclipse/CDT user interface, or from a command line that can be placed in a batch/script file.

The user can build the currently active configuration, or select a different set of configurations to build.

The user can rebuild an individual resource separate from building the entire project.

2.1.7 Upgrading a Project to a New MBS or Tool-chain Version.

MBS defines a version number that is stored in every MBS project file (.cdtbuild).

When MBS reads a project file with an older version number:

1. MBS asks the user to confirm the conversion.
2. If the user confirms the conversion, the project file is converted and the project can no longer be loaded by previous versions of MBS.
3. If the user does not confirm the conversion, the MBS information is loaded in a read-only mode, and any changes made to the MBS information will be discarded when the project is closed.

When MBS reads a project file with a newer version number, it displays an error message, and does not load the MBS information.  None of the MBS operations are available on the project (for example, editing build properties, cleaning, building, …).

Some of the build model elements (tool-chain, tool, or builder) can also define a version number.  The version number is appended to the end of the element id, and stored by MBS with each reference to the element.  MBS attempts to resolve references in the following manner:

1. MBS looks up the id with the version specified with the reference. 
2. If not found, MBS looks up all occurrences of the id, and selects a match in the following order:
   1. the id with the closest higher version number that lists the referenced version in its versionsSupported attribute
   2. the id with no version information specified

If a match is found, there are 2 scenarios:

1. The version is still actively supported by the tool integrator, and the MBS information is loaded.
2. The version specifies that a conversion to a later version of the tool-chain/tool/builder is required.  At the discretion of the tool-chain/tool/builder, the conversion may occur automatically, or the converter may prompt the user to confirm the upgrade.  The same rules apply as above for whether or not the user confirms the conversion.

If no match is found, MBS displays an error message, and does not load the MBS information.  None of the MBS operations are available on the project (for example, editing build properties, cleaning, building, …).

3 Build Model Grammar Elements

The managed build system defines a grammar to describe tool and build information. This information is used to store invariant data, like the command line invocation for a specific compiler, for example. The build system also stores user settings between sessions, like the level of debugging information that is needed for a particular build configuration. The following section describes the format of the grammar and what the information is used for by the build model.  See the CDT 3.0 Gnu tool-chain definitions for an example of using the managed build object model.

Common Attributes

Many of the MBS elements require the specification of the id attribute.  The attribute value typically takes a form similar to Eclipse package names, e.g. "cdt.managedbuild.tool.gnu.c.linker".  Each id must be unique within MBS and among all of the loaded manifest files.  It is suggested that you include your company/organization name in the ids that you create.

Many of the MBS elements can specify the name attribute.  The attribute value is used in the MBS user interface, and may therefore change if your tool-chain supports more than one language.  You can use a plugin.properties file in order to define these strings in an external file (see the Gnu tool-chain definitions for an example).

Many of the MBS elements can specify the superClass attribute.  The attribute value is the id of an element of the same type as this element.  For most attributes, when the value of an attribute is not specified in an element, the value will default to the value defined by the first super-class ancestor that specifies a value for the attribute.

Schema Notes

• Attributes highlighted in yellow indicate functionality that is new since CDT 3.0.1.
• Attributes highlighted in aqua indicate attributes that have been deprecated.  Each of these attributes describes the new method to use to obtain equivalent functionality.
• The "Required" column can contain 3 values.  "Yes" means that the attribute is required by the schema for every instance of the element.  "No" means that the attribute is never required and an appropriate default is supplied if necessary.  "In Hierarchy" means that the attribute is not required by the schema, but MBS requires that the attribute be specified either by the element itself, or inherited from one of its ancestors (see the superClass attribute).

3.1 Model

The figure below shows a UML model of the schema elements.  It is simplified by leaving out the fact that the configuration, toolChain, tool, targetPlatform, and builder definition elements can be defined at the top level in a manifest file.

Figure 2 Managed build model elements

3.2 ProjectType

The projectType element represents the project-type in the user model.  It is a tool-integrator-defined class of project which acts as a template for the projects that a user will create.  The projectType contains one or more children of type configuration.  These are the default configurations that the user can choose from.  Note that there is no reason to define a projectType element in a .cdtbuild file.  It would never be used since projectType elements are used to populate the New Project dialog boxes.

You must provide a unique identifier for the project-type in the id attribute. The build model uses this information to distinguish between the project-type definitions it finds.  You must also provide a meaningful name that will be displayed to the user in the UI and new project wizards.

Project-types can be arranged into hierarchies to promote the efficient sharing of configurations. If you have defined a project-type that should not be selected by the user, but is a root for other project-types, it may be declared abstract by setting the isAbstract attribute to ‘true’. Abstract project-types do not appear in the UI.  Descendents of an abstract project-type will have the same configurations that the abstract project-type has. For these children to function properly, their superClass attribute must contain the unique identifier of the super-class project-type.

A concrete project type must have at least one configuration defined for it. A configuration must define (or inherit) a set of tool-chain definitions that work together to produce the build goal as an output.

A projectType may define a project level environment variable provider in the projectEnvironmentSupplier attribute.  See § 7.6 for additional information.

A projectType may define a project level macro provider in the projectMacroSupplier attribute.  See § 7.8 for additional information.

3.2.1 Schema

3.3 Managed Project

The managedProject element represents a project instance in the .cdtbuild file.  Note that there is no reason to define a project element in a manifest file – it would never be used.

The following steps occur when a CDT user creates a new Managed Build project:

1. A new managedProject element is created.  Its projectType attribute is set to the projectType that the user selected.  Its name attribute is set to the project name that the user entered.
2. When the user adds a default configuration, the selected configuration element is cloned to become a child of the managedProject element created in step 1.
3. Add a tool-chain element that specifies as its superClass the tool-chain that is the child of the selected configuration element.
4. For each tool element child of the tool-chain that is the child of the selected configuration element, create a tool element child of the cloned configuration’s tool-chain element that specifies the original tool element as its superClass.

This prepares the new project/configurations for modification by the user.

3.3.1 Schema

3.4 Configuration

The configuration element represents the configuration in the user model.  A tool-integrator defines default configurations as children of the project type.  These provide a template for the configurations added to the user’s project, which are stored in the project’s .cdtbuild file.  A projectType must have at least one default configuration defined for it, and a project must always contain at least one configuration.

The configuration contains one child of type tool-chain.  This describes how the project’s resources are transformed into the build artifact.  The configuration is responsible for maintaining the name of the final build goal. The user selects the name of the build artifact in the UI, and the configuration maintains it in the artifactName and artifactExtension attributes.  The configuration can contain one or more children of type resourceConfiguration.  These describe build settings of individual resources that are different from the configuration as a whole. 

Each configuration must have a unique identifier specified in the id attribute that will be used by the build model to manage the configuration. It must also have a name that will be displayed in the UI in the build property page and new project wizards.  The configuration contains the information needed to “clean” the build files on the host machine.  The configuration can specify the cleanCommand attribute which specifies a command that removes the build files.

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

3.5 Tool Chain

The toolChain element represents 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 superclass attribute.

The toolChain contains one or more children of type tool.  These define the tools used in the tool-chain.

The toolChain contains one child of type targetPlatform.  This defines the architecture/os combination(s) where the outputs of the project can be deployed.

The toolChain contains one child of type builder.  This defines the “build” or “make” utility that is used to drive the transformation of the inputs into outputs.

The tooChain may contain one or more children of type optionCategory and option.  These define tool-chain wide settings that are not specific to a particular tool.

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 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 should specify the targetTool attribute to identify the tool that runs to generate the primary 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.  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.

A tool-chain may define a 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

3.6 Builder

The builder element represents the utility that drives the build process (typically, but not necessarily, a variant of “make”).  It defines the command needed to invoke the build utility in the command attribute. Any special flags that need to be passed to the builder are defined in the arguments attribute.   The builder can specify the error parser(s) to be used to parse its output.  The builder also specifies a Java class that generates the build file.  MBS provides built-in gnu makefile generation.

The builder can specify a number of arguments that apply to build macros and how they interact with the build file generator. 

The builder can specify the template of how to convert a build macro that contains an environment variable into the build file environment variable format by specifying the variableFormat attribute.

The builder can specify the builder internal (reserved) macro names and the macro names reserved by a build file generator (used to store the list of objects files, input files, etc.). This information will be used by the build file generator in the case where the build environment variable macros are not to be expanded in the build file. If an environment variable build macro name conflicts with the name of some reserved macro, it always gets resolved in the build file. See the reservedMacroNames and reservedMacroNameSupplier attributes below.

The builder can provide the values for the file-context build macros.  To provide the value for the macro ${<macro_name>}, the macro<macro_name>Value attribute should be specified. The value of this attribute should be set to the value of the given macro. MBS will resolve the value of unsupported file-context macros to their actual macro value. In this case, a separate rule for each file will be generated when file-specific macros are used.  See the gnu tool-chain for an example of setting these attributes for gnu make.

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

3.7 Target Platform

The targetPlatform element represents the os/architecture combination(s) upon which the output of a tool-chain can be deployed.  The osList and archList attributes contain the Eclipse names of the operating systems and architectures described by this element. 

CDT offers a facility for parsing binary files if it knows which output format the build artifact has been produced with. The binaryParser attribute must contain the id of the appropriate parser if you want build artifacts of the tool-chain to be parsed in the workspace.

3.7.1 Schema

3.8 Tool

The tool element represents the tool in the user model.  A tool must have a unique id for the build model, and a name that is displayed to a user through the UI.  A tool can be defined as part of a tool-chain, or as an independent specification.

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 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 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 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.

Certain tools logically belong to certain kinds of projects. For example, the Gnu compiler is invoked differently for C and C++ source files. You can specify a filter for a tool based on the nature of a project using the natureFilter attribute. When a new C project is created, a “cnature” is added to it. New C++ projects have both a “cnature” and “ccnature”. The build model interprets the filter as follows. If you specify a ‘cnature’ filter, then the tool will only be displayed if the project has a “cnature” and does not have a “ccnature”. If you specify a ‘ccnature’ filter, then the tool will be displayed if the project has a “ccnature”. The default if no filter is specified is to display the tool for all projects.

Each tool specifies a command that will be placed in the build file during the build file generation stage of building.  If the tool requires a special output flag, such as ‘-o’ for a compiler or linker, the implementer must specify that in the outputFlag attribute.

The commandLineGenerator attribute allows the implementer to specify a class that implements the IManagedCommandLineGenerator 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

3.9 Input Type

This element is a child of the Tool element.  It describes one category of input to the tool.  A Tool may have multiple InputType element children.  The element may reference an Eclipse content type that corresponds to the input type.  If Eclipse/CDT has not defined an appropriate content type, then the tool integration can provide an Eclipse content type extension.  A content type describes things such as the file extensions that identify the type (see the Eclipse org.eclipse.core.runtime.contentTypes extension point.) 

CDT pre-defines the following content types:

• cSource            .c

• cHeader            .h

• cxxSource        .C,.cpp,.cxx,.cc

• cxxHeader        .hpp,.hh,.hxx

• asmSource       .asm,.s

• objectFile         .o,.obj

• executable        .exe

• staticLibrary     .lib,.a

• sharedLibrary   .dll,.so,.dylib

A tool can define more than one input type.  The primary input type is used in a different manner than any secondary input types.  For a multipleOfType == false primary input type, the tool is called for each project resource that is of the primary input type.  All files of every secondary input type are added to each invocation of the tool.  For a multipleOfType == true primary input type, the primary inputs are listed before the secondary inputs.

Calculated dependencies of an input type are not described by a separate input type, but are instead determined by a dependency calculator extension callback when necessary.  The dependencyCalculator attribute allows the implementer to specify a class that implements the IManagedDependencyGenerator2 interface. It is the responsibility of this class to answer all of the source-level dependencies for a given input. A discussion of why this is important for make-based build utilities can be found in § 5.1.3. An explanation of how to replace the default dependency calculator can be found in § 7.3.

Other attributes of the InputType element are described in the table below.

3.9.1 Schema

3.10 Additional Input

This element is a child of the InputType element.  It describes additional input of a particular input type. An InputType may have multiple AdditionalInput element children.  This element is only present if additional inputs and/or dependencies are specified by the user (or tool integrator).

3.10.1 Schema

3.11 Output Type

This element is a child of the Tool element.  It describes one category of output created by the tool.  A Tool may have multiple OutputType element children.  The element may reference an Eclipse content type that corresponds to the output type.  If Eclipse/CDT has not defined an appropriate content type, then the tool integration can provide an Eclipse content type extension.  It describes things such as the file extensions that identify the type (see the Eclipse org.eclipse.core.runtime.contentTypes extension point.)

A number of the OutputType attributes provide a mechanism for MBS to determine the name(s) of the output file(s) generated from this OutputType.  This is necessary in order for MBS to generate correct build files, and to allow for input ordering.  The precedence order for determining the output resource names is the following:

1. If this is the “target” tool in the tool-chain, and this is the primary OutputType, use the user-defined artifact name and extension.
2. If the option attribute is specified, use the value of the option.
3. If the nameProvider attribute is specified, call the nameProvider and use the returned name(s).
4. If the outputNames attribute is specified, use the value of the attribute.
5. Use the namePattern attribute value to construct the name from the input file name.

 If the output of the tool usually has a special prefix, like the prefix ‘lib’ for libraries on POSIX systems, the implementer must specify this in the outputPrefix attribute.

3.11.1 Schema

3.12 Option Category

The optionCategory element represents the option category in the user model.  A tool can have a large number of options. To help organize the user interface for these options, a hierarchical set of option categories can be defined. A unique identifier must be specified in the id attribute. This will be used by the build model to manage the category. The user will see the value assigned to the name attribute. If the category is nested inside another category, the unique identifier of the higher level category must be specified in the owner attribute, otherwise specify the identifier of the tool the category belongs to.

3.12.1 Schema

3.13 Option

The option element represents the option in the user model.  Options are used to organize and maintain the command arguments that are sent to tools during the build. Users interact with the build model through the UI to set the value of options.  Each option must have a unique id for the build model to properly manage it. A descriptive name that will appear in the UI must be specified. Options can be organized into categories to keep the UI more manageable. If an option category has been defined for the tool, and the option should be displayed as part of that category, then the unique identifier of the option category must be specified in the category attribute.

3.13.1 Option Types

Some options contain commands to turn a feature off or on, such as setting a flag to see descriptive messages from a tool. Others contain lists of values, such as a set of directories to search for files. Still others are a single selection from a pre-determined range of choices, like the level of debugging information to produce, or the type of architecture to build for. The valueType attribute is used to indicate to the build model what kind of option it is.

Specifying the type of value an option contains is an important design decision, since it controls how the build model treats the contents of the option’s attributes, and just as importantly, how the option is displayed to the user. The basic types are string, boolean, stringList, and enumerated.

There are also four specialized cases of list options, includePath, definedSymbols, libs, and userObjs to manage the list of paths to search for header files, the defined preprocessor symbols, external libraries to link against, and object module to link in respectively.

3.13.1.1 String Options

String options are used for tool commands that take a user-defined value.  The UI representation for a string option is a text box.

3.12.1.2 Boolean Options

Boolean options are used to specify an option that is either true or false. The UI representation for a boolean option is a check box. The value of the option is set true by selecting the check box, and false by deselecting it. If true, the command associated with the option will be passed to the tool when it is invoked. If false, the value associated with the commandFalse attribute will be passed.

3.13.1.3 Enumerated Options

Enumerated options are used when the tool command takes a value from a pre-determined range of choices. The UI representation for an enumerated option is a combo box.  Enumerated options may have enumeratedOptionValue children.  Note that when an enumerated option has enumeratedOptionValue children, the children define the complete set of possible option values and override the enumeratedOptionValue children of any superclass.

3.13.1.4 String List Options

String list options are used for a tool command that takes a list of user-defined values.  The UI representation for a string list option is a multi-line text box and button bar.  String list options may have listOptionValue children.

3.13.1.4.1 Special List Options

There are four special cases of string list options; includePaths specify the paths to search for header files, definedSymbols for user-defined preprocessor defines, libs for libraries that must be linked into the final build goal, and userObjs for external object files that must be linked.

While specifying these types of options as type stringList will make them appear in the UI correctly, the build model will not be able to recognize them as special in any way. Since certain functions of the CDT require this information to function correctly, it is important to flag these types of options appropriately. For example, the search and indexing function may not perform correctly if the includes paths and defined symbols are not set for a project. Similarly, the build file generator may not be able to generate dependencies correctly if it is unaware that there are libraries and external object files that participate in the final build step.

3.13.1.4.2 Browse Types

Certain types of list and string options that deal with files or directories are easier for the user to manipulate if there is a browse button supplied in the UI. This is especially true for include and library search paths, as well as library and object file lists. Because the UI needs to know what "type" of browser to display, the implementer may specify the browseType for list and string options as none (default), file, or directory. Note that the browseType attribute is only used for list and string options. It is ignored for all other option types.

3.13.2 Values and Default Values

An option can define a default value that applies to the option until a value has been specified. An option defines its default value using the defaultValue attribute.  When an option has a value that has been specifically set, the value is contained in the value attribute.  In order to determine the current value of an option, MBS performs the following steps until a value is found:

1. Examine the value attribute of the option.
2. Examine the value attribute of the option’s superClass recursively.
3. Examine the defaultValue attribute of the option.
4. Examine the defaultValue attribute of the option’s superClass recursively.
5. Use the default value for the option type.

The type of option will determine how the build model treats the value it finds associated with the attribute. Options that define simple string values will use the value as-is as described below.  For boolean options any value but the string ‘true’ will be treated as false. List options treat all the defined list option values as default, and enumerated options search through the defined enumerated values for the default.

3.13.3 Option Commands

The values stored in the options are passed to build tools with unique flags, depending on the compiler and the option. For example, an option defining the paths a linker should search for libraries might contain a large number of search paths, but each path is passed to the linker with a ‘-L’ flag. The command attribute is used to hold the actual flag to pass along with the option value.

The build model handles the value it finds associated with the command attribute differently depending on the type of value the option is managing based on the following heuristic. For string options the option value is appended to the value of the command attribute. The command attribute can be empty in order to support an area for typing in additional options.  For enumerated options, the command associated with the selected enumerated value is used, not the command defined in the option. For boolean options, the command is used if the option value is set to true, otherwise the value of the commandFalse attribute is used. For list options, the command is applied to each element of the list.

3.13.4 Option Applicability

This section will be provided in a future version of the document.

3.13.5 Schema

3.14 List Option Value

Some options are best described using a list of values. This build model element is used to define an individual element of a list option. Typically, these options are populated by the user, not by the person describing the option. However, if you define one or more values in your extension point, they will be displayed in the UI when the user edits the build settings for the project. If the user modifies those settings, the overridden values will be stored by the build model and displayed in the UI.

There is an exception to this, however. Certain core functions in the CDT rely on the built-in parser to function correctly. In order to return accurate values, the CDT parser must mimic (as closely as possible) the preprocessor that ships with the tool. Unfortunately, these tools often have a number of built-in symbols and include paths that the user is never required to set, and may be unaware even exist. In those cases, the tool integrator must set those values in the tool definition and flag them by setting the value of the builtIn attribute to true. Built in list option values are never shown to the user, and are only passed to clients of the build model that specifically request them.

3.14.1 Schema

3.15 Enumerated Option Value

Some options are best described as a single selection from a list of choices. For example, users typically select the level of optimization they want the compiler to apply when creating a build artifact. The enumerate option value is used to define the elements of the list of choices.

Each element of an enumerated option has a name that will be shown to the user in the UI. It also has a command which should correspond to the command line option that gets passed to the tool by the builder if this element is selected.

A default element can be indicated by setting the value of isDefault to ‘true’. If the user has not overridden the selection in the UI, the default element will be displayed. If no default is specified, the first element in the list is assumed to be the default and is displayed to the user.

3.15.1 Schema

3.16 Resource Configuration

The resourceConfiguration element is not visible in the user model.  It is a place to store build attributes of individual resources that are different from the configuration as a whole.  The resourceConfiguration element can have a tool child that contains the overridden attributes and options, and/or a tool child that contains a custom build step for the resource.

The resourceConfiguration attributes are specified in the schema table below.

3.16.1 Schema

3.17 Environment Variable Build Path

The tool-integrator can specify the names of the environment variables used by the tool for specifying the include and the library paths.  To specify the build paths variables (either the include path variables or library path variables) the tool-integrator must define the envVarBuildPath element as the child of the tool element.  The tool element may have several envVarBuildPath elements, each of those representing the list of environment variable names and the delimiter or the Build Path Resolver used for those variables.

The envVarBuildPath attributes are specified in the schema table below.

3.17.1 Schema

3.18 Managed Build Revision

Version identifier for the managed build extension point. It is a string representation, consisting of three (3) tokens separated by a decimal point. The 3 tokens are positive integer numbers. This is used by the build model when it loads a tool definition. The model will compare the version string in the plugin manifest with its internal version of the model grammar. If the manifest is compatible with the internal version, the MBS will do its best to load the manifest file.

3.18.1 Schema

3.19 Option/Category Enablement

Tool integrators may supply element enablement to make an element (such as option and option categories) conditionally available

3.19.1 Schema

3.20 Dynamic Element Provider

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.

3.20.1 Schema

4 UI Representation

In addition to controlling the way a project is built, the build model also defines how the user interface will appear. There are two principle ways a user interacts with the build settings model. The first is at project creation time through the New Project wizards, the second is through the build settings property page.

4.1 New Project Wizard

The new project wizard relies on the project-type and configuration definitions from all managed build system manifest files to populate the list of choices it 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 to false. The value of the projectType's name attribute is 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.

Figure 3 New project wizard

4.2 Build Property Page

The contents of the build property page for a project are created by 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.

4.2.1 Managing the Configuration

The active configuration information pane of the build property page consists of two drop-down list controls and a button. The first drop-down list is currently read-only, and displays the type of project. The second contains a list of configurations that are defined for the project. The figure below shows a project targeted solely at a Windows shared library built with GCC that has two configurations; ‘Release’ (not shown), and ‘Debug’. Note that the build settings model is queried for the project-type and configuration name information.

Figure 4 Configuration selection

Users change the build settings for options associated with 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 and tool-chain categories are the root elements of the tree. Categories are displayed as leaves of the tool 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 specification, but this is not necessary.

Figure 5 Tools and option category display

As mentioned in the discussion of the build settings model, options know what type of data they manage. Different option types require different UI widgets to properly represent that data to the user. The figure below shows what UI elements are created for each type of option.

The Compiler Flags option contains a string option. In this example, the option is intended to be the place the user enters all those extra flags that are not defined anywhere else in the property page. Options containing strings display their contents in a simple text box.

The Optimization Level option is an enumerated option. These types of options force the user to select a single value from a list of possible choices. Note that the name of the option is applied to the label in the UI, whereas the name of each individual enumeratedOptionValue element is used to populate the list.

The Include Paths option is a special case of a stringList option. The contents of this option are left undefined in this example, so the user sees an empty list. However, all list options are displayed in a list control with an associated button bar for adding, removing, and reordering list elements. Note that the optionType attribute is set to includePath. This notifies the build system that it must pay special attention to the values entered in this option. There are clients of this information in the CDT that will query the build system for this information, and this is currently the only way to flag these values as special.

Figure 6 Option display

Finally Verbose, a Boolean option, is displayed as a check-box. Since the default value for this option is defined as false, the check-box is left unselected when it is created.

Note that the UI actually builds itself on the fly based on the options descriptions in the plug-in manifest. The order of the options is the basis of the page layout. If the layout is not satisfactory, you must edit the manifest file itself. You must then restart the workspace after editing the manifest for your changes to take effect in the UI.

5 Build File Generation

The third element of the managed build system is the build file 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 a compiler dependency calculator are shown in the model below.

Note:  This figure uses the deprecated interface IManagedDependencyGenerator instead of IManagedDependencyGenerator2.  However the relationships between the parts remains the same.

Figure 6 Relationship between build file generator and dependency calculator

5.1 Default Build File Generator

The best way to understand how the build file generator works is to look at a real project. The figures below show the project that we will be using for the purposes of this discussion. The source for the project is spread over the directories source1/, source2/, and source2/source21. Header files are located in 2 locations; headers/, and source2/source21. To illustrate the problem of calculating source-level dependencies for make, Class1 is in a has-a relationship with Class2.

Figure 7 Example project source files

While simple, this example illustrates some of the problems projects using make typically face when source files are organized hierarchically. One approach to these types of problems is to generate a makefile for each subdirectory, then call make recursively, culminating in the final build step which, in theory, brings all of the build results together.

The problem with managing this type of approach lies in understanding all of the source-level dependencies and handling them properly when the makefiles are generated. In order for this to happen, all the dependencies have to be properly specified and complete. As long as there are no dependencies between resources in different subdirectories, the makefiles in a recursive approach will contain a properly partitioned set of dependencies. However, in a more realistic project organization, the fragmentary makefiles will have incomplete representations of the dependencies. In order to correct for this, we would have to do some of the work that make gives us for free.

The approach the makefile generator takes is to use a single makefile to build the entire project. To keep the makefile manageable and readable, the makefile generator creates makefile fragments for each subdirectory of the project that contributes source code and dependency fragments for each source file, and uses the include capability of make to bring them all together.

The figure below shows the makefile, makefile fragments, and dependency fragments that are generated for the project. Note that all generated files and directories are marked as derived so that a CM system will not check them in.

Figure 8 Generated makefiles

In the next sections, we will examine the makefiles that are generated by the default build file generator in more detail.

5.1.1 Main Makefile

There is one main makefile generated for each project configuration. Based on information for the configuration, the proper clean command is defined as a macro. Note that for efficiency, wherever possible the default build file generator takes advantage of Gnu make's ‘:=’ and ‘+=’ variable assignment operators so that the contents of the makefile macros are only evaluated when a value is assigned or modified, not every time they are used. The makefile includes external makefiles that have a list of build directories, object files, makefile fragments, and dependency makefiles.

This makefile is passed as an argument to make, so it contains clean and all targets.  It contains the build rules for the following types of tools defined in the tool-chain:

1. The target tool as defined by the tool-chain
2. All tools where the primary input-type defines multipleOfType == true
3. All tools that consume the output of type #2 tools

5.1.2 Makefile Fragments

Obviously, the makefile we just looked at is incomplete. There are no rules for building source files that are not built by the rules defined in the main makefile. However, the build file generator places that information into makefile fragments for each subdirectory contributing source to the build. The figure below shows what the fragment for the source1/ subdirectory looks like.

As you can see, the fragment contributes one file, class1.cpp, and a rule to build all source files with the ‘cpp’ extension in the subdirectory where it is located. The content of the dependency and command lines is derived from the build settings model. The dependency line is supplied by the build model which has a list of tools and know which (if any) build files with a particular extension. When a tool is found, it is asked for the extension of the output. For the command line, the tool that builds for the extension supplies the actual command, while the options for the tool supply the arguments to pass to it.

5.1.3 Dependency Makefile Fragments

There is one final piece to the puzzle, and that is a list of dependencies for each source file in the build. Recall that make will rebuild any file that is out of date in its dependency graph, but it only adds the dependency to the graph if it is explicitly told to do so. Thus, it is the responsibility of the makefile generator to completely describe all dependencies for make. Consider the dependencies of the final build target to Class1. It is obvious that if the implementation file, Class1.cpp, changes then the object module, Class1.o, should be rebuilt. In fact, we described that dependency in the makefile described in § 5.1.2. What may be less clear is that the object module should be updated if the class description in Class1.h changes. To make matters more complex, Class1 is in a has-a relationship with Class2, so any changes to Class2.h should result in a rebuild of Class1.o. Finally, the build file generator puts dummy build targets for each header file in the dependency list. This is important because if the header file is moved or deleted, make will try to find a rule to build the dependency and if a dummy target is not present, it will stop.

Additional dependency calculator modes are supported by the MBS.  See § 7.3.

5.1.4 Support Makefiles

There are two other makefiles that are generated and included in the main makefile. The first, sources.mk, defines a list of source macros, such as C_SRCS, and all of the subdirectories the builder believes contribute source code to the build. The second, objects.mk, contains two special macros used by the build, LIBS and USER_OBJS, which can be contributed to by options that are marked with a special type in the tool-chain definition.

5.1.5 Inter-Project Dependencies

A project may reference one or more additional projects in the workspace. The makefile generator attempts to generate these dependencies in two ways. First, the makefile must have a dependency on the build goal of the referenced project in the main target, and it must include instructions for building those targets as a separate rule.

For the remainder of this discussion, let us consider the following basic scenario. Project Makefile Example builds an executable, Messages.exe. It references a project, UI Widgets, which builds a shared library, UIWidgets.dll. The main build target in the makefile for Makefile Example would be generated with the output of UI Widgets as a dependency.

As you can see from the generated makefile above, the rule for the target Messages.exe will be run if UIWidgets.dll has changed. This works well if the output of the referenced project can be determined. For the moment, this is only the case when the referenced project is managed. Standard make projects do not know what the output of their build step is since that information is encoded in the makefile. If a managed project references a standard project, it will not have an explicit dependency on the output of that project.

The managed builder relies on the Eclipse build framework to properly determine the build order when projects involved in a build reference other projects. As long as the build takes place inside the CDT, the managed builder can trust that the build framework will build the projects in the proper order.

5.1.6 Makefile Generator Constraints

The current implementation of the default Gnu makefile generator assumes a set of constraints that must be met in your tool-chain definition in order for it to generate valid makefiles:

1. Input files must be specified via project relative or absolute paths.
2. Output files must be specified via configuration build directory relative or absolute paths.
3. A tool with a primary input type where the multipleOfType attribute is set to true executes once during the build using all of the project resources and generated outputs that match its input file extensions.  A subset of the full set of input files can be defined using the buildVariable attribute in the inputType of the tool, and the outputType of other tools.
4. If any inputType of a tool has the multipleOfType attribute set to true, then primary inputType of the tool must have the multipleOfType attribute set to true.
5. A tool with a primary input type where the multipleOfType attribute is set to false executes per project resource and generated output that match its input file extensions.  A subset of the full set of input files can be defined using the buildVariable attribute in the inputType of the tool, and the outputType of other tools.
6. A tool must be able to determine all of its output file names and dependencies given the name(s) of its primary input file(s).
7. The main makefile contains the rules for the "target" tool, for all tools with a primary input type where the multipleOfType attribute is set to true, and for any tool that consumes the output of these tools.
8. Each fragment makefile contains the rules for all project resources in the current directory and for generated outputs that are not consumed by tools where the multipleOfType attribute is set to true.

6 Tutorial: An Example Tool Integration

One of the features of the MBS is that you can add custom project-types and tool integrations. The tutorial in this section will walk you through the basic steps of setting up your environment, creating a new plugin where you can define a tool integration, and give you pointers for publishing the tool integration for others to use.

6.1 Setting up your Environment

Tool integrations are specified by extending the buildDefinitions 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 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 used to install the CDT.

6.2 Creating your Plug-in Project

Now that the source for the CDT is available, you will create a plug-in project containing your tool definitions. Technically the extension can be defined in any plug-in manifest, but for this tutorial we will create a new, empty plug-in project with an empty plug-in manifest file.

1. Open the New Project... wizard (File > New > Project...), choose Plug-in Project from the Plug-in Development category and click the Next > button.
   
2. On the Plug-in Project page, use org.eclipse.cdt.example.toolchain as the name for your project, and click the Next > button.
   
3. On the Plug-in Content page, you will see that the wizard has set the id to org.eclipse.cdt.example.toolchain by default. We are going to be defining the tool integration in the plug-in manifest file without writing any code, so de-select the "Generate the Java class that..." check-box and click on the Finish button.
4. If asked if you would like to switch to the Plug-in Development perspective, answer Yes.

6.3 Creating the Extension

You have installed the CDT source and 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.

1. 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.toolchain project in the Package Explorer to expand it. Click on the expansion icon beside META-INF, and then double click on the MANIFEST.MF file to edit its contents.
2. We have to add a dependency between our project and the org.eclipse.cdt.managedbuilder.core plug-in where the extension point is defined. Click on the Dependencies tab located along the bottom of the manifest editor. Click the Add… button located beside the Required Plug-Ins list. Select org.eclipse.cdt.managedbuilder.core from the list and then click the OK button.
3. Select the Extensions tab located along the bottom of the manifest editor. Click the Add… button located beside the All Extensions list.
4. You should now be on the Extension Points tab on the Extension Point Selection page. Make sure that the Show only extension points from the required plug-ins check-box is selected. Select org.eclipse.cdt.managedbuilder.core.buildDefintions from the list of extension points.  Click the Finish button.
5. In the Extension Details column in the manifest editor, use org.eclipse.cdt.example.toolchain as the ID for the extension, and Example Tool Chain for the Name.

6.4 Adding a Project Type

Now we will add a new projectType, configuration, toolChain, builder, targetPlatform and an example tool to the extension.

1. Right click on org.eclipse.cdt.managedbuilder.core.buildDefinitions in the All Extensions column of the manifest editor to access the context menu for the extension. Select New > projectType to add a projectType definition. A new projectType with the id org.eclipse.cdt.example.toolchain.projectType[n] should appear below the extension point. That's a bit verbose, so rename it to example.toolchain.executable.
   
2. Let’s give the new projectType a human-readable name. Locate the name property in the Extension Element Details column. For now, let’s use the name Example Executable for our projectType.
3. Make sure that the values of isTest and isAbstract are set to false.
   

6.5 Adding a Configuration

We have now added a basic project-type definition. We now want to define a default configuration. Normally, you would consider defining both a release and debug configuration, but we want to keep this example simple so we will restrict ourselves to a single configuration.

1. Right click on Example Executable in the All Extensions list. From the context menu select New > configuration.
   
2. Change the value of the name property and  to be Test Release and the value of id to be example.toolchain.configuration.release.
3. 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.
4. 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

6.6 Adding a ToolChain

Each configuration requires a toolChain child that defines the set of tools used by the configuration.

1. Right click on Test Release in the All Extensions list. From the context menu select New > toolChain.
   
2. Change the value of the name property and  to be Example Tool-chain  and the value of id to be example.toolchain.toolchain.
3. We want the new project-type to appear when we run the new project wizard on our host platform, so we have to define the operating systems that the toolChain should be visible on. Locate the osList property and click it to edit the value. Enter win32 if you are running the tutorial on Windows, linux if you are running on one of the Linux distributions, solaris, hpux, or aix if you are running on a version of Solaris, or other if none of the above apply.

6.7 Adding a Builder

Each toolChain can have a builder child that describes the build utility used by the tool-chain to create the build artifacts of the configuration.

1. Right click on Example Tool-chain in the All Extensions list. From the context menu select New > builder.
2. Change the value of the name property to be Example Builder and the value of id to be example.toolchain.builder.
3. Locate the Command property, click on it to edit the value, and enter make.

6.8 Adding a TargetPlatform

Each toolChain can have a targetPlatform child that describes the target operating system(s)/architecture(s) that build artifacts created by the tool-chain are intended to execute on.

1. Right click on Example Tool-chain in the All Extensions list. From the context menu select New > targetPlatform.
2. Change the value of the name property and  to be Example Target Platform  and the value of id to be example.toolchain.targetplatform.
3. Our target platform is the same as our host platform.  Enter the same value for the osList property as entered for the ToolChain osList.
4. Set the value of the binary parser property based on the platform you will be using to create your example projects on. For example, if you are running this tutorial on Linux or Solaris, enter the value org.eclipse.cdt.core.ELF. If you are running the tutorial on Windows, enter the value org.eclipse.cdt.core.PE64.

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.

1. Right click on Example Tool-chain to get the context menu and select New > tool. Name the tool Compiler and make its id example.toolchain.compiler.
2. Let us assume that the tool should appear for both C and C++ projects, although this is not always the case. Locate the natureFilter property and select both from the list of choices.
3. Tools often have a flag to specify the primary output of a tool. For the purposes of this example, set the outputFlag property to -o.
4. Finally, we want to specify the command that is needed to invoke the tool. For this example, we are not interested in actually calling a real tool, so just enter ccc as the value for the command property.

6.10 Adding Input and Output Types

Each tool describes its inputs and outputs in InputType and OutputType elements. 

1. 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.

2. Our imaginary compiler only works on c source files. Locate the sourceContentType property and set it to org.eclipse.cdt.core.cSource.

3. 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 org.eclipse.cdt.core.cHeader and the dependencyCalculator property to be org.eclipse.cdt.managedbuilder.makegen.internal.DefaultIndexerDependencyCalculator.

4. Set the primaryInput property to true.

5. 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.

6. 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.

7. 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.

8. Set the primaryOutput property to true.

6.11 Testing the ProjectType

We have now defined enough information to create a project for our new example project-type, so let’s go test it out.

1. Make sure our example project is selected in the Package Explorer. Select Run > Debug As > Eclipse Application to start a new run-time workbench instance that includes the new tool information you have created. You may be prompted to save the resource you were editing. If prompted, answer Yes.
   
2. In the new workspace, open the C/C++ perspective.
3. Run the new project wizard. From the Selection page choose either a managed C or C++ project. Click the Next > button, give your project any name you wish, and click Next > again.
   
4. You should now be at the Select a type of project page. Your new project-type will appear as a choice in the Project Type selection widget. Select it and note that the list of available configurations now contains the single configuration we defined for the project-type.
   
5. Click Finish.
   
6. Right click on your new project in the Navigator or C/C++ Projects view to access the context menu, and select Properties to open the property browser for the project. Select C/C++ Build from the choices, select the Tool Settings tab, and note that the tool we defined appears in the list.
7. Select the Build Settings tab.  The user can change the build output name and the build command from here, and the MBS will manage that selection between sessions.
8. Select the Error Parsers tab. Recall that you added all five parsers to the new target definition, so they should all be selected in the list. The user can change that selection from here, and the MBS will manage that selection between sessions.
   
9. Select the Binary Parser tab. Note that the default binary parser you specified for the target should be selected in the list. The user can change that selection from here, and the MBS will manage that selection between sessions.

At this point, you have no doubt noticed that the C/C++ Build property page does 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.

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 add three example options to it.

1. Shutdown the debug session.
   
2. Switch back to the Plug-in Development perspective. Right click on the Compiler entry in the extension description to bring up the context menu. Select New > optionCategory to add the category. Set the name of the category to General.
3. You must specify the id of the tool the category belongs to in the owner property. The simplest way to do this is to copy the id from the compiler description and paste it into the owner property of the category.
   
4. Set the unique id of the category to example.compiler.optionCategory.general.
5. Right click on the tool, not the category, to bring up its context menu and select New > option to add our first option. Name the option Include paths and set the id to example.toolchain.compiler.general.incpath.
   
6. Set the valueType property to includePath from the list of choices. Please refer to § 3.13 for a description of option value types and what this decision implies.
   
7. We expect users to enter paths in this option, so to enable the right type of 'Browse" button when the user enters a new option value, set the browseType property to directory.
   
8. In the command property, enter -I.
   
9. In the category property, put the unique id of the category that you entered in step 4.
10. Add a "catch-all" option to the 'General' category of the compiler (remember, you add the option to the tool and set its category via the category property). Set the name of the option to Other flags, its id to example.toolchain.compiler.general.otherflags, its valueType to string, and its defaultValue to -c.
11. Add a check-box option to the 'General' category of the compiler. Name it Error messages, set the id to example.toolchain.compiler.general.errmsgs, and set its valueType to boolean. This is a boolean option, so it might have a command associated with the selected and unselected states. In this case we want to turn on reporting when it is selected, and turn it off when it is deselected. Set the command property to -Wall to turn on error reporting, and set the commandFalse property to -w to disable it.
    

At this point, you can test how your options appear in the UI by debugging your run-time workbench. You should see something like this.

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.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 anything. Further, the tool we defined transforms source files into object files. Another tool, like a linker, would be needed to transform those object files into a final build goal. For many tool-chains, defining a compiler and “something else” is usually sufficient, but you may have to define additional tools if your tool-chain requires intermediate build steps to function properly.

6.13.2 Defined Symbols and Header File Search Paths

There are elements of the CDT core that require build information to function properly. Things like the indexing service, search, or content assist will only function correctly if the built-in parser can retrieve information about the paths to search for include files and the preprocessor symbols defined for the project.

MBS gathers information about the defined symbols and include paths from a number of sources:

User-defined symbols and include paths:  You can flag certain tool 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 provide them to the appropriate clients in the CDT core without any further intervention on your part.

Pre-defined symbols and include paths:  A toolChain may specify the id of scanner configuration discovery profile for gathering the built-in compiler settings.  See the org.eclipse.cdt.make.core.ScannerConfigurationDiscoveryProfile extension point description in the reference documentation for more information.  If a collector is specified, MBS invokes it to return the pre-defined symbols and include paths.  If a collector is not specified, MBS searches for options of type “includePaths” and “definedSymbols” with the builtIn attribute set to true.

Environment include paths:  Your build definition may specify a envVarBuildPath element with the pathType attribute set to "buildpathInclude".  If specified, MBS will read the environment variable(s) for additional include paths.  See § 3.17 for additional information regarding the envVarBuildPath element.

6.13.3 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 provide a valid list. Flag the option value type as “libs” for external libraries or “userObjs” for object modules.

6.13.4 ProjectType and Other Element Hierarchies

One area of the build model that the tutorial does not touch on is the concept of abstract project-types discussed in § 3.2. It would be quite time consuming, not to mention error prone, if you had to redefine common tool-chains, tools, etc. each time you wanted to create a new project-type. Instead, the build model allows you to organize project-types into hierarchies that promote the sharing of common property settings and element definitions between related project-types. When you create a parent project-type though, you may not want that project-type to be selected by the user in the new project wizard. In that case, make the projectType abstract and it will no longer appear as an option for users. Flagging an element as abstract is a UI design decision; you can declare a non-abstract element as the super-class of another element.

Since 2.1 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.13.5 Publishing your Plug-in

The subject of packaging Eclipse plug-ins is well covered in the Platform Plug-in Developer Guide. It is strongly recommended that you review this information carefully if you plan on deploying products based on Eclipse. However, making your tool integration available to other users of Eclipse is not difficult. You must supply the plugin manifest we created inside the Eclipse platform's plug-in directory. The plug-in directory is named plugins and is typically located underneath the main directory where you installed the Eclipse platform.

1. From the Plug-in Development Perspective, select the plugin.xml file for your plug-in in the package explorer. Open the File > Export... wizard. On the Select page, chose Deployable Plugins and Fragments from the export destination list. Click the Next > button.
2. In the Deployable Plugins and Fragments dialog, Export Destination section, select Directory and click the Browse... button. Browse to your Eclipse installation. Deselect all Export Options.  Click the Finish button.
3. Restart Eclipse, switch to the C/C++ Development Perspective and run the new project wizard to create a new project based on your tool integration.

7 Adding Dynamic Behavior

7.1 Overview

MBS defines a number of element attributes that allow the tool integrator to customize the behavior of the MBS by implementing an MBS-defined interface in a Java class.  This section describes these attributes and the interfaces.

7.2 Replacing the Build File Generator

You can specify a replacement build file generator for a project configuration. You must specify and supply a class that implements the IManagedBuilderMakefileGenerator interface shown below.  The class name is assigned to the builder element, buildfileGenerator attribute.

Figure 10 Makefile generator interface

At build time, the MBS builder will ask for the build file generator associated with the project configuration being built. If you have specified a class in your plugin, that class will be instantiated at this point. The MBS builder will then give the new build file generator a chance to initialize itself.  At the very least, your generator should cache the build information and progress monitor so you can access build settings and respond to the user canceling the build in a timely fashion.

Since the MBS builder is an incremental builder, it will be asked to build or rebuild the project depending on the type of delta that the Eclipse workspace detects. For an incremental build using the default generator, it will ask the generator to generate makefiles. For a full rebuild, it will ask for a regeneration of all makefiles. Depending on the makefile pattern that you generate, these may end up doing the same thing. It is important to note that the builder pays special attention to the return value of the generate and regenerate methods, so it is important to return a instance of MultiStatus containing some sort or result. For example, the following code snippet will tell the builder that it can go on and invoke the make utility and start the build.

Typically, you have to specify source-level dependencies in your makefiles as described in § 5.1.3. The builder will ask the generator to generate or regenerate these dependencies depending on whether it is an incremental or rebuild situation. If your source-level dependencies are generated as a by-product of the build step, this call may result in a NOP. In the case of the default generator, it results in some post-processing of the dependency descriptions. What happens depends entirely on the build utility you are using and the build file pattern you implement.

7.3 Replacing the Dependency Calculator

As we know, the generated build file must contain all of the dependencies for a build target, but not every system has the same set of utilities for discovering them. Some tool integrations might rely on an external utility like makedepend to calculate source-level dependencies. Other tool integrations might provide dependency calculation along with the other build tools, like the GCC preprocessor. The replaceable dependency calculator in the MBS tries to accommodate many types of dependency discovery mechanisms.

The mechanism for replacing the dependency calculator is similar to the build file generator, except that the dependency calculator is associated with a tool inputType, not a builder. You must create a class that implements the IManagedDependencyGenerator2 interface shown below and specify that class in the inputType element, dependencyCalculator attribute.  Typically, dependency calculators are only relevant for a "compiler" tool, but what tool you use to specify the generator (or generators) is arbitrary.

By design, a dependency calculator must answer what type of dependency generation it will do.  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.  This is a TYPE_CUSTOM dependency calculator as defined below.  See the IManagedDependencyCalculator interface discussion below for more information. 
2. The build file generator and the tool-chain cooperate in creating and using separate "dependency" files.  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.  This is either a TYPE_BUILD_COMMANDS dependency calculator or a TYPE_PREBUILD_COMMANDS dependency calculator as defined below.  See the IManagedDependencyCommands and IManagedDependencyPreBuild interfaces discussion below for more information.

public interface IManagedDependencyGeneratorType {
    /**
     *  Constants returned by getCalculatorType
     */
    public int TYPE_NODEPS = 0; //  Deprecated - use TYPE_NODEPENDENCIES
    public int TYPE_COMMAND = 1; //  Deprecated - use TYPE_BUILD_COMMANDS
    public int TYPE_INDEXER = 2; //  Deprecated - use TYPE_CUSTOM
    public int TYPE_EXTERNAL = 3; //  Deprecated - use TYPE_CUSTOM
    public int TYPE_OLD_TYPE_LIMIT = 3;

    //  Use these types
    public int TYPE_NODEPENDENCIES = 4;
    public int TYPE_BUILD_COMMANDS = 5;
    public int TYPE_PREBUILD_COMMANDS = 6;
    public int TYPE_CUSTOM = 7;

    /**
     * Returns the type of dependency generator that is implemented. 
     *
     *   TYPE_NODEPENDENCIES indicates that no dependency generator is
     *     supplied or needed.
     *   TYPE_CUSTOM indicates that a custom, "build file generation time"
     *     dependency calculator is implemented.  Note that the dependency
     *     calculator will be called when the makefile is generated, and
     *     for every source file that is built by this tool in the build
     *     file, not just for those that have changed since the last build
     *     file generation.
     *   TYPE_BUILD_COMMANDS indicates that command lines or options will
     *     be returned to be used to calculate dependencies.  These
     *     commands/options are added to the build file to perform dependency
     *     calculation at "build time".  This currently supports
     *     compilers/tools that generate .d files either as a
     *     side-effect of tool invocation, or as a separate step that is
     *     invoked immediately before or after the tool invocation.
     *   TYPE_PREBUILD_COMMANDS indicates that a separate build step is
     *     invoked, prior to the the normal build steps, to update the
     *     dependency information.  These commands are added to the build
     *     file to perform dependency calculation at "build time".  Note
     *     that this step will be invoked every time a build is done in
     *     order to determine if dependency files need to be re-generated.
     *
     * @return int
     */
        public int getCalculatorType();
}

After deciding upon the type of dependency calculator, you must implement the methods in IManagedDependencyGenerator2.  The method getDependencySourceInfo returns an instance of the IManagedDependencyInfo interface.  This can be any one of the 3 interfaces that derive from IManagedDependencyInfo  - IManagedDependencyCalculator, IManagedDependencyCommands or IManagedDependencyPreBuild which are discussed below.  The returned interface is called to get the dependency information for a particular source file in the configuration.  See the descriptions of the other methods in IManagedDependencyGenerator2 in the code comments below.

public interface IManagedDependencyGenerator2 extends IManagedDependencyGeneratorType {
	
    /**
     * Returns an instance of IManagedDependencyInfo for this source file.
     * IManagedDependencyCalculator, IManagedDependencyCommands
     * and IManagedDependencyPreBuild are all derived from
     * IManagedDependencyInfo, and any one of the three can be returned.
     * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS, 
     * TYPE_CUSTOM or TYPE_PREBUILD_COMMANDS.
     *
     * @param source  The source file for which dependencies should be calculated
     *    The IPath can be either relative to the project directory, or absolute in the file system.
     * @param buildContext  The IConfiguration or IResourceConfiguration that
     *   contains the context in which the source file will be built
     * @param tool  The tool associated with the source file
     * @param topBuildDirectory  The top build directory of the configuration.  This is
     *   the working directory for the tool.  This IPath is relative to the project directory.
     * @return IManagedDependencyInfo    
     */
	public IManagedDependencyInfo getDependencySourceInfo(
		IPath source,
		IBuildObject buildContext,
		ITool tool,
		IPath topBuildDirectory);

    /**
     * Returns the file extension used by dependency files created
     * by this dependency generator.
     * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS or 
     * TYPE_PREBUILD_COMMANDS.
     *    
     * @param buildContext  The IConfiguration that contains the context of the build
     * @param tool  The tool associated with the dependency generator. 
     *
     * @return String
     */
	public String getDependencyFileExtension(
		IConfiguration buildContext,
		ITool tool);

    /**
     * Called to allow the dependency calculator to post-process dependency files.
     * This method is called after the build has completed for at least every 
     * dependency file that has changed, and possibly for those that have not
     * changed as well.  It may also be called with dependency files created by
     * another tool.  This method should be able to recognize dependency files
     * that don't belong to it, or that it has already post-processed.
     * This is called when getCalculatorType returns TYPE_BUILD_COMMANDS or 
     * TYPE_PREBUILD_COMMANDS.
     *    
     * @param dependencyFile  The dependency file  
     *    The IPath can be either relative to the top build directory, or absolute in the file system.
     * @param buildContext  The IConfiguration that contains the context of the build
     * @param tool  The tool associated with the dependency generator.  Note that this is
     *    not necessarily the tool that created the dependency file
     * @param topBuildDirectory  The top build directory of the project.  This is
     *   the working directory for the tool.
     *
     * @return boolean  True if the method modified the dependency (e.g., .d) file
     */
	public boolean postProcessDependencyFile(
		IPath dependencyFile,
		IConfiguration buildContext,
		ITool tool,
		IPath topBuildDirectory);
}

7.3.1 TYPE_CUSTOM dependency calculator

A TYPE_CUSTOM dependency calculator must implement the IManagedDependencyCalculator interface.

public interface IManagedDependencyCalculator extends IManagedDependencyInfo {
	
    /**
     * Returns the list of source file specific dependencies.
     *   
     * The paths can be either relative to the project directory, or absolute 
     * in the file system.
     *
     * @return IPath[]    
     */
	public IPath[] getDependencies();
	
    /**
     * Returns the list of source file specific additional targets that the 
     * source file creates.  Most source files will return null.  An example 
     * of where additional targets should be returned is for a Fortran 90 
     * source file that creates one or more Fortran Modules.
     * 
     * Note that these output files that are dependencies to other invocations
     * of the same tool can be specified here, or as another output type 
     * of the tool.  If the output file can be used as the input of a different
     * tool, then use the output type mechanism.
     *   
     * The paths can be either relative to the top build directory, or absolute 
     * in the file system.
     *
     * @return IPath[]    
     */
	public IPath[] getAdditionalTargets();
}

An example TYPE_CUSTOM dependency calculator can be found in the MBS test suite - org.eclipse.cdt.managedbuilder.core.tests\DefaultFortranDependencyCalculator.

If you do not have an external process or tool to calculate dependencies, you could take advantage of the indexer in the CDT. In this case, you are restricted to generating the dependencies independently of the build steps. The dependency calculator asks the indexer for a list of dependencies and returns them as an array of IResource instances. Obviously, if you rely on the indexer, you must wait for it to complete its work before it will answer, so your build may take longer to complete.  See the org.eclipse.cdt.managedbuilder.makegen.internal\DefaultIndexerDependencyCalculator class for an example of how this was implemented using the old, deprecated IManagedDependencyGenerator interface.  However, it doesn't seem as if it worked with CDT 3.0.  Readers are encouraged to update this method to the new interfaces and contribute the implementation to CDT.

7.3.2 TYPE_BUILD_COMMANDS dependency calculator

There are multiple ways that these separate dependency files can be created by the tool-chain and used by the builder.  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 TYPE_PREBUILD_COMMANDS for more information.  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: https://sourceware.org/automake/automake.html#Dependency-Tracking-Evolution.  Use the IManagedDependencyCommands interface for this mode.

Two sub-scenarios of this mode are to:

1. 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.
2. 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 DefaultGCCDependencyCalculator3Commands class.

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.

Examples of the use of TYPE_BUILD_COMMANDS can be found in org.eclipse.cdt.managedbuilder.makegen.gnu\DefaultGCCDependencyCalculator2Commands and DefaultGCCDependencyCalculator3Commands.

public interface IManagedDependencyCommands extends IManagedDependencyInfo {
	
    /**
     * Returns the list of generated dependency files.
     *   
     * The paths can be either relative to the top build directory, or absolute 
     * in the file system.
     *
     * @return IPath[]    
     */
	public IPath[] getDependencyFiles();

    /**
     * Returns the command lines to be invoked before the normal tool invocation 
     * to calculate dependencies.
     *
     * @return String[]  This can be null or an empty array if no dependency 
     *                   generation command needs to be invoked before the normal 
     *                   tool invocation.
     */
	public String[] getPreToolDependencyCommands();
	
    /**
     * Returns the command line options to be used to calculate dependencies.
     * The options are added to the normal tool invocation. 
     *
     * @return 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[]?
     */
	public String[] getDependencyCommandOptions();
 	
    /**
     * Returns the command lines to be invoked after the normal tool invocation  
     * to calculate dependencies.  
     *
     * @return String[]  This can be null or an empty array if no dependency 
     *                   generation commands needs to be invoked after the normal 
     *                   tool invocation
     */
	public String[] getPostToolDependencyCommands();
	
    /**
     * 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.
     *
     * @return boolean
     */
	public boolean areCommandsGeneric();
}

7.3.3 TYPE_PREBUILD_COMMANDS dependency calculator

"To this end, after reading in all makefiles, make will consider each as a goal target and attempt to update it. If a makefile has a rule which says how to update it (found either in that very makefile or in another one)..., it will be updated if necessary.  After all makefiles have been checked, if any have actually been changed, make starts with a clean slate and reads all the makefiles over again."

We can use this to ensure that the dependency files are up to date by adding rules to the make file for generating the dependency files.  These rules are returned by the call to the getDependencyCommands method.  However, this has a significant problem when we don't want to build the build target, but only want to "clean" the configuration, for example. If we invoke make just to clean the configuration, make will still update the dependency files if necessary, thereby re-generating the dependency files only to immediately delete them.  The workaround suggested by the make documentation is to check for an invocation using the "clean" target, and to not include the dependency files it that case. For example,

ifneq ($(MAKECMDGOALS),clean)
include $(DEPS)
endif

The restriction with this is that it only works if "clean" is the only target specified on the make command line. Therefore, the build "clean" step must be invoked separately.

Examples of the use of TYPE_PREBUILD_COMMANDS can be found in org.eclipse.cdt.managedbuilder.makegen.gnu\DefaultGCCDependencyCalculatorPreBuildCommands.

public interface IManagedDependencyPreBuild extends IManagedDependencyInfo {

    /**
     * Returns the list of generated dependency files.
     *   
     * The paths can be either relative to the top build directory, or absolute 
     * in the file system.
     *
     * @return IPath[]    
     */
	public IPath[] getDependencyFiles();

    /**
     * Returns the name to be used in the build file to identify the separate
     * build step.  Note that this name should be unique to the tool since
     * multiple tools in a tool-chain may be using this method of
     * dependency calculation.
     *    
     * @return String  
     */
	public String getBuildStepName();

    /**
     * Returns the command line(s) to be invoked in the separate 
     * dependencies pre-build step.
     *
     * @return String[]
     */
	public String[] getDependencyCommands();
	
   /**
     * Returns true if the command lines 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 
     * 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.
     *
     * @return boolean
     */
	public boolean areCommandsGeneric();
}

7.4 Replacing the Command Line Generator

You can specify a replacement command line generator for a tool. You must specify and supply a class that implements the IManagedCommandLineGenerator interface.  The class name is assigned to the tool element, commandLineGenerator attribute.

public interface IManagedCommandLineGenerator {

   public IManagedCommandLineInfo generateCommandLineInfo(

               ITool tool,

               String commandName,

               String[] flags,

               String outputFlag,

               String outputPrefix,

               String outputName,

               String[] inputResources,

               String commandPattern);

}

public interface IManagedCommandLineInfo {

   public String getCommandLine();

   public String getCommandName();

   public String getFlags();

   public String getOutputFlag();

   public String getOutputPrefix();

   public String getOutputName();

   public String getInputResources();

}

MBS calls IManagedCommandLineGenerator.generateCommandLineInfo to generate the command line information.  The supplied IManagedCommandLineGenerator could modify the command line parts if necessary and then provide the modified values, as well as the complete command line, in the IManagedCommandLineInfo interface.  The default MBS implementation does not modify any of the command line parts.  It 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

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 build path variables (“bin”, “include”, “lib”). These environment variables are defined by MBS for the process in which the builder (e.g., make) runs. In addition to providing environment variables the tool-chain integrator can specify the names of the environment variables used by the tool for specifying the include and library paths. MBS will examine these variables and pass the appropriate information about includes and libraries to the rest of the CDT.

The tool-integrator can provide Project-level and Configuration-level environment variable suppliers separately: 

To provide a Configuration-level supplier the “configurationEnvironmentSupplier” 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 IConfigurationEnvironmentVariableSupplier interface

public interface IConfigurationEnvironmentVariableSupplier{

  /**

   *

   * @variableName the variable mane

   * @param configuration configuration

   * @param provider the instance of the environment variable provider to be used for querying the

   * environment variables from within the supplier. The supplier should use this provider to obtain

   * the already defined environment instead of using the “default” provider returned by the

   * ManagedBuildManager.getEnvironmentVariableProvider().

   * The provider passed to a supplier will ignore searching the variables for the levels

   * higher than the current supplier level, will query only the lower-precedence suppliers

   * for the current level and will query all suppliers for the lower levels.

   * This is done to avoid infinite loops that could be caused if the supplier calls the provider

   * and the provider in turn calls that supplier again. Also the supplier should not know anything

   * about the environment variables defined for the higher levels.

   * @return the reference to the IBuildEnvironmentVariable interface representing

   * the variable of a given name

   */

   IBuildEnvironmentVariable getVariable(String variableName,

IConfiguration configuration,

IEnvironmentVariableProvider provider);

  /**

   * @param configuration configuration

   * @param provider the instance of the environment variable provider to be used for querying the

   * environment variables from within the supplier. The supplier should use this provider to obtain

   * the already defined environment instead of using the “default” provider returned by the

   * ManagedBuildManager.getEnvironmentVariableProvider().

   * The provider passed to a supplier will ignore searching the variables for the levels

   * higher than the current supplier level, will query only the lower-precedence suppliers

   * for the current level and will query all suppliers for the lower levels. 

   * This is done to avoid infinite loops that could be caused if the supplier calls the provider

   * and the provider in turn calls that supplier again. Also the supplier should not know anything

   * about the environment variables defined for the higher levels.

   * @return the array of IBuildEnvironmentVariable that represents the environment variables

   */

   IBuildEnvironmentVariable[] getVariables (IConfiguration configuration,

IEnvironmentVariableProvider provider);

}

To provide a Project-level supplier the “projectEnvironmentSupplier” attribute in the projectType definition must be specified. The value of this attribute should be set to the name of the class which implements the IProjectEnvironmentVariableSupplier interface.

public interface IProjectEnvironmentVariableSupplier{

  /**

   * @variableName the variable mane

   * @param project the managed project

   * @param provider the instance of the environment variable provider to be used for querying the

   * environment variables from within the supplier. The supplier should use this provider to obtain

   * the already defined environment instead of using the “default” provider returned by the

   * ManagedBuildManager.getEnvironmentVariableProvider().

   * The provider passed to a supplier will ignore searching the variables for the levels

   * higher than the current supplier level, will query only the lower-precedence suppliers

   * for the current level and will query all suppliers for the lower levels.

   * This is done to avoid infinite loops that could be caused if the supplier calls the provider

   * and the provider in turn calls that supplier again. Also the supplier should not know anything

   * about the environment variables defined for the higher levels.

   * @return the reference to the IBuildEnvironmentVariable interface representing

   * the variable of a given name

   */

   IBuildEnvironmentVariable getVariable(String variableName,

IManagedProject project,

IEnvironmentVariableProvider provider);

  /**

   *

   * @param project the managed project

   * @param provider the instance of the environment variable provider to be used for querying the

   * environment variables from within the supplier. The supplier should use this provider to obtain

   * the already defined environment instead of using the “default” provider returned by the

   * ManagedBuildManager.getEnvironmentVariableProvider().

   * The provider passed to a supplier will ignore searching the variables for the levels

   * higher than the current supplier level, will query only the lower-precedence suppliers

   * for the current level and will query all suppliers for the lower levels.

   * This is done to avoid infinite loops that could be caused if the supplier calls the provider

   * and the provider in turn calls that supplier again. Also the supplier should not know anything

   * about the environment variables defined for the higher levels.

   * @return the array of IBuildEnvironmentVariable that represents the environment variables

   */

   IBuildEnvironmentVariable[] getVariables (IManagedProject project,

IEnvironmentVariableProvider provider);

}

The IBuildEnvironmentVariable interface returns information regarding an individual environment variable. 

public interface IBuildEnvironmentVariable{

    public static final int ENVVAR_REPLACE = 1;

    public static final int ENVVAR_REMOVE = 2;

    public static final int ENVVAR_PREPEND = 3;

    public static final int ENVVAR_APPEND = 4;

    String getName();

    String getValue();

   /**

    * @return one of the IBuildEnvironmentVariable.ENVVAR_* operation types

    */

    int getOperation();

   /**

    * @return if the variable can hold the list of values this method returns the String representing

    * the delimiter that is used to separate values. This information is used for the following:

    *

    * 1. in append and prepend operations:

    * If the variable already exists and contains some value the new

    * value will be calculated in the following way:

    * For the “prepend” operation:

    *         <New value> = <the value from the getValue() method><delimiter><Old value>

    * For the “append” operation:

    *         <New value> = <Old value><delimiter><the value from the getValue() method>

    *

    * The Environment Variable Provider will also remove the duplicates of “sub-values”

    * in the resulting value.

    * For example:

    * If the current value is “string1:string2:string3”, the getDelimiter() method returns “:”

    * and getValue() method returns “string4:string2” the new value will contain:

    * For the “prepend” operation: “string4:string2:string1:string3”

    * For the “append” operation: “string1:string3:string4:string2”

    *
    * 2. Since the environment variables are also treated as build macros the delimiter is also used

    * by the BuildMacroProvider to determine the type of the macro used to represent the

    * given environment variable. If the variable has the delimiter it is treated as the Text-List macro

    * otherwise it is treated as the Text macro. (See Build Macro design for more details)

    *

    * To specify that no delimiter should be used, the getDelimiter() method should
    * return null or an empty string

    */

    String getDelimiter();

}

7.7 Defining a Build Path Resolver 

To provide a build path resolver, 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 for resolving the environment variable values to build paths.

public interface IBuildPathResolver {

   /**

    *

    * @param pathType one of the IEnvVarBuildPath.BUILDPATH _xxx

    * @param variableName represents the name of the variable that holds the build paths

    * @param variableValue represents the value of the value specified with the

    *     variableName argument

    * @param configuration represents configuration for which the build paths are requested

    */

    String[] resolveBuildPaths(

                 int pathType,

                 String variableName,

                 String variableValue,

                 IConfiguration configuration);

}

See org.eclipse.cdt.managedbuilder.gnu.cygwin.CygwinPathResolver for an example of a build path resolver.  It converts Cygwin-style paths to Windows paths.

7.8 Defining Build Macros

The IConfigurationBuildMacroSupplier interface and the IProjectBuildMacroSupplier interface allow a tool-integrator to define build macros and their values.

All methods of the IConfigurationBuildMacroSupplier interface MUST return macros ONLY for the configuration context, and MUST NOT search for macro values for contexts with lower precedence. This is up to BuildMacroProvider to query macro suppliers passing lower-precedence context if necessary in case the macro value was not found for some specified context

public interface IConfigurationBuildMacroSupplier {

   /**

    *

    * @ macroName the macro name

    * @param configuration configuration

    * @param provider the instance of the build macro provider to be used for querying the

    * build macros from within the supplier. The supplier should use this provider to obtain

    * the already defined build macros instead of using the “default” provider returned by the

    * ManagedBuildManager.getBuildMacroProvider().

    * The provider passed to a supplier will ignore searching macros for the levels
    * higher than the current supplier level, will query only the lower-precedence suppliers

    * for the current level and will query all suppliers for the lower levels.

    * This is done to avoid infinite loops that could be caused if the supplier calls the provider

    * and the provider in turn calls that supplier again. Also the supplier should not know anything
    * about the build macros defined for the higher levels.

    * @return the reference to the IBuildMacro interface representing

    * the build macro of a given name or null if the macro of  that name is not defined

    */

    IBuildMacro getMacro(String macroName,

IConfiguration configuration,

IBuildMacroProvider provider);

   /**

    *

    * @param configuration configuration

    * @param provider the instance of the build macro provider to be used for querying the

    * build macros from within the supplier. The supplier should use this provider to obtain

    * the already defined build macros instead of using the “default” provider returned by the

    * ManagedBuildManager.getBuildMacroProvider().

    * The provider passed to a supplier will ignore searching macros for the levels

    * higher than the current supplier level, will query only the lower-precedence suppliers

    * for the current level and will query all suppliers for the lower levels.

    * This is done to avoid infinite loops that could be caused if the supplier calls the provider

    * and the provider in turn calls that supplier again. Also the supplier should not know anything

    * about the build macros defined for the higher levels.

    * @return the IBuildMacro[] array representing defined macros

    */

    IBuildMacro[] getMacros(IConfiguration configuration,

IBuildMacroProvider provider);

}

All methods of the IProjectBuildMacroSupplier interface MUST return macros ONLY for the Project context, and MUST NOT search for macro values for contexts with lower precedence. This is up to the BuildMacroProvider to query macro suppliers passing lower-precedence context if necessary in case the macro value was not found for some specified context.

public interface IProjectBuildMacroSupplier {

   /**

    *

    * @ macroName the macro mane

    * @param project the instance of the managed project

    * @param provider the instance of the build macro provider to be used for querying the

    * build macros from within the supplier. The supplier should use this provider to obtain

    * the already defined build macros instead of using the “default” provider returned by the

    * ManagedBuildManager.getBuildMacroProvider().

    * The provider passed to a supplier will ignore searching macros for the levels

    * higher than the current supplier level, will query only the lower-precedence suppliers

    * for the current level and will query all suppliers for the lower levels.

    * This is done to avoid infinite loops that could be caused if the supplier calls the provider

    * and the provider in turn calls that supplier again. Also the supplier should not know anything

    * about the build macros defined for the higher levels.

    * @return the reference to the IBuildMacro interface representing

    * the build macro of a given name or null if the macro of  that name is not defined

    */

    IBuildMacro getMacro(String macroName,

IManagedProject project,

IBuildMacroProvider provider);

   /**

    *

    * @param project the instance of the managed project

    * @param provider the instance of the build macro provider to be used for querying the

    * build macros from within the supplier. The supplier should use this provider to obtain

    * the already defined build macros instead of using the “default” provider returned by the

    * ManagedBuildManager.getBuildMacroProvider().

    * The provider passed to a supplier will ignore searching macros for the levels

    * higher than the current supplier level, will query only the lower-precedence suppliers

    * for the current level and will query all suppliers for the lower levels.

    * This is done to avoid infinite loops that could be caused if the supplier calls the provider

    * and the provider in turn calls that supplier again. Also the supplier should not know anything

    * about the build macros defined for the higher levels.

    * @return the IBuildMacro[] array representing defined macros

    */

    IBuildMacro[] getMacros(IManagedProject project,

IBuildMacroProvider provider);

}

The IBuildMacro interface returns information regarding an individual build macro. 

public interface IBuildMacro{

    public static final int VALUE_TEXT = 1; //can hold any text string

    public static final int VALUE_TEXT_LIST = 2; //can hold the array of text string values

    public static final int VALUE_PATH_FILE = 3; //can hold file path

    public static final int VALUE_PATH_FILE_LIST = 4; //can hold the array of file path values

    public static final int VALUE_PATH_DIR = 5; //can hold dir path

    public static final int VALUE_PATH_DIR_LIST = 6; //can hold the array of dir path values

    public static final int VALUE_PATH_ANY = 7; //can hold both file and dir path

    public static final int VALUE_PATH_ANY_LIST = 8; //can hold the array of  PATH_ANY

// values 

    String getName();

    /**

     * @returns IBuildMacro.VALUE_xxx

     */

    int getMacroValueType();

    /**

     * @throws BuildMacroException if macro holds StringList-type value

     */

    String getStringValue() throws BuildMacroException;

    /**

     * @throws BuildMacroException if macro holds single String-type value

     */

    String[] getStringListValue() throws BuildMacroException;

}

7.9 Defining a Configuration Name Provider

All the configuration names must be unique within a project.  You can provide unique configuration names in your build definitions, or you can dynamically created unique names.  To provide configuration names dynamically, you must specify and supply a class that implements the IConfigurationNameProvider interface shown below.  The class name is assigned to the projectType element, configurationNameProvider attribute.

Consider the following usage for a configuration name provider.  You support multiple versions of your tool-chain within the same version of CDT (see § 8.2 for a discussion of supporting multiple versions).  For the purpose of this example, assume they are versions 1.0 and 2.0.  You provide default "debug" and "release" configurations for each version of your tool-chain.  You have a choice when assigning names to these default configurations.  You can define unique names statically in your build definitions (for example, "Debug_1.0", "Debug_2.0", etc.)  However, these names are not very "user-friendly", particularly for a user who intends to use a single version of your tool-chain.  The alternative is to dynamically assign unique configuration names using a configuration name provider (see the  getNewConfigurationName method below.)  The first configuration that is created gets to use the most “basic” name – for example, “Debug”.  When another configuration is created that uses a different tool-chain version, it would see that “Debug” was already chosen, so it could return a more qualified name - for example, “Debug_2.0”.  The same technique could be used when your tool-chain supports multiple host/target platforms.

public interface IConfigurationNameProvider {

   /*
    * Returns the new unique configuration name based on the 'configuration'
    * object and the list of configuration names already in use in the project.
    *
    */

    String getNewConfigurationName(IConfiguration configuration, String [] usedConfigurationNames );
}

7.10 Defining an Output Name Provider

You can specify an output name provider for an outputType. You must specify and supply a class that implements the IManagedOutputNameProvider interface shown below.  The class name is assigned to the outputType element, nameProvider attribute.

public interface IManagedOutputNameProvider{

  /**

   *

   * Returns the output names corresponding to the primary input name(s)

   *

   * @returns String[]

   */

   IPath[] getOutputPaths(ITool tool, IPath[] primaryInputs);

}

When multipleOfType is true, an output name provider, or the outputNames attribute, is required in order for MBS to know the names of the output files.

The returned paths must be relative to the top-level build directory. However, if only a file name is returned, MBS will automatically add on the directory path relative to the top-level build directory. The relative path comes from the source file location. In order to specify that this output file is always in the top-level build directory, regardless of the source file directory structure, return "./path".

7.11 Defining an Option Value Handler

You can specify a value handler for an option.  You must specify and supply a class that implements the IManagedOptionValueHandler interface shown below.  This interface is used to dynamically manage the value of an option.

public interface IManagedOptionValueHandler{

    public final int EVENT_OPEN = 1;  /** The option is opened, i.e. its UI element
                                      * is created. The valueHandler can override
                                      * the value of the option. If it does not,
                                      * the last persisted value is used. */
    public final int EVENT_CLOSE = 2; /** The option is closed. i.e. its value has been
                                      * destroyed when a configuration/resource gets deleted.
                                      * The valuehandler can do various things assocaited with
                                      * destroying the option such as freeing the memory
                                      * associated with this option callback, if needed. */
    public final int EVENT_SETDEFAULT = 3; /** The default value option::defaultValue has
                                      * been set. The handleValue callback is called
                                      * afterwards to give the handler a chance to
                                      * override the value or to update the value in
                                      * its back-end. Typically this event will be called
                                      * when the Restore Defaults button is pressed. */
    public final int EVENT_APPLY = 4; /** The option has been set by pressing the Apply
                                      * button (or the OK button). The valueHandler can
                                      * transfer the value of the option to its own
                                      * back-end. */

   /**
    * Handles transfer between values between UI element and
    * back-end in different circumstances.
    *
    * @param configuration build configuration of option
    * (may be IConfiguration or IResourceConfiguration)
    * @param holder contains the holder of the option
    * @param option the option that is handled
    * @param extraArgument extra argument for handler
    * @param event event to be handled
    *
    * @return True when the event was handled, false otherwise.
    * This enables default event handling can take place.
    */
    boolean handleValue(IBuildObject configuration,
        IHoldsOptions holder,
        IOption option,
        String extraArgument,
        int event);

   /**
    * Checks whether the value of an option is its default value.
    *
    * @param configuration build configuration of option
    * (may be IConfiguration or IResourceConfiguration)
    * @param holder contains the holder of the option
    * @param option the option that is handled
    * @param extraArgument extra argument for handler
    *
    * The additional options besides configuration are supplied to
    * provide enough information for querying the default value from
    * a potential data storage back-end.
    *
    * @return True if the options value is its default value and
    * False otherwise. This enables that default event handling can
    * take place.
    */
    boolean isDefaultValue(IBuildObject configuration,
        IHoldsOptions holder,
        IOption option,
        String extraArgument);

   /**
    * Checks whether an enumeration value of an option is currently a
    * valid choice. The use-case for this method is the case, where
    * the set of valid enumerations in the plugin.xml file changes.
    * The UI will remove entries from selection lists if the value
    * returns false.
    *
    * @param configuration build configuration of option
    * (may be IConfiguration or IResourceConfiguration)
    * @param holder contains the holder of the option
    * @param option the option that is handled
    * @param extraArgument extra argument for handler
    * @param enumValue enumeration value that is to be checked
    *
    * The additional options besides configuration are supplied to
    * provide enough information for querying information from a
    * a potential data storage back-end.
    *
    * @return True if the enumeration value is valid and False
    * otherwise.
    */
    boolean isEnumValueAppropriate(IBuildObject configuration,
        IHoldsOptions holder,
        IOption option,
        String extraArgument,
        String enumValue);
}

See the Shared Tool Options design document in bugzilla #90481 for additional information.

7.12 Defining an Option Applicability Calculator

You can specify an option applicability calculator for an option.  You must specify and supply a class that implements the IManagedOutputNameProvider interface shown below.  The class name is assigned to the outputType element, nameProvider attribute.  You should implement this interface when an option is not always applicable - for example, when an option is only used if another option has a particular value.

public interface IOptionApplicability {
  /**
  * This method is queried whenever a makefile or makefile fragment is
  * generated which uses this option, and in the C/C++ Build property
  * pages when displaying the current command line.
  *
  * @param configuration build configuration of option
  * (may be IConfiguration or IResourceConfiguration)
  * @param holder contains the holder of the option
  * @param option the option itself 
  *
  * @return true if this option is to be used in command line
  * generation, false otherwise
  */
  public boolean isOptionUsedInCommandLine(
    IBuildObject configuration,
    IHoldsOptions holder,
    IOption option);

  /**
  * This method is queried whenever a new option category is displayed.
  *
  * @param configuration build configuration of option
  * (may be IConfiguration or IResourceConfiguration)
  * @param holder contains the holder of the option
  * @param option the option itself
  *
  * @return true if this option should be visible in the build options page,
  * false otherwise
  */
  public boolean isOptionVisible(
    IBuildObject configuration,
    IHoldsOptions holder,
    IOption option);

  /**
  * Whenever the value of an option changes in the GUI, this method is
  * queried on all other visible options for the same category. Note that
  * this occurs when the GUI changes - the user may opt to cancel these
  * changes.
  *
  * @param configuration build configuration of option
  * (may be IConfiguration or IResourceConfiguration)
  * @param holder contains the holder of the option
  * @param option the option itself
  *
  * @return true if this option should be enabled in the build options page,
  * or false if it should be disabled (grayed out)
  */
  public boolean isOptionEnabled(
    IBuildObject configuration,
    IHoldsOptions holder,
    IOption option);

}

7.13 Defining a Dynamic Element Provider

Tool integrators may supply a dynamic element provider to dynamically provide the definitions that are otherwise specified in the buildDefinitions extension point.  To specify a dynamic element provider, your build definitions must define a dynamicElementProvider element as described in § 3.19.

7.14 Adding Custom Pages to the New Project Wizard

One aspect that toolchain developers have requested more flexibility in is the ability to customize the new project wizard.  Developers wish to be able to add custom pages to the wizard to facilitate such things as automatically setting launch properties for the project, generating configuration files for the project, and other various custom settings and behaviour.

Developers might wish that such customizations be toolchain specific, or possibly be global to all toolchains.  At the same time or separately, they may wish their pages to appear only when a project is of a certain nature (e.g. C vs. C++) or for certain project types (e.g. executable vs. library).

External interfaces are provided by a single extension point:

7.14.1 org.eclipse.cdt.managedbuilder.ui.newWizardPages

This extension point allows for the specification of pages to the New Managed C/C++ wizards.  Via this extension point, the developer may specify one or more wizard pages to add to the wizard, and optionally only add these pages if certain conditions on the project type, project toolchain, and project nature are met.  The developer may also specify a Java class which performs any operations pursuant to the state of the wizard when the user clicks Finish.

7.14.1.1 Schema

7.14.1.1.1 wizardPage Element

One or more instances of this element are required.  Each instance of this element defines an additional page which is added to the New Project wizard.  Pages are added after the default pages provided by MBS.  Pages are added in the order they are discovered.

Note that the IWizardPage interface allows a page to specify programmatically and dynamically at runtime what its previous and next pages are.  This element does not trump that behaviour, but rather just specifies the order in which the pages are added to the wizard (and hence the order in which the pages appear if they do not override the previous and next page methods).

For convenience, here is a UML class diagram of the IWizardPage interface.



Wizard pages as GUI elements by themselves are really not all that useful.  More than likely if someone is defining their own wizard pages it's because they need some additional operations to happen upon project creation in addition to the stock behaviour of creating a basic project, and they want to use their new wizard pages to provide a front end to these operations.

Note that during the display of the wizard page, and the user possibly entering information, no permanent changes should be executed, since the user can abort the creation of the new project at any time. For this reason, the actual changes indicated on the wizard pages should be executed once the user has completed the new project wizard: after the "Finish" button has been selected. User data can be saved in a storage area for any of these pages, and retrieved later when needed.

As such, along with a specification of the GUI wizard page, ISVs may specify a runnable operation that will be executed in the wizard's doRunEpilogue() method, after the new project creation is committed. These contributions will all be executed in the order that the wizard pages were added to the wizard.  Not all pages need have such a contribution however, as ISVs may need to perform all the operations associated with their pages as a group.  In cases such as this the ISV can define an operation for one of the pages and it can pull data from any of the other pages as required.

wizardPage Element Schema:

7.14.1.1.2 projectType element

This is an optional child element of wizardPage which specifies a projectType for which the additional pages should apply.  One instance of this element is provided per toolchain supported by the page.

If no projectType elements are specified, then it is assumed that the page potentially applies to all projectTypes, although it may still be excluded based on toolchain (§7.14.1.1.3) or project nature (§7.14.1.1.4).

projectType Element Schema:

7.14.1.1.3 toolchain Element

This is an optional child element of wizardPage which specifies a toolchain for which the additional pages should apply.  One instance of this element is provided per toolchain supported by the page.

If no toolchain elements are specified, then it is assumed that the page potentially applies to all toolchains, although it may still be excluded based on project type (§7.14.1.1.2) or project nature (§7.14.1.1.4)

toolchain Element Schema

7.14.1.1.4 nature Element

This optional child element of wizardPage specifies the project nature(s) for which the additional pages should apply.   One instance of this element is provided per nature supported.

This would for example allow one to add pages to the New Managed C Project wizard but not the New Managed C++ project wizard, or other hypothetical natures that might be supported by MBS in the future (e.g. someday there might be a Fortran nature).

If no natureID elements are specified, then it is assumed that the page potentially applies to all project natures, although it may still be excluded based on project type (§7.14.1.1.2) or toolchain (§7.14.1.1.3)

natureID element Schema:

7.14.2 High-Level Architecture

7.14.2.1 System Overview

The custom wizard pages subsystem in MBS is responsible for managing:

• Which pages exist in the system, and their associated attributes
• Whether pages should be shown in a given wizard based upon what options the user has selected in previous pages (i.e. project nature, toolchain, project type).
• What order pages are shown in as the user navigates the wizard
• What operations should be executed in association to the page during the wizard's doRunEpilogue() method.

The main entry point to the system is a central manager class called MBSCustomPageManager.  This class is responsible for managing classes which handle the aggregation of page data (MBSCustomPageData).

For convenience sake, an abstract base class for wizard pages exists (MBSCustomPage) which ISVs can subclass to implement the default behaviour of allowing the page manager to completely control the ordering of pages.

The following class diagram shows how these new classes fit into the existing wizard system in MBS in terms of class hierarchies and associations.

Figure 12: High level view of MBS wizard system

As you can see in Figure 12, there are two MBS wizards, one for C projects and one for C++. These wizards ultimately inherit some of their behaviour from the generic wizards provided by the CDT's core UI. There are several wizard pages that always appear in the MBS wizard, which allow the user to select the project name, project location, and MBS project type for their project. The wizards defer to the MBSCustomPageManager to handle any custom pages that might be present in the system.

7.14.3 Low-Level Architecture

Drilling down into the custom wizard page system itself, we see the following:

Figure 12: High level view of custom wizard system

The MBSCustomPageManager class is the main entry point to the system. It is responsible for loading all of the extensions which provide custom wizard pages, and storing that data for later use by the wizard. It keeps a list of records of these pages (MBSCustomPageData) which act as a repository for everything that needs to be known about the page, including what circumstances it should be shown under, and what actual IWizardPage should be shown when the page is displayed.

For convenience, there is an abstract base class (MBSCustomPage) which ISVs can subclass to get the most commonly desired behaviour from their pages. Most notably, the provided implementation contained in this class consults the MBSCustomPageManager to determine what wizard pages appear before and after the page, which is necessary to ensure that all custom pages in the system are displayed when they should be.

7.14.3.1 MBSCustomPageManager

This class is responsible for:

• Maintaining the set of custom pages as discovered by the wizard and allowing them to be referenced by string ID
• Managing the published data which pages wish to make available to other pages
• Managing the visibility and ordering of custom pages within the wizard as the user navigates between pages.

This class is a singleton. All non-constructor methods are static.

When the wizard is initialized, it makes a call to MBSCustomPageManager.loadExtensions(). This method looks for contributions to the org.eclipse.cdt.managedbuilder.ui.newWizardPages extension point.  The loaded data is used to instantiate and populate an MBSCustomPageData object for each page discovered.

As the user manipulates the wizard, each page can publish data they wish to export for use by other pages, or for use by the optional Runnable operation that may execute when the wizard pages are completed.   This is done via the addPageProperty() method, which allows for the storage of string data by string key, using the string ID of the page as a sort of namespace.  The data can be retrieved by other pages via the getPageProperty() method, and this is the standard way for pages to interface to each other.

Individual pages are expected to somehow consult the getNextPage() and getPreviousPage() methods of the manager when their own getNextPage() and getPreviousPage() methods are called by the wizard.  This allows the pages to properly navigate amongst each other while taking into account user choices such as project nature, toolchain, and project type.  It should be noted that the manager can only do so much as it fills the role of an advisor.  Custom pages are still theoretically free to ignore its existence, although this is strongly discouraged.

7.14.3.2 MBSCustomPageData

This class provides data aggregation capabilities for the page manager to store information on a custom wizard page.  On startup, the page manager loads all contributions to the newWizardPages extension point, and stores the loaded data in these records for later use. There is a nested class, ToolchainData, which is used to maintain information on each individual toolchain that a given custom page supports. The MBSCustomPage manager calls various methods on this class (e.g. MBSCustomPageData.shouldBeVisibleForNature()) to determine when a given page should be visible in the wizard.

7.14.3.3 MBSCustomPage

This abstract class provides a convenient, partial implementation of the IWizardPage interface.  This class provides implementations of the getNextPage() and getPreviousPage() methods which consult with the page manager to determine which pages are to be displayed.  If an ISV's custom pages do not subclass MBSCustomPage then their page implementation must be carefully coded to function properly while still respecting the rules laid out by the page manager.



7.14.4 Limitations

Currently there is no way for ISVs to intermingle their wizard pages amidst the ones defined in MBS, or amidst the ones created by other plugins in general.  In the future it might be possible to provide an extension point which would allow an ISV to customize this ordering for their product.

This would be problematic though as it would be possible for multiple ISVs to attempt to specify such an ordering within the same installation of Eclipse/CDT.

It would also be problematic as certain custom pages would rely on the selected project type or toolchain, and with a reordering mechanism, ISVs would have to be careful to not try to put such pages ahead of the page on which that data is selected.  If a developer were reordering pages that they themselves did not create, they would have to tread extremely carefully to properly manage these and other ordering constraints.

7.15 Defining Startup Behavior for Configuration Loading

Tool integrators may require that a plugin contain all the build configurations before projects are loaded. Use of this interface insures that a plugin will have access to build configurations before project inforamation is loaded in the workbench. Two methods can be used to access configuration information just after build definitions have been loaded and then again after the build definitions have been resolved. Added as enhancement to bug 123275.

public interface IManagedBuildDefinitionsStartup {

String BUILD_DEFINITION_STARTUP = "buildDefinitionStartup"; //$NON-NLS-1$
String CLASS_ATTRIBUTE = "class"; //$NON-NLS-1$

/**
* Any work you want to do on build definitions after they have been loaded but before they have been resolved.
*/
void buildDefsLoaded();

/**
* Any work you want to do on build definitions after they have been resolved.
*/
void buildDefsResolved();

}

Advanced Features

8.1 Converting CDT 2.0 Manifest Files

The CDT 2.1 Managed Build System (MBS) defined a new object model for tool integrators to use when integrating their tool definitions.  The CDT 3.0 model is upward compatible with the CDT 2.1 model with the exception of the ToolChain.scannerInfoCollector attribute.  CDT 2.0 manifest files continue to be supported, but it is recommended that integrators use the new model when possible.  New functionality that is added to MBS will be added to the new object model, and not necessarily to the old object model.

The figure below shows the CDT 2.0 object model.  The CDT 3.0 object model is shown earlier in the document.

Figure 12 CDT 2.0 Managed build model elements

Below are the detailed instructions for converting a manifest from the old model to the new model.

8.1.1 MBS Manifest Extension Point

The old object model defines the org.eclipse.cdt.managedbuilder.core.ManagedBuildInfo extension point.  The new model defines the org.eclipse.cdt.managedbuilder.core.buildDefinitions extension point.  Both old model and new model definitions can be defined in the same manifest file, but all of the identifiers (ids) assigned to both old and new model elements must be unique within MBS.  No two elements can have the same id no matter whether they originate in the same or different manifest files.

See the CDT 2.0 Gnu tool-chain definitions for an example of the old model (org.eclipse.cdt.managedbuilder.ui\plugin.xml).  See the CDT 2.1 Gnu tool-chain definitions for an example of the new model.

8.1.2 MBS 2.0 Target Element

The new model does not define a target element.  The information defined in a target element in a 2.0 manifest file has been split up into the ProjectType, ToolChain, Builder, and TargetPlatform elements in the new model.

The Target attributes name, id, isTest and isAbstract should be transferred to a new ProjectType element in the new model.  The id assigned to the Target must be transferred to the new ProjectType element without change.  Otherwise, projects created using your integration with CDT 1.2 or 2.0.x will not be able to be converted.  There is no tool integrator intervention into the conversion process yet, but this is a high priority for CDT 3.0.

8.1.3 MBS 2.0 Configuration Element

The Configuration children of the Target element are made Configuration children of the new ProjectType element.  The Configuration name and  id attributes should be transferred with the Configuration.  The id assigned to the Configuration must remain unchanged in order to support the conversion of old model project files.  The Target attributes artifactName, cleanCommand and errorParsers attributes should be transferred to the Configuration element.  The Target defaultExtension attribute should be transferred to the Configuration element as the artifactExtension attribute (Note the name change).

A new ToolChain element should be created as the child of each Configuration element.  The name and id of the ToolChain are not dependent upon the name of any of the old model objects.  However, if you allow users to create CDT 2.1 projects using your CDT 2.0 manifest file, then the id of your new ToolChain must be the parent Configuration id, appended with “.toolchain”.  The Target isAbstract, osList, archList and scannerInfoCollector attributes are transferred to the ToolChain element.

A new Builder element can be created as the child of each ToolChain element.  The name and id of the Builder are not dependent upon the name of any of the old model elements.  However, if you allow users to create CDT 2.1 projects using your CDT 2.0 manifest file, then the id of your new Builder must be the parent Configuration id, appended with “.builder”.  The target isAbstract attribute is transferred to the Builder element.   The target makeCommand attribute should be transferred to the Builder element as the command attribute (Note the name change).  The target makeArguments attribute should be transferred to the Builder element as the arguments attribute (Note the name change).  The target makefileGenerator attribute should be transferred to the Builder element as the buildfileGenerator attribute (Note the name change).

A new TargetPlatform element can be created as the child of each ToolChain element.  The name and id of the TargetPlatform are not dependent upon the name of any of the old model elements.  However, if you allow users to create CDT 2.1 projects using your CDT 2.0 manifest file, then the id of your new TargetPlatform must be the parent Configuration id, appended with “.targetplatform”.  The target isAbstract and binaryParser attributes are transferred to the TargetPlatform element.  The TargetPlatform element contains osList and archList attributes that specify the architecture(s) and operating system(s) on which the Configuration’s build artifact(s) execute.  You can transfer the Target osList and archList attributes if appropriate.

8.1.4 MBS 2.0 Tool Element

The old model allows Tools to be defined at the top level scope in the manifest file.  This is still true in the new model.  In addition, the new model allows Configuration, ToolChain, Builder and TargetPlatform elements to be defined at the top level scope in the manifest file.

In the old model, Tool elements can also be specified as the children of Target elements.  In the new model, Tool elements are children of ToolChain elements.  Old model Tool elements need to be added as the child of each ToolChain that uses the Tool.  All of the old model Tool attributes are supported by the new model.

The id assigned to the Tool must remain unchanged in order to support the conversion of old model project files.  The outputs attribute no longer defaults to an empty string.  If your Tool produces files by default with no extension, you must specify ‘outputs=””’ in the definition of the Tool or one of its ancestors (superClass).

8.1.5 MBS 2.0 ToolReference Element

The new model does not define a ToolReference element.  Instead, a Tool element can specify the superClass attribute in order to provide the same functionality.  That is, specifying a Tool that inherits attributes from another Tool and can override one or more attributes.

The old model uses ToolReferences in two ways.  They can be specified as the child of a Configuration element.  In this case, the ToolReference should be converted a Tool element child of the Configuration’s ToolChain, transferring the value of the id attribute to the Tool superClass attribute.

A ToolReference can also be specified as the child of a Target element.  In this case, the ToolReference applies to all of the Configuration children of the Target.  These ToolReference elements need to be converted to Tool elements and added as the child of each ToolChain that uses the Tool.

8.1.6 MBS 2.0 Option Element

All of the old model Option attributes are supported by the new model.

The id assigned to the Option must remain unchanged in order to support the conversion of old model project files.

8.1.7 MBS 2.0 OptionReference Element

The new model does not define an OptionReference element.  Instead, an Option element can specify the superClass attribute in order to provide the same functionality.  That is, specifying an Option that inherits attributes from another Option and can override one or more attributes.

All OptionReference elements should be converted to Option elements, transferring the value of the id attribute to the Option superClass attribute.

8.1.8 MBS 2.0 OptionCategory, EnumeratedOptionValue, ListOptionValue Elements

There are no changes to these elements.

8.1.9 MBS 2.0 DynamicElementProvider Element

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.

8.2 Supporting Multiple Versions of a Tool-chain

This section will be provided in a future version of the document.  For now, refer to the Tool-chain Multi-version Support design document in bugzilla #89872.