Extending the Eclipse CDT Managed Build System

Example Tool-chain: Source Code Pretty-Printer

To explain the concepts behind creating a tool-chain, let's look at an example.

Say you have a large amount of source code that you wish to code review with your peers. You want to format the code nicely to make it easier for everyone to inspect. You'd also like to put it into one PDF file, both to save on trees and to avoid the confusion created by everyone printing out the code in a different format. With a PDF, all the reviewers can see an identical representation of the artifacts under inspection.

After giving the problem some thought, you realize that since you're running a UNIX-like OS shell (for instance, under Cygwin on Windows) you can use the GNU utility enscript to pretty-print the source files into a PostScript file and then use another GPL'd utility, ps2pdf, to convert the PostScript file into PDF format.

Unfortunately, you know nothing about shell scripting or batch files, but being an expert on using the MBS, you realize that you can create a set of build definitions that will process all of your files, with relatively little effort.

To begin defining the tool-chain, you must have the Eclipse SDK 3.1 and the CDT SDK Feature 3.1.0 installed. Open the Plug-in Development perspective and create a new plug-in:

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 "ddj.example.prettyprinter.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 ddj.example.prettyprinter.toolchain by default. The plug-in will not be directly adding items to the Eclipse UI, so de-select the This plug-in will make contributions to the UI checkbox and click on the Finish button.

You have created the plug-in. You will now define your extension to the org.eclipse.cdt.managedbuilder.core.buildDefintions extension point:

1. In the MANIFEST.MF file for the plug-in, double click on the ddj.example.prettyprinter.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. Now you must add a dependency between the project and the org.eclipse.cdt.managedbuilder.core plug-in where the MBS tool definition extension point is defined. To do this, click on the Dependencies tab located along the bottom of the manifest editor, then Click the Add... button located beside the Required Plug-Ins list. Select org.eclipse.cdt.managedbuilder.core from the list and 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 checkbox 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 "ddj.example.example.buildDefinitions" as the ID for the extension, and "Example Enscript Tool Chain" as the Name.

The org.eclipse.cdt.managedbuilder.core.buildDefintions extension point uses the object model in Figure 1. The top element in the model is projectType, which serves as a template for the CDT projects that a user will create. CDT uses the information supplied in all projectTypes when populating the New Project dialog box in the Managed Make Project wizards.

To add the ProjectType for the new tool-chain:

1. Right click on the org.eclipse.cdt.managedbuilder.core.buildDefintions extension in the All Extensions list. Select New from the context menu, and then select projectType.
2. Fill out the name field to name the project type as "Pretty Printer". You can leave the automatically generated ID as is or change it to suit your tastes.

To be useful, a project type must contain at least one configuration to build. A configuration consists of a tool-chain that incorporates one or more tools. Typically, a project type contains more than one configuration (for instance, a Debug configuration versus a Release version that uses the same tools but changes some of the optimization and debug options). In this case, however, you need only one configuration, so you'll just create a "default" configuration:

1. Right click on the projectType you just created and select New, then select configuration.
2. Name the configuration "Default".
3. Set the artifact extension to "pdf". This tells the MBS that the final result of running your tool-chain will be a .pdf file.
4. Set the cleanCommand to "rm -f". This tells MBS how to remove any intermediate files or build artifacts in order to clean your project.
5. Fill in the description as "default configuration".