From 55d7f38a852d6aad6b72aaac1c650f9e28bae7eb Mon Sep 17 00:00:00 2001 From: Leo Treggiari Date: Thu, 28 Jul 2005 03:50:53 +0000 Subject: [PATCH] Update for MBS Extensibility Guide --- .../Managed_Build_Extensibility.html | 158 +++++++++++++----- 1 file changed, 113 insertions(+), 45 deletions(-) diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html index 7fe0c649a0b..cfc59fe7b02 100644 --- a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html @@ -184,6 +184,7 @@ managed build system and how to extend it.
8 Advanced Features
8.1 Converting CDT 2.0 Manifest Files
+
8.2 Supporting Multiple Versions of a Tool-chain

1 Introduction

@@ -194,10 +195,27 @@ 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:

+

1.1 Who Needs This Information

The information in this document describes the design of the managed -build system (MBS) and discusses how to add new tool-chain definitions to it +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 @@ -209,7 +227,7 @@ 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, and 7 as they are primarily concerned +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, then you have to @@ -278,13 +296,12 @@ defined by the user, but others will be built into the tools themselves so the user will be unaware of them. The CDT parser described in the previous section needs to know about the entire set to properly parse source files. It is the -responsibility of the MBS to answer both the user-supplied and built-in -paths and symbols to the parser. Of the two, the user-supplied include -paths and defines are trivial as they are entered by the user through -the UI. The built-in compiler settings on the other hand, are quite a -bit harder to decipher and the solution will vary from tool to -tool. A discussion of the possible solutions is provided in § -6.9.3.
+responsibility of the MBS to answer both the user-supplied and built-in paths +and symbols to the parser. Of the two, the user-supplied include paths and +defines are trivial as they are entered by the user through the UI. The built-in +compiler settings on the other hand, are quite a bit harder to decipher and the +solution will vary from tool to tool. A discussion of the possible solutions is +provided in § 6.12.

1.2.4 Tool Definitions and Settings Storage

A key feature of the managed build system is that it is extensible. Tool integrators @@ -351,7 +368,7 @@ contains the following primary objects: 

An ordered set of tools used to transform the project resources into the final output (build - artifact) of the project.  A tool integrator can provide a family + artifacts) of the project.  A tool integrator can provide a family of tool-chains that support different host/target platform combinations, and different versions of the tool-chain. @@ -471,7 +488,7 @@ and modify the following attributes of the tool-chain:

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 resources that are created by the + dependencies of the step, and the output files that are created by the step.
  • The mapping of @@ -621,7 +638,7 @@ 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 -the managed build object model.

    +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 @@ -845,7 +862,12 @@ UI.

    style="border-style: none solid solid none; border-width: medium 1pt 1pt medium; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" valign="top" height="49"> The name of a class that implements the IConfigurationNameProvider - interface in order to provide a default name for a configuration. + interface in order to provide a default name for a configuration.  + The configuration names in a user's project must be unique.  A + projectType can contain configuration children with the same name.  + In this case, a configurationNameProvider must be specified to make the + names unique before they are displayed to the user in the New Project + and New Configuration dialog boxes. @@ -952,8 +974,13 @@ 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.  -

    +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

    style="border-style: none solid solid none; border-width: medium 1pt 1pt medium; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" valign="top"> Specifies the description of the configuration that will be displayed to - the user while creating a project and managing configurations. + the user while creating a project and managing configurations.  The + description is only displayed in the UI - it is not considered to be + part of the configuration name.
    @@ -1145,7 +1174,7 @@ track of this specific configuration.

    3.5 Tool Chain

    The toolChain element represents -the tool chain in the user model.  It is a tool-integrator-defined, ordered set +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 @@ -1160,20 +1189,19 @@ of type builder.  This defines the “build” or “make” drive the transformation of the inputs into outputs.

    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 the CDT on Windows. You can +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 may be associated -with a scanner configuration profile that defines how to discover built-in compiler defines and -includes search paths.

    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, then MBS uses the file extension +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???

    A tool-chain may define a configuration level environment variable provider in the configurationEnvironmentSupplier attribute.  See § 7.6 for additional information.
    @@ -1183,6 +1211,9 @@ 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

    @@ -1259,7 +1290,7 @@ the schema table below.

    A semi-colon separated - list of the identifiers  of the tools that can be used to create the + list of the identifiers of the tools that can be used to create the build artifact.  A list is required, for example, when there are 2 versions of a target tool that are used with different project natures. -   +

    The name of a class that implements the + + IManagedIsToolChainSupported interface.  This provides 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 + isToolChainSupported callback 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. @@ -1435,7 +1476,7 @@ the schema table below.

    DiscoveryProfileId Specifies an id of scanner configuration discovery profile for + valign="top">Specifies the id of a scanner configuration discovery profile for gathering the built-in compiler settings for a toolchain.

    -

    +

    6.1 Setting up your Environment

    Tool integrations are specified by extending the buildDefinitions @@ -4430,7 +4471,7 @@ Feature Details and check that "Eclipse C/C++ Development Tools 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

    @@ -4464,7 +4505,7 @@ button.
    • style="font-weight: bold;">Plug-in Development perspective, answer Yes. -

    +

    6.3 Creating the Extension

    You have installed the CDT source and @@ -4505,7 +4546,7 @@ 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 @@ -4529,7 +4570,7 @@ Executable for our projectType. to false.
    -

    +

    6.5 Adding a Configuration

    We have now added a basic project-type definition. We now want to define a @@ -4560,7 +4601,8 @@ following list org.eclipse.cdt.core.MakeErrorParser;org.eclipse.cdt.core.G org.eclipse.cdt.core.GASErrorParser;org.eclipse.cdt.core.VCErrorParser

    -6.6 Adding a ToolChain

    + +6.6 Adding a ToolChain

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

    @@ -4587,7 +4629,8 @@ you are running on a version of Solaris, or other if none of the above apply.

    -6.7 Adding a Builder

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

    @@ -4607,7 +4650,7 @@ example.toolchain.builder. style="font-weight: bold;">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 @@ -4636,7 +4679,8 @@ are running this tutorial on Linux or Solaris, enter the value org.eclipse If you are running the tutorial on Windows, enter the value org.eclipse.cdt.core.PE.

    -6.9 Adding a Tool

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

    @@ -4673,7 +4717,7 @@ real tool, so just enter ccc as the value for the command property. -

    +

    6.10 Testing the ProjectType

    We have now defined enough information to create a project for our @@ -4735,7 +4779,7 @@ 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.11 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 @@ -4810,14 +4854,14 @@ debugging your run-time workbench. You should see something like this.

    title="" alt="Tutorial project property page">

    Figure 9 MBS property page with tool, category, and options
    -

    +

    6.12 Taking the Next Step

    The purpose of the tutorial you just followed was to become familiar with the steps involved in creating a simple tool-chain and to get a feeling for how the choices you make in the specification of options affect the UI. In this section, we will discuss some additional points that you need to consider before specifying your own tool integration.

    -

    6.12.1 Adding More +

    6.12.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 @@ -4829,7 +4873,7 @@ compiler and “something else” is usually sufficient, but you may hav to define additional tools if your tool-chain requires intermediate build steps to function properly.

    -

    6.12.2 Defined +

    6.12.2 Defined Symbols and Header File Search Paths

    There are elements of the CDT core that require build information @@ -4847,7 +4891,7 @@ specification has options of type “includePaths” and “definedS The build model will pay special attention to these options and answer them to the appropriate clients in the CDT core without any further intervention on your part.

    -

    6.12.3 Built-in +

    6.12.3 Built-in Symbols and Search Paths

    We have automated the discovery of paths and symbols for standard GCC compilers that are building targets for the platform they are @@ -4870,7 +4914,7 @@ for the user to edit these values if something changes is to directly edit the plug-in manifest where the extension is specified. Please refer to § 3.11 for more details on specifying list option values. -

    6.12.4 User-Specified +

    6.12.4 User-Specified Libraries and Object Modules

    Similarly, a user may want to specify external libraries to link @@ -4880,7 +4924,7 @@ special attention to an option containing libraries so that when the build file generator requests them, it can answer a valid list. Flag the option value type as “libs” for external libraries or “userObjs” for object modules.

    -

    6.12.5 ProjectType and Other +

    6.12.5 ProjectType and Other Element Hierarchies

    One area of the build model that the tutorial does not touch on @@ -4905,7 +4949,7 @@ it is now possible to declare a configuration, tool-chain, tool, builder and tar is possible to declare a complete set of elements once, and use superClass references to those elements inside many projectTypes.

    -

    6.12.6 Publishing +

    6.12.6 Publishing your Plug-in

    The subject of packaging Eclipse plug-ins is well covered in the Platform Plug-in Developer Guide. @@ -5126,7 +5170,30 @@ default MBS implementation does not modify any of the command line parts.  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

    +

    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 @@ -5929,5 +5996,6 @@ Elements

    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

    \ No newline at end of file