Managed Build System Extensibility Document

Migrating your tool-chain integration to CDT 4.0 This document describes steps needed to be done to migrate the existing tool-chain integrations to the CDT 4.0 |

Authors
Mikhail Sennikovsky
Revision Date
06/21/07 - Version 4.0
Change History
4.0 - Document Creation

Table of Contents
1 Scope of the document
2 Migration Steps

1 Scope of the document

The document describes steps needed to be done to migrate the existing tool-chain integrations to the CDT 4.0.

The documents outlines the main steps needed for migration without focusing on details of the new Build System functionality. For more detail on the new functionality presented in the CDT 4.0 please refer to the "What's New in the CDT Build System" document.

2 Migration Steps

1. The Build System now supports the per-folder settings. The new interface org.eclipse.cdt.managedbuilder.core.IFolderInfo is presented to represent the folder-specific settings. Thus the implementers of the following interfaces should now expect to receive the IFolderInfo in addition to the IFileInfo (IResourceConfiguration) and IConfiguration as the "IBuildObject configuration" argument:

   - org.eclipse.cdt.managedbuilder.core.IOptionApplicability

   - org.eclipse.cdt.managedbuilder.core.IManagedOptionValueHandler

   - org.eclipse.cdt.managedbuilder.makegen.IManagedDependencyGenerator2

2. The new New Project wizard now operates with tool-chains allowing to select the tool-chain(s) to be used on project creation. Also the "Tool-chain editor" functionality now allows to modify/change the tool-chain of the already created project. Thus it is required that all toolChain/tool/builder build definitions representing different tool-chain/tool/builder must have different names as well as toolChain/tool/builder build definitions representing one and the same tool-chain/tool/builder must have identical names.

   Example: to illustrate the above requirement here is how this is handled in the gnu tool-chain definitions:

   The gnu plug-in contains the gcc linker tool on Linux is defined as

   <tool
   natureFilter="cnature"
   name="%ToolName.linker.gnu.c"
   outputFlag="-o"
   command="gcc"
   id="cdt.managedbuild.tool.gnu.c.linker"

   ...

   At the same time the gnu tool-chain definitions refers to the gcc linker by defining a new tool as a super-class of the "cdt.managedbuild.tool.gnu.c.linker" tool

   <tool
   id="cdt.managedbuild.tool.gnu.c.linker.base"
   superClass="cdt.managedbuild.tool.gnu.c.linker">

   ...

   Both tool definitions listed above are actually treated as two different tools by the Build System, while both of them refer to one and the same "gcc" executable. To make the build system aware that both tool definitions refer to one and the same tool/executable it is required that both tool definitions specify one and the same name. In the above sample the tool of id="cdt.managedbuild.tool.gnu.c.linker.base" does not specify any name thus making the name to be inherited from the super-class tool, so both tools have the same name.

   On the other hand the cygwin gcc linker is defined as

   <tool
   id="cdt.managedbuild.tool.gnu.c.linker.cygwin"
   name="%ToolName.linker.cygwin.gnu.c"
   superClass="cdt.managedbuild.tool.gnu.c.linker">
   ...

   although the tool definitions is defined as a super-class of the linux gcc linker, it refers to the different tool(executable) than the Linux linker definition. The cygwin linker definition specifies the name="%ToolName.linker.cygwin.gnu.c" that differs from the one defined by the Linux gcc linker.

3. The CDT Build System now support the Custom Configuration Builds. For Managed builds (makefiles are generated automatically) this functionality works only in case the buildfile generator implements the org.eclipse.cdt.managedbuilder.makegen.IManagedBuilderMakefileGenerator2. This interface extends the old IManagedBuilderMakefileGenerator by defining a new initialize() method which accepts IConfiguration and IBuilder rather than IManagedBuildInfo thus removing an assumption that only active configuration can be used for building.

   The default GnuMakefileGenerator supplied with the CDT now implements this interface, so in case the builder is using this default implementation, no changes are needed.

4. There are some modifications in Eclipse Platform's org.eclipse.core.runtime.Path class behavior that might affect some of the current MBS integrations, namely

   The changes are related to the way the dot ("./") prefix are treated by the path constructors, i.e. with Eclipse 3.2.x the Path(String) constructor and also Path.from*String() methods generate the “./some/path” path given a “./some/path” string
   With Eclipse 3.3 the above generate “some/path” for the same string (note the “./” stripped)
   Historically the Managed Build System contains some logic that behaves differently depending on whether the “./” is prefixed or not, e.g. org.eclipse.cdt.managedbuilder.core.IManagedOutputNameProvider is expected to return a one-segment path to force the path to be prepended by the build output [sub]directory path, so returning “./foo.o” and “foo.o” would have different meaning and behavior, i.e. the “./foo.o” would force the foo.o to be located in the root output directory, while “foo.o” would result in putting the foo.o in the output_dir/source/relative/directory/foo.o
   There was some code in MBS relying on the 3.2 Path behavior, e.g. something like path = Path.fromOSString(“./” + name + extension); Stripping the “./” in eclipse 3.3 resulted in incorrect output calculation for the case the tool wanted to force the output to be located in the build output root directory for.
   If your tool-chain needs to specify the "./" prefix to the paths, they could do it by using the following construction

   path = new Path(“./”).append(fileName);

   instead of

   path = new Path("./" + fileName);

5. Integrating with the new New Project Wizard

   If no modifications are made the old-style project types should be presented as separate entries in the "Project Types" list of the wizard. In case a tool-integrator is willing to use general project type entries, he/she should refer to the New Project Wizard description for detail.