CDT 2.0 Managed Build System SRS This document describes the proposed work items for the managed build system for the CDT 2.0 release.

Table of Contents

1 Introduction

This is a partial SRS for the managed build system for the CDT 2.0 release. A long list of requirements was compiled based on feedback we received from a number of end users. However, there were simply too many suggestions for us to implement in the time we have allocated to this release. This document describes the requirements that we feel are important to the end-user experience and that should be considered for the next release of the managed build system. That said, the requirements that are not on the short list are all valid, and if some other partner wishes to contribute the work, then they can also be considered for the release.

1.1 Terms

This section defines the terms commonly used in this document.

2 Requirements

While there is a large list of requirements for the managed build system, the following items have been identified as the key work items for IBM to commit to. The priority of the requirements will determine which features get tackled first, but the order of the requirements in this list does not imply any relative importance within a given priority.

4 Design Discussion

This section contains more detail on the requirements listed in section 2. Certain requirements such as bug fixing and providing an implementation for the Visual Studio tool chain are self-explanatory and are not discussed in this section.

4.1 Modifying the Tool Command (C1)

Users have said that they would like to be able to change the command used to invoke certain tools defined in a tool chain. The example that is often used is replacing the linker command with Purify to instrument a build goal, as in purify gcc. Tools are defined in a plugin manifest and part of that definition is the command to invoke the tool on the host platform. When an individual user creates a new project, the settings in the manifest are used unless they are overridden by the user. However, the user can only modify the options associated with a tool, not the actual command. The only way for a user to specify a variant command for a tool is to edit the plugin manifest itself. This is a barrier to the average user, so the proposal is to any tool invocation to be changed at the project level.

The change is scoped to the project; it will not effect the manifest. This is important to understand because if the user does not edit the manifest manually, the next time a project is created they will have to override the tool command again. Project creation is not a high-frequency activity, so this should not be a huge problem. If the user wants to permanently override a tool command for a project they can do so for an existing configuration. It is also possible to clone existing configurations, so to stick with our example, a user could clone one of the default configurations and override the command for the linker to produce an instrumented executable with Purify.

For teams, one would expect the initial setup of a project would be the responsibility of a build team. They would follow the same workflow as a single developer. The project, tool settings, and default configurations including the new "purify" configuration, would all be shared through their CM system.

4.2 Setting Build Options Simultaneously (C2)

Users have pointed out that it is tedious and error prone to set options individually for each configuration of a given target. The build system should supply an 'all' configuration by default where any changes to the options would be applied to all defined configurations. The build settings page should also support cutting and pasting option values between configurations.

Consider the following case. The user has set (overridden from the default) the value of option A in configuration 1 but not configuration 2. At some later time, the user switches to the 'all' configuration. When the user edits option A, they change the setting in configuration 1 and override the default value in configuration 2 simultaneously.

Another case concerns the behaviour of the system when the 'Reset to Defaults' command is received and the 'all' configuration is selected. The default option settings for every configuration will be reset to the defaults defined in the manifest. We could prompt the user to make sure this is what they want to do, since hitting this button with the 'all' configuration selected may have major consequences for the project settings.

Cutting and pasting shall only be enabled on widgets that logically support it. For example, cutting and pasting a radio button selection makes no sense.

4.3 Converting a Managed to a Standard Build Project (C3)

Some users have mentioned that they would like to use the managed build system to create the project makefiles, then manage those makefiles manually after that. The workflow would be the user creates a managed project. The user adds all of the relevant classes and files to that project and the CDT generates a set of makefiles to build the project. At some point the user decides that they want to manage the makefile themselves and turn off makefile generation. Every new file that is added to the project would have to be manually added to the list of source files in the makefile, all of its dependencies captured, as would any custom build commands. The user could turn makefile generation back on, but the makefile generator would override the manual changes they made.

To support this, we shall supply a managed-to-standard conversion wizard. The include paths and defined symbols will be transferred, but all other build settings will be lost.

4.4 Refactor the Current Default Manifest (C4)

The current default manifest that defines the Gnu tool chain is bulky because options are duplicated for each tool on each host. The default tool chain definition should be made more compact by better defining inheritance of tools and options. This will make it easier to correct problems and maintain the definitions going forward.

4.5 Replace Current Default Targets with a "Gnu" Target (C5)

The current set of targets in the default manifest do not differ significantly in any way from one another. In fact, for most host platforms the Gnu tool chain is invoked the same way with the same command line options. If we refactor the default manifest, as per the C4 requirement, then a user would really only have to select the type of build goal and the tool chain they want to use to build it. We would then replace the current set of targets, such as "Cygwin Executable" with "Gnu Executable" or "Executable built with Gnu". This will make it easier to port the managed build system to other host platforms.

4.6 Automatically Update Build Information for Inter-project Dependencies (C6)

It is possible to specify that a project references other projects in the workspace. For the CDT, this has three important consequences for the build system. The first is that the build goal of the referencing project has a dependency on the build goals of the referenced projects, so the build system has to insure that the referenced project is built before the referencing project. The second is that the makefile for the referencing project must properly invoke the tools needed to produce the build goal. For example, if the referenced project builds a library, then the linker needs to know what the library name is and where it can be located, and the compiler will likely need to know the path to the include file that defines the library interface. Finally, this information needs to be captured and stored in the build system so that clients like the parser can find out about it.

The use case begins when the user defines an inter-project dependency between two projects in the workspace. The referencing project must be a managed project. If the referenced project is a managed project, the referencing project can query it for the build goal name and location. The include file search path will also be updated. This information will be stored by the build model.

If the referenced project is not managed, the build system will not be able to automatically update the information for the referencing project.

4.7 Target Definitions Contain Reasonable Default Build Settings (C7)

The user creates a new project with a build goal based on one or more execution targets. The user builds the project. The project builds correctly with no input from the user.

4.8 Add New Configurations to a Project by Cloning an Existing Configuration (C8)

In the current version of the managed make project, a user can add a new configuration to a project based on a configuration defined in the plugin manifest. In CDT 2.0, the user shall also be able to clone an existing configuration so they do not have to recreate all the includes paths, symbols, and library settings.

4.9 The Debug Configuration Should be Default (C9)

For any new project created from a default tool chain, the debug configuration shall be the default. That is, when the user creates a project or opens the property page, the debug configuration shall appear as the first selection in any widget.

4.10 Remove Gnu Make Extensions from Generated Makefiles (C10)

The current version of the managed build system relies on the pattern substitution extension of Gnu make to generate a more compact makefile. For users unwilling or unable to use the Gnu version of make, this is a problem. The makefile generator shall be modified so that it no longer outputs a makefile that uses this extension. The generated makefile will be less compact.

4.11 New Project Wizard Should Show All Targets (C13)

In the CDT 1.2, the New project wizard only displays the targets that define tool chains hosted on the platform that the user is running Eclipse on. This is too restrictive, since a user may be running on one platform and decide to create a project for a target that has tools hosted on another host platform. Obviously, the user will not be able to build the new project on their host platform, but they may intend to share it through their CM system with other users, or they may intend to copy the files immediately prior to building.

When the user runs the New project wizard, they will be presented with a list of all defined targets. The list will either be sorted so that the targets with tools on the host platform appear first, or there will be a way for users to filter out targets that are not available on the host platform.

4.12 Changing a Project's Build Goal (C15)

The user that wants to change the build goal type for a project, for example from an executable to a library. Currently, they have to create a new project with a different name, copy and paste all the source files into the new project, delete the original project, and rename the new project to the original. While this is a low-frequency activity, and one that is not typically supported by other IDEs, we should be able to simplify the process. The question is the degree of automation that we want to provide.

The lowest level of support is to create a conversion wizard which prompts the user to select the project build type and tool chain, then simply overrides all of the existing build settings for the project based on the defaults in the manifest. The settings for the original project could be stored in case the user wants to switch back at some point, but this has some technical issues associated with storage and reconciliation should the manifest definition change before the user switches back.

A more sophisticated wizard would attempt to transfer tool settings that are common to both build goal types. The simplest case would be switching build goal types but keeping the tool chain the same. For example, a library and an executable are built with exactly the same Gnu compiler, and there are few options that are unique to one type and not the other. This is not the case if the tool chains are different. Simply, the challenge is determining what tools and options the two types have in common.

10 References