diff options
author | Leo Treggiari | 2005-07-21 21:17:12 +0000 |
---|---|---|
committer | Leo Treggiari | 2005-07-21 21:17:12 +0000 |
commit | b76d3ca6ffc13e4c4cc6a0d9e75cef6ea9b5be92 (patch) | |
tree | 22c4115a26b63ea02896fd9409f6db44f1c5e96a /doc/org.eclipse.cdt.doc.isv/guide | |
parent | 459ee196996300abd23d77dad4d8711bfc22c4b4 (diff) | |
download | org.eclipse.cdt-b76d3ca6ffc13e4c4cc6a0d9e75cef6ea9b5be92.tar.gz org.eclipse.cdt-b76d3ca6ffc13e4c4cc6a0d9e75cef6ea9b5be92.tar.xz org.eclipse.cdt-b76d3ca6ffc13e4c4cc6a0d9e75cef6ea9b5be92.zip |
Create initial MBS Extensility document for CDT 3.0 in ISV doc area - more to come
Diffstat (limited to 'doc/org.eclipse.cdt.doc.isv/guide')
22 files changed, 5664 insertions, 0 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 new file mode 100644 index 00000000000..eb47eaccf59 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html @@ -0,0 +1,5664 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns="http://www.w3.org/TR/REC-html40"> +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1"> + <meta name="GENERATOR" content="Microsoft FrontPage 6.0"> + <meta http-equiv="Content-Style-Type" content="text/css"> + + <title>Managed Build System Extensibility Document</title> + <link rel="stylesheet" + href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/cdt-home/cdt.css?cvsroot=Tools_Project" + type="text/css"> + <link rel="stylesheet" href="cdt.css" type="text/css"> + <style> +<!-- +h3 + {margin-top:12.0pt; + margin-right:0in; + margin-bottom:3.0pt; + margin-left:0in; + page-break-after:avoid; + font-size:13.0pt; + font-family:Arial} +--> + </style> + <!--[if !mso]> + <style>h2 + {margin-top:12.0pt; + margin-right:0in; + margin-bottom:3.0pt; + margin-left:0in; + page-break-after:avoid; + font-size:14.0pt; + font-family:Arial; + font-style:italic} +table.MsoTableGrid + {border:1.0pt solid windowtext; + font-size:10.0pt; + font-family:"Times New Roman"; + } + li.MsoNormal + {mso-style-parent:""; + margin-bottom:.0001pt; + font-size:12.0pt; + font-family:"Times New Roman"; + margin-left:0in; margin-right:0in; margin-top:0in} + h4 + {margin-top:12.0pt; + margin-right:0in; + margin-bottom:3.0pt; + margin-left:.6in; + text-indent:-.6in; + page-break-after:avoid; + tab-stops:list .6in; + font-size:12.0pt; + font-family:"Times New Roman"; + } + table.MsoNormalTable + {mso-style-parent:""; + font-size:10.0pt; + font-family:"Times New Roman"; + } +</style> + <![endif]--> +</head> +<body> +<!-- Document Header --> +<table border="0" cellpadding="2" width="100%"> + <tbody> + <tr> + <td align="left" width="72%"><font class="indextop">Managed Build +System Extensibility Document</font><br> + <font class="indexsub">This document describes the design of the +managed build system and how to extend it.</font></td> + <td width="28%"><img src="http://dev.eclipse.org/images/Idea.jpg" + alt="" height="86" width="120"></td> + </tr> + </tbody> +</table> +<table> + <tr> + <td width="50%" rowspan="2">Authors</td> + <td width="50%"> <a href="mailto:sevoy@ca.ibm.com">Sean Evoy</a></td> + </tr> + <tr> + <td width="50%"><a href="mailto:leo.treggiari@intel.com">Leo Treggiari</a></td> + </tr> + <tr> + <td width="50%" rowspan="4">Revision Date</td> + <td width="50%">10/21/2003 - Version: 0.1.0</td> + </tr> + <tr> + <td width="50%">09/10/2004 - Version: 2.0.0</td> + </tr> + <tr> + <td width="50%">11/08/2004 - Version: 2.1.0</td> + </tr> + <tr> + <td width="50%">7/22/2005 - Version 3.0.0</td> + </tr> + <tr> + <td width="50%" rowspan="4">Change History</td> + <td width="50%">0.1.0 - Document Creation</td> + </tr> + <tr> + <td width="50%">2.0.0 - Updated for CDT 2.0</td> + </tr> + <tr> + <td width="50%">2.1.0 - Updated for CDT 2.1</td> + </tr> + <tr> + <td width="50%">3.0 - Updated for CDT 3.0</td> + </tr> +</table> +<br> +<!-- End of Document Header --><!-- Table of Contents --> +<div class="section">Table of Contents</div> +<br> +<div class="indent"><a href="#_TocSectionIntro">1 Introduction</a> +<div class="indent"><a href="#_TocSectionIntro_1">1.1 Who Needs This Information</a></div> +<div class="indent"><a href="#_TocSectionIntro_2">1.2 Managed Build System Overview</a></div> +<div class="indent"><a href="#_TocSectionIntro_3">1.3 The Standard Build System</a></div> +</div> +<div class="indent"><a href="#_TocSectionUIModel">2 User Model</a> +<div class="indent"><a href="#_TocSectionUIModel_1">2.1 User Scenarios</a></div> +</div> +<div class="indent"><a href="#_TocSectionGrammar">3 Build Model Grammar Elements</a> +<div class="indent"><a href="#_TocSectionGrammar_1">3.1 Model</a></div> +<div class="indent"><a href="#_TocSectionGrammar_2">3.2 Project Type</a></div> +<div class="indent"><a href="#_TocSectionGrammar_3">3.3 Managed Project</a></div> +<div class="indent"><a href="#_TocSectionGrammar_4">3.4 Configuration</a></div> +<div class="indent"><a href="#_TocSectionGrammar_5">3.5 Tool Chain</a></div> +<div class="indent"><a href="#_TocSectionGrammar_6">3.6 Builder</a></div> +<div class="indent"><a href="#_TocSectionGrammar_7">3.7 Target Platform</a></div> +<div class="indent"><a href="#_TocSectionGrammar_8">3.8 Tool</a></div> +<div class="indent"><a href="#_TocSectionGrammar_9">3.9 InputType</a></div> +<div class="indent"><a href="#_TocSectionGrammar_10">3.10 AdditionalInput </a></div> +<div class="indent"><a href="#_TocSectionGrammar_11">3.11 OutputType</a></div> +<div class="indent"><a href="#_TocSectionGrammar_12">3.13 Option Category</a></div> +<div class="indent"><a href="#_TocSectionGrammar_13">3.13 Option</a></div> +<div class="indent"><a href="#_TocSectionGrammar_14">3.14 List Option Value</a></div> +<div class="indent"><a href="#_TocSectionGrammar_15">3.15 Enumerated Option Value</a></div> +<div class="indent"><a href="#_TocSectionGrammar_16">3.16 Resource Configuration</a></div> +<div class="indent"><a href="#_TocSectionGrammar_17">3.17 Environment Variable Build Path</a></div> +<div class="indent"><a href="#_TocSectionGrammar_18">3.18 Managed Build Revision</a></div> +<div class="indent"><a href="#_TocSectionGrammar_19">3.19 Dynamic Element Provider</a></div> +</div> +<div class="indent"><a href="#_TocSectionUIElements">4 UI Representation</a> +<div class="indent"><a href="#_TocSectionUIElements_1">4.1 New Project Wizard</a></div> +<div class="indent"><a href="#_TocSectionUIElements_2">4.2 Build Property Page</a></div> +</div> +<div class="indent"><a href="#_TocSectionMakefile">5 Build File Generation</a> +<div class="indent"><a href="#_TocSectionMakefile_1">5.1 Default Build File Generator</a></div> +</div> +<div class="indent"><a href="#_TocSectionTutorial">6 Tutorial: An Example Tool + Integration</a> +<div class="indent"><a href="#_TocSectionTutorial_1">6.1 Setting up your Environment</a></div> +<div class="indent"><a href="#_TocSectionTutorial_2">6.2 Creating your Plug-in Project</a></div> +<div class="indent"><a href="#_TocSectionTutorial_3">6.3 Creating the Extension</a></div> +<div class="indent"><a href="#_TocSectionTutorial_4">6.4 Adding a ProjectType</a></div> +<div class="indent"><a href="#_TocSectionTutorial_5">6.5 Adding a Configuration</a></div> +<div class="indent"><a href="#_TocSectionTutorial_6">6.6 Adding a ToolChain</a></div> +<div class="indent"><a href="#_TocSectionTutorial_7">6.7 Adding a Builder</a></div> +<div class="indent"><a href="#_TocSectionTutorial_8">6.8 Adding a TargetPlatform</a></div> +<div class="indent"><a href="#_TocSectionTutorial_9">6.9 Adding a Tool</a></div> +<div class="indent"><a href="#_TocSectionTutorial_10">6.10 Testing the ProjectType</a></div> +<div class="indent"><a href="#_TocSectionTutorial_11">6.11 Adding Tool Options</a></div> +<div class="indent"><a href="#_TocSectionTutorial_12">6.12 Taking the Next Step</a></div> +</div> +<div class="indent"><a href="#_TocSectionDynamic">7 Adding Dynamic Behavior</a> +<div class="indent"><a href="#_TocSectionDynamic_1">7.1 Overview</a></div> +<div class="indent"><a href="#_TocSectionDynamic_2">7.2 Replacing the Build File Generator</a></div> +<div class="indent"><a href="#_TocSectionDynamic_3">7.3 Replacing the Dependency Calculator</a></div> +<div class="indent"><a href="#_TocSectionDynamic_4">7.4 Replacing the Command Line Generator</a></div> +<div class="indent"><a href="#_TocSectionDynamic_5">7.5 Determining if a Tool Chain is Installed</a></div> +<div class="indent"><a href="#_TocSectionDynamic_6">7.6 Defining Environment Variables</a></div> +<div class="indent"><a href="#_TocSectionDynamic_7">7.7 Defining a Build Path Resolver</a></div> +<div class="indent"><a href="#_TocSectionDynamic_8">7.8 Defining Build Macros</a></div> +<div class="indent"><a href="#_TocSectionDynamic_9">7.9 Defining a Configuration Name Provider</a></div> +<div class="indent"><a href="#_TocSectionDynamic_10">7.10 Defining an Output Name Provider</a></div> +<div class="indent"><a href="#_TocSectionDynamic_11">7.11 Defining an Option Value Handler</a></div> +<div class="indent"><a href="#_TocSectionDynamic_12">7.12 Defining an Option Applicability Calculator</a></div> +<div class="indent"><a href="#_TocSectionDynamic_13">7.13 Defining a Dynamic Element Provider</a></div> +</div> +<div class="indent"><a href="#_TocSectionAdvanced">8 Advanced Features</a> +<div class="indent"><a href="#_TocSectionAdvanced_1">8.1 Converting CDT 2.0 Manifest Files</a></div> +</div> +<!-- End of Table of Contents --><br> +<p class="section"><a name="_TocSectionIntro">1 Introduction</a></p> +<p>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.</p> +<p class="subsection"><a name="_TocSectionIntro_1">1.1 Who Needs This +Information</a></p> +<p>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 +through the <code>buildDefinitions</code> 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.</p> +<p>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, and 7 as they are primarily concerned +with adding new tool integrations to the build model.</p> +<p>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 +decide whether you will provide your own makefile and use the standard builder, +or add a description of your project-type to the extension point and +let the CDT generate the makefiles for your project.</p> +<p>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 <span style="font-style: italic;">Platform +Plug-in Developer Guide</span> if you +get stuck.</p> +<p class="subsection"><a name="_TocSectionIntro_2">1.2 Managed Build System +Overview</a></p> +<p>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.</p> +<p> +<img src="./image002.gif" + title="Figure 1 Managed build system overview" + alt="Build model logical elements" style="border: 0px solid ;"></p> +<h5>Figure 1 Managed build system overview</h5> +<p class="subsection">1.2.1 External Users</p> +<p>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. +</p> +<p class="subsection">1.2.2 Internal Users</p> +<p>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.</p> +<p class="subsection">1.2.3 Built-in Compiler Settings</p> +Every compiler relies on having a correct set of preprocessor +symbols +and header file search paths to perform proper builds. Even compilers +from the same vendor may use different symbols and search paths when +building for different operating systems. Some of these values may be +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.<br> +<p class="subsection">1.2.4 Tool Definitions and Settings Storage</p> +A key feature of the managed build system is that it is extensible. +Tool integrators +can use the grammar, described in § 3, to add +their own tools to the +build system. The same grammar is used to save the settings that the +user overrides through the UI between sessions, in the project's .cdtbuild file.<p class="subsection"><a name="_TocSectionIntro_3">1.3 The Standard Build +System</a></p> +<p>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.</p> +<p>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.</p> +<p class="section"><a name="_TocSectionUIModel">2</a> User Model</p> +<p class="MsoNormal" style="margin-top:6.0pt">The CDT user’s model of the MBS +contains the following primary objects: </p> +<table class="MsoTableGrid" border="1" cellspacing="0" cellpadding="0" style="border-collapse: collapse; border: medium none" id="table9"> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Project Type</td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: 1.0pt solid windowtext; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">A tool-integrator-defined + class of project which acts as a template for the projects that a user + will create. The template specifies one or more default configurations, + and can optionally provide code generation capability to create an + initial set of input resources for the project. The template can also + present various options in Wizard Pages that allow the user to further + customize the project. </td> + </tr> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border-left: 1.0pt solid windowtext; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Project</td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">A user-defined instance of + a particular project type along with a set of user specified input + resources and configurations.</td> + </tr> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border-left: 1.0pt solid windowtext; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Configuration</td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">A particular tool-chain + (possibly customized with additional or different tools), a set of + options for those tools, and other information which define a unique way + to build a project. Examples include building a project for debugging, + building a project for release, or building a project for a different + target platform.</td> + </tr> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border-left: 1.0pt solid windowtext; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Tool-chain</td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">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 + of tool-chains that support different host/target platform combinations, + and different versions of the tool-chain.</td> + </tr> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border-left: 1.0pt solid windowtext; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Tool </td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">A utility of some sort + that is used in the build process. A tool will generally process one or + more resources to produce output resources. Most tools have a set of + options that can be used to modify the behavior of the tool.</td> + </tr> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border-left: 1.0pt solid windowtext; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Option</td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">An individual control that + the user can set to modify the behavior of a tool.</td> + </tr> + <tr> + <td width="127" valign="top" style="width: 95.4pt; border-left: 1.0pt solid windowtext; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">Option Category</td> + <td width="463" valign="top" style="width: 347.4pt; border-left: medium none; border-right: 1.0pt solid windowtext; border-top: medium none; border-bottom: 1.0pt solid windowtext; padding-left: 5.4pt; padding-right: 5.4pt; padding-top: 0in; padding-bottom: 0in"> + <p class="MsoNormal" style="margin-top:6.0pt">A named set of options + used for grouping similar options together in a hierarchy.</td> + </tr> +</table> +<p class="subsection"><a name="_TocSectionUIModel_1">2.1 User Scenarios</a></p> +<p>The following sections describe how the user interacts with MBS. Text +in <font color="#FF0000">red </font>indicates MBS functionality that is not yet +implemented, but is intended to be implemented in future releases of MBS.</p> +<h3 class="subsection">2.1.1 Creating a New Project</h3> +<p class="MsoNormal" style="margin-top:6.0pt">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:</p> +<p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in; margin-right: 0in; margin-top: 6.0pt; margin-bottom: .0001pt"> +<span style="font-family: Symbol">·<span style="font:7.0pt "Times New Roman""> +</span></span>The project type must contain at least one default configuration +that uses a tool-chain that supports the host operating system and architecture.</p> +<p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in; margin-right: 0in; margin-top: 6.0pt; margin-bottom: .0001pt"> +<span style="font-family: Symbol; ">·<span style="font:7.0pt "Times New Roman""> +</span></span>If the project type implements the method +of verifying that its support has been installed, the method must return TRUE.</p> +<p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in; margin-right: 0in; margin-top: 6.0pt; margin-bottom: .0001pt"> +<span style="font-family: Symbol; color: red">·<span style="font:7.0pt "Times New Roman""> +</span></span><span style="color:red">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.</span></p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">After selecting the project type, +the user selects 1 … <i>n </i>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:</p> +<p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in; margin-right: 0in; margin-top: 6.0pt; margin-bottom: .0001pt"> +<span style="font-family: Symbol">·<span style="font:7.0pt "Times New Roman""> +</span></span>The tool-chain used by the configuration must support the host +operating system and architecture.</p> +<p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in; margin-right: 0in; margin-top: 6.0pt; margin-bottom: .0001pt"> +<span style="font-family: Symbol; ">·<span style="font:7.0pt "Times New Roman""> +</span></span>If the tool-chain implements the method of +verifying that its support has been installed, the method must return TRUE.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.).</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">After creating the new project, +the user can use any of the Eclipse methods of adding files to the project.</p> +<h3 class="subsection">2.1.2 Adding a New Configuration</h3> +<p class="MsoNormal" style="margin-top:6.0pt">The user can create a new +configuration based upon the settings used by one of the existing +configurations. <span style="color:red">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.</span></p> +<p class="MsoNormal" style="margin-top:6.0pt">The user +can also pick 1 … <i>n </i>configurations from the list of default +configurations defined in the project type. The list of configurations is, by +default, filtered as specified above.</p> +<h3 class="subsection">2.1.3 Modifying the Tool-chain of the Configuration</h3> +<p class="MsoNormal">The user can select a configuration +and modify the following attributes of the tool-chain: </p> +<ol style="margin-top: 0in; margin-bottom: 0in" start="1" type="1"> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">The command used to invoke a + particular tool in the tool-chain.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">The set of error parsers to + be used with the build output and the order that the error parsers will be + invoked </font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">The binary parser to be used + with the build binary outputs.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">The set of file extensions + that are processed by a tool.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">The + addition of Custom Build steps before or after the build. The user specifies the commands + to be executed by the step.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">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 + step.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2" color="#FF0000">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.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2"><span style="color:red">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.</span></font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2"><span style="color:red">The + mapping of an individual resource to a tool: </span> + <span style="color:red">The available tools come from the configuration’s + tool-chain, from a different tool-chain or from individually defined tools.</span></font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2"><span style="color:red">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.</span></font></li> +</ol> +<h3 class="subsection">2.1.4 Modifying the Tool Options of the Configuration</h3> +<p class="MsoNormal" style="margin-top:6.0pt">The user can modify the options of +an individual configuration<font color="#FF0000">, or he can make changes to a set of configurations +that he has selected</font>. <font color="#FF0000">The user can select a set of configurations individually</font><span style="color:red"> +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. </span></p> +<p class="MsoNormal" style="margin-top:6.0pt">The user can modify the options of +a tool used by the configuration. <span style="color:red">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.</span></p> +<p class="MsoNormal" style="margin-top:6.0pt"><span style="color:red">The user +can modify certain “well known” build settings for multiple selected +configurations, even when the configurations do not use the same tool-chain.</span></p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt"><span style="color:red">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.</span></p> +<h3 class="subsection">2.1.5 Modifying the Tool Options of an Individual File</h3> +<p class="MsoNormal" style="margin-top:6.0pt">The user can specify different +configuration specific build settings for individual files in the project.<span style="color:red"> +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.</span></p> +<p class="MsoNormal" style="margin-top:6.0pt">The user can add or remove a +Custom Build step for an individual resource.<span style="color:red"> </span> +The step<span style="color:red"> can execute before or after the tool assigned +to the resource, or they can </span>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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The user +can mark individual files to not be used in the building of the selected +configuration(s).</p> +<h3 class="subsection">2.1.6 Building a Configuration</h3> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The user can build the currently +active configuration<span style="color:red">, or select a different set of +configurations to build.</span></p> +<p class="MsoNormal" style="margin-top:6.0pt"><span style="color:red">The user +can rebuild an individual resource separate from building the entire project.</span></p> +<h3 class="subsection">2.1.7 Upgrading a Project to a New MBS or Tool-chain +Version.</h3> +<p class="MsoNormal">MBS defines a version number that is stored in every MBS +project file (.cdtbuild).</p> +<p class="MsoNormal" style="margin-top:6.0pt">When MBS reads a project file with +an older version number:</p> +<ol style="margin-top: 0in; margin-bottom: 0in" start="1" type="1"> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">MBS asks the user to confirm + the conversion.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="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.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">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.</font></li> +</ol> +<p class="MsoNormal" style="margin-top:6.0pt">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, …).</p> +<p class="MsoNormal" style="margin-top:6.0pt">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:</p> +<ol style="margin-top: 0in; margin-bottom: 0in" start="1" type="1"> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">MBS looks up the id with the + version specified with the reference. </font> </li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">If not found, MBS looks up + all occurrences of the id, and selects a match in the following order: + </font> + <ol style="margin-top: 0in; margin-bottom: 0in" start="1" type="a"> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">the id with the closest + higher version number that lists the referenced version in its <i> + versionsSupported</i> attribute</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">the id with no version + information specified</font></li> + </ol> + </li> +</ol> +<p class="MsoNormal" style="margin-top:6.0pt">If a match is found, there are 2 +scenarios:</p> +<ol style="margin-top: 0in; margin-bottom: 0in" start="1" type="1"> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="2">The version is still + actively supported by the tool integrator, and the MBS information is + loaded.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"> + <font face="arial, helvetica, geneva" size="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.</font></li> +</ol> +<p class="MsoNormal" style="margin-top:6.0pt">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, …).</p> +<p class="section">3<a name="_TocSectionGrammar"> Build Model Grammar Elements</a></p> +<p>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 +the managed build object model.</p> +<h3>Common Attributes</h3> +<p>Many of the MBS elements require the specification of the <i>id </i> +attribute. The attribute value typically takes a form similar to Eclipse +package names, e.g. "cdt.managedbuild.tool.gnu.c.linker". Each <i>id</i> +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 <i>id</i>s that you create.</p> +<p>Many of the MBS elements can specify the <i>name </i>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).</p> +<p>Many of the MBS elements can specify the <i>superClass </i>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.</p> +<h3>Schema Notes</h3> +<ul> + <li>Attributes highlighted in <span style="background-color: #FFFF00">yellow</span> + implement functionality that is new for CDT 3.0.</li> + <li>Attributes highlighted in <span style="background-color: #00FFFF">aqua</span> + indicate attributes that are deprecated in CDT 3.0. Each of these + attributes describes the new method to use to obtain equivalent + functionality.</li> + <li>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 <i>superClass + </i>attribute).</li> +</ul> +<p class="subsection"><a name="_TocSectionGrammar_1">3.1 Model</a></p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p> +<img + src="./image003.gif" + title="Figure 2 Managed build model elements" + alt="Build model grammar elements" style="border: 0px solid ;"></p> +<h5>Figure 2 Managed build model elements</h5> +<p class="subsection"><a name="_TocSectionGrammar_2">3.2 ProjectType</a></p> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">You must provide a unique identifier for the project-type in the <i>id</i> +attribute. The build model uses this information to distinguish between the +project-type definitions it finds. You must +also +provide a meaningful <var>name</var> that will be displayed to the +user +in the UI and new project wizards.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i> +isAbstract</i> 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 <i>superClass</i> attribute must contain +the unique identifier of the super-class project-type.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">A projectType may define a project +level macro provider in the <i>projectMacroSupplier</i> attribute. See § +7.8 for additional information.<br> +</p> +<p class="subsection">3.2.1 Schema</p> +<table + style="border: medium none ; border-collapse: collapse; width: 669px; " + border="1" cellpadding="0" cellspacing="0" height="170"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top;" height="22"> + <p align="left">Attribute</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top;" height="22"> + <p align="left">Description</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;" height="22"> + <p align="left">Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="33"> + <p>id</p> + </td> + <td + 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="33"> + <p>A unique identifier that the model manager will use to keep track of + this specific element.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="33"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="17"> + <p>name</p> + </td> + <td + 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="17"> + <p>The name for the projectType that is displayed to the user in the +UI.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="17"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="17"> + superClass</td> + <td + 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="17"> + <font size="2">The unique identifier of the projectType that this projectType is derived from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="17"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="49"> + <p>isAbstract</p> + </td> + <td + 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"> + <p><font size="2">Flags the projectType as abstract. An abstract + projectType can not be selected by the user in the UI, but projectTypes + derived from this projectType will inherit its attributes and children. + The default value is false.</font></p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="49"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="49"> + <p>isTest</p> + </td> + <td + 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"> + <p><font size="2">A projectType can be flagged for test purposes only. It + can be manipulated programmatically, in JUnit tests for example, but not + selected by the user in the UI. The default value is false.</font></p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="49"> + <p>no</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="49"> + <span style="background-color: #FFFF00">projectMacro Supplier</span></td> + <td + 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 IProjectBuildMacroSupplier + interface in order to provide project level build macros.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="49"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="49"> + <span style="background-color: #FFFF00">projectEnvironment Supplier</span></td> + <td + 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"> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="49"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="49"> + <span style="background-color: #FFFF00">configurationName Provider</span></td> + <td + 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"> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="49"> + no</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_3">3.3 Managed Project</a></p> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The following steps occur when a +CDT user creates a new Managed Build project:</p> +<ol> + <li><font face="arial, helvetica, geneva" size="2">A new managedProject element is + created. Its <i>projectType</i> attribute is set to the projectType that + the user selected. Its <i>name</i> attribute is set to the project name + that the user entered.</font></li> + <li><font face="arial, helvetica, geneva" size="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.</font></li> + <li><font face="arial, helvetica, geneva" size="2">Add a tool-chain element + that specifies as its <i>superClass</i> the tool-chain that is the child of + the selected configuration element.</font></li> + <li><font face="arial, helvetica, geneva" size="2">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 <i> + superClass</i>.</font></li> +</ol> +<p class="MsoNormal" style="margin-top:6.0pt">This prepares the new +project/configurations for modification by the user.</p> +<p class="subsection">3.3.1 Schema</p> +<table + style="border: medium none ; border-collapse: collapse; width: 669px; " + border="1" cellpadding="0" cellspacing="0" height="72" id="table3"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top;" height="22"> + <p align="left">Attribute</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top;" height="22"> + <p align="left">Description</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;" height="22"> + <p align="left">Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="17"> + name</td> + <td + 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="17"> + The name for the managedProject that is displayed to the user in the +UI.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="17"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="33"> + projectType</td> + <td + 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="33"> + <font size="2">The unique identifier of the projectType that was used when + creating this project.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="33"> + yes</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_4">3.4 Configuration</a></p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i> +artifactName</i> and <i>artifactExtension </i>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. </p> +<p class="MsoNormal" style="margin-top:6.0pt">Each configuration must have a unique identifier specified in the <var>id</var> +attribute that will be used by the build model to manage the +configuration. It must also have a <var>name</var> 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 <i>cleanCommand</i> +attribute which specifies a command that removes the build files. +</p> +<p class="MsoNormal" style="margin-top:6.0pt">A configuration may define a +configuration +level macro provider in the <i>configurationMacroSupplier</i> attribute. See § +7.8 for additional information.<br> +</p> +<p class="MsoNormal" style="margin-top:6.0pt">Additional configuration attributes are described in the schema table below.</p> +<p class="subsection">3.4.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table4"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + id</td> + <td + 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; vertical-align: top;"> + A unique identifier that the model manager will use to keep +track of this specific configuration.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;" height="18"> + name</td> + <td + 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; vertical-align: top;" height="18"> + Human-readable name for the configuration to be used in the UI.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;" height="18"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + parent</td> + <td + 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; vertical-align: top;"> + <font size="2">The unique identifier of the configuration that this + configuration is derived from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + artifactName</td> + <td + 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; vertical-align: top;"> + <font size="2">The name of the build goal defined by the configuration. + This can be set by the user in the UI.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + artifactExtension</td> + <td + 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; vertical-align: top;"> + <font size="2">The extension that the build goal will have, for example + ‘.exe’ or ‘.so’</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + in hierarchy</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + cleanCommand</td> + <td + 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; vertical-align: top;"> + <font size="2">The command to remove intermediary and output files on the + build machine.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + in hierarchy</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + errorParsers</td> + <td + 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"> + <font size="2">The semi-colon separated list of the default error parsers + to be used with this configuration. The list is ordered with the first + error parser on the list invoked first, the second error parser second, + and so on. The list may contain the error parsers defined by CDT and/or + other installed error parser extensions. The list of error parsers to + be used may be changed by the user on a per-configuration basis. When + specified, this overrides the tool-chain errorParsers attribute.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 92.15pt;" + valign="top" height="49"> + <span style="background-color: #FFFF00">configurationMacro Supplier</span></td> + <td + 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 IConfigurationBuildMacroSupplier + interface in order to provide configuration level build macros.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="49"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + <td + 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"> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_5">3.5 Tool Chain</a></p> +<p class="MsoNormal" style="margin-top:6.0pt">The toolChain element represents +the tool chain in the user model. It is a tool-integrator-defined, ordered 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The toolChain contains one or more +children of type tool. These define the tools used in the tool-chain.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The toolChain contains one child +of type targetPlatform. This defines the architecture/os combination(s) where +the outputs of the project can be deployed.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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. </p> +<p class="MsoNormal" style="margin-top:6.0pt">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 +specify the operating systems and architectures that the tool-chain is supported +on as a comma-separated list in the <i>osList</i> and <i>archList</i> +attributes. </p> +<p class="MsoNormal" style="margin-top:6.0pt">A tool-chain may be associated +with a scanner configuration profile that defines how to discover built-in compiler defines and +includes search paths.</p> +<p class="MsoNormal" style="margin-top:6.0pt">A tool-chain should specify the <i> +targetTool </i>attribute to identify the tool that runs to generate the primary +build output. If this is not specified, then 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">Additional tool-chain attributes are described in +the schema table below.</p> +<p class="subsection">3.5.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table5"> + <tbody> + <tr> + <th + style="border-left:1.5pt double windowtext; border-right:1pt solid windowtext; border-top:1.5pt double windowtext; border-bottom:1.5pt double windowtext; width: 17%; vertical-align: top; text-align: left; padding-left:5.4pt; padding-right:5.4pt; padding-top:0in; padding-bottom:0in"> + Attribute</th> + <th + style="border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; width: 62%; vertical-align: top; text-align: left; border-left-style:none; border-left-width:medium; padding-left:5.4pt; padding-right:5.4pt; padding-top:0in; padding-bottom:0in"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + id</td> + <td + 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; vertical-align: top;"> + A unique identifier that the model manager will use to keep track of this + specific toolChain.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + name</td> + <td + 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; vertical-align: top;"> + Human-readable name for the toolChain to be used in the UI.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + superClass</td> + <td + 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; vertical-align: top;"> + <font size="2">The unique identifier of the toolChain that this toolChain + is derived from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + isAbstract</td> + <td + 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; vertical-align: top;"> + <font size="2">Flags the toolChain as abstract. An abstract toolChain + must be defined as a top level object in the model definition and cannot + be selected by the user in the UI, but tool-chains derived from this + tool-chain will inherit its attributes and children. The default value + is false.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <span style="background-color: #FFFF00">targetTool</span></td> + <td + 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; vertical-align: top;"> + <span style="font-family: Arial"><font size="2">A semi-colon separated + 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.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <span style="background-color: #FFFF00">secondaryOutputs</span></td> + <td + 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; vertical-align: top;"> + <span style="font-family: Arial"><font size="2">A semi-colon separated + list of the identifiers of other output types, besides the primary + output of the targetTool, that are also considered to be build + artifacts. The build file generator will ensure that the outputs + get built.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + osList</td> + <td + 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; vertical-align: top;"> + <tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva"> + The list of operating systems that the tool-chain is supported on. The + valid list of</font></span></tt><font size="2"> operating system</font><tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">s + is the string values returned by Platform.getOS().</font></span></tt><font size="2"><br> + I</font><tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">f + the osList attribute is not specified, or if the value is "all", then + the tool-chain is supported on all operating systems. Otherwise, the + tool-chain is only displayed when CDT is running on one of the specified + operating systems, unless the user has turned off filtering.</font></span></tt></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + archList</td> + <td + 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"> + <tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva"> + The list of architectures that the tool-chain is supported on. The + valid list of</font></span></tt><font size="2"> </font><tt> + <span style="font-size: 10.0pt"><font face="arial, helvetica, geneva"> + architectures is the string values returned by Platform.getOSArch().</font></span></tt><font size="2"><br> + </font><tt><span style="font-size: 10.0pt"> + <font face="arial, helvetica, geneva">If the archList attribute is not + specified, or if the value is "all", then the tool-chain is supported on + all architectures. Otherwise, the tool-chain is only displayed when CDT + is running on one of the specified architectures, unless the user has + turned off filtering.</font></span></tt></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">errorParsers</td> + <td + 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"><font size="2">The semi-colon separated list of the default error + parsers to be used with this tool-chain. The list is ordered with the + first error parser on the list invoked first, the second error parser + second, and so on. The list may contain the error parsers defined by + CDT and/or other installed error parser extensions. When specified, + this overrides the tool errorParsers attributes of the tool children of + the tool-chain and the builder child of the tool-chain.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"><span style="background-color: #00FFFF">scannerInfoCollector</span></td> + <td + 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">REMOVED - see the scannerConfigDiscoveryProfileId attribute</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"><span style="background-color: #FFFF00">scannerConfig + DiscoveryProfileId</span></td> + <td + 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 an id of scanner configuration discovery profile for + gathering the built-in compiler settings for a toolchain.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_6">3.6 Builder</a></p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i> +command</i> attribute. Any special flags that need to be passed to the builder +are defined in the <i>arguments</i> 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.</p> +<p class="MsoNormal">The builder can specify a number of arguments that apply to +build macros and how they interact with the build file generator. </p> +<p class="MsoNormal">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 <i>variableFormat</i> attribute. +</p> +<p class="MsoNormal">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 <i>reservedMacroNames</i> and <i> +reservedMacroNameSupplier</i> attributes below.</p> +<p class="MsoNormal">The builder can provide the values for the file-context +build macros. To provide the value for the macro ${<macro_name>}, the <i> +macro<macro_name>Value</i> 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">Additional builder attributes are described in +the schema table below.</p> +<p class="subsection">3.6.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table6"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">id</font></td> + <td + 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; vertical-align: top;"> + <font face="Arial">A unique identifier that the model manager will use to keep +track of this specific builder.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">yes</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">name</font></td> + <td + 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; vertical-align: top;"> + <font face="Arial">Human-readable name for the builder to be used in the UI.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">superClass</font></td> + <td + 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; vertical-align: top;"> + <font size="2" face="Arial">The unique identifier of the builder that this builder is + derived from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">isAbstract</font></td> + <td + 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; vertical-align: top;"> + <font size="2" face="Arial">Flags the builder as abstract. An abstract builder must be + defined as a top level object in the model definition and cannot be + selected by the user in the UI, but builders derived from this builder + will inherit its attributes and children. The default value is false.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">command</font></td> + <td + 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; vertical-align: top;"> + <font size="2" face="Arial">The command used to invoke the builder. The default is + “make”.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">arguments</font></td> + <td + 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; vertical-align: top;"> + <font size="2" face="Arial">The default flags passed to the builder on the command + line. The default is “-k”.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <font face="Arial">errorParsers</font></td> + <td + 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; vertical-align: top;"> + <font size="2" face="Arial">The semi-colon separated list of the default error parsers + to be used with this builder.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">buildfileGenerator</font></td> + <td + 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"> + <font size="2" face="Arial">The name of a class that implements IManagedBuilderMakefileGenerator. </font> + See § 7.2 for additional information.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">variableFormat</span></font></td> + <td + 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"> + <p class="MsoNormal"><font face="Arial">The value of this attribute should + be set to the expression representing the variable format. For example, + to generate macros with the ${macro} format, the attribute would contain + ${=}. To generate macros with the @macro format, the attribute would + contain @=. If the attribute is not specified or contains the + empty string, this would mean that the builder can not treat environment + variables as its own variables. In this case, the build macros that + contain environment variables are resolved by MBS to their actual + value. The user can also specify that build macros that contain + environment variables be resolved to their actual value, as explained + earlier.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">isVariableCase + Sensitive</span></font></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">Specifies whether the + builder variables are case sensitive or not. Can be set to either “true” + or “false”. The default is “true”. If the builder does not support + case-sensitive variables and there are some build environment variables + that differ only in case (Environment variables on Unix-like operating + systems are case sensitive), then those macros will always get resolved + in the buildfile.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">reservedMacro + Names</span></font></td> + <td + 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"> + <p class="MsoNormal"><font face="Arial">Comma-separated list of reserved + macro names. The macro name could contain either the exact name or the + java regular expression. The latter could be used to supply the pattern + of variable names that are generated by MBS in case the “buildVariable” + attribute of the “InputType” element is not specified, etc. If + this attribute is specified and the reservedMacroNameSupplier is not + specified, the following macro names will be treated as reserved:</font></p> + <p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in"> + <font face="Arial">1.</font><span style="font-style: normal; font-variant: normal; font-weight: normal; font-family: Arial"><font size="2"> </font></span><font face="Arial">a + macro name that is equal to one of the names specified in the + reservedMacroNames value</font></p> + <p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in"> + <font face="Arial">2.</font><span style="font-style: normal; font-variant: normal; font-weight: normal; font-family: Arial"><font size="2"> </font></span><font face="Arial">a + macro name that matches one of the regexp patterns specified in the + reservedMacroNames value</font></p> + <p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in"> + <font face="Arial">3.</font><span style="font-style: normal; font-variant: normal; font-weight: normal; font-family: Arial"><font size="2"> </font></span><font face="Arial">a + macro name that is equal to one of the build variable names specified + InputType elements of the tools used in the tool-chain</font></p> + <span style="font-family: Arial"><font size="2">If this attribute is not + specified, MBS will assume that there are no reserved macro names that + could conflict with the build environment variable macros, except names + specified in the “buildVariable” attribute of the “InputType” elements: + these names will always be treated as reserved.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">reservedMacro + NameSupplier</span></font></td> + <td + 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"> + <p class="MsoNormal"><font face="Arial">Should be set to the name of the + class that implements the IReservedMacroNameSupplier interface. If this + attribute is specified the reservedMacroNames attribute is ignored, and + the following macro names will be treated as reserved:</font></p> + <p class="MsoNormal" style="text-indent: -.25in; margin-left: .25in"> + <font face="Arial">1.</font><span style="font-style: normal; font-variant: normal; font-weight: normal; font-family: Arial"><font size="2"> </font></span><font face="Arial">macro + names that the IReservedMacroNamesSupplier specifies as reserved</font></p> + <p style="text-indent: -0.25in; margin-left: 0.25in"> + <span style="font-family: Arial"><font size="2">2. a macro + name that is equal to one of the build variable names specified + InputType elements in the tools used in the tool-chain. </font> + </span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">macroInputFile + NameValue</span></font></td> + <td + 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"> + <font face="Arial">Represents the InputFileName macro value. The macro + specifies the input file name. The input file has the following meaning:<br> + 1. If a tool does not accept building multiple files of the primary + input type with one tool invocation, the input file is the file of the + primary input type being built.<br> + 2. If a tool accepts building multiple files of the primary input type + with one tool invocation the input file is undefined and the macros + representing the input file contain information about one of the inputs + of the primary input type being built.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">macroInputFile + ExtValue</span></font></td> + <td + 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"> + <font face="Arial">Represents the InputFileExt macro value. The macro + specifies the extension of the input file.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">macroInputFile + BaseNameValue</span></font></td> + <td + 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"> + <font face="Arial">Represents the InputFileBaseName macro value. The macro + specifies the base name of the input file. That is the file name with an + extension stripped.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">macroInputFile + RelPathValue</span></font></td> + <td + 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"> + <font face="Arial">Represents the InputFileRelPath macro value. The macro + specifies the input file path relative to the builder current directory.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">macroInputDir + RelPathValue</span></font></td> + <td + 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"> + <font face="Arial">Represents the InputDirRelPath macro value. The macro + specifies the input file directory path relative to the builder current + directory.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial"><span style="background-color: #FFFF00">macroInputDir + RelPathValue</span></font></td> + <td + 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"> + <font face="Arial">Represents the InputDirRelPath macro value. The macro + specifies the input file directory path relative to the builder current + directory.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <font face="Arial">no</font></td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">macroOutput FileNameValue</span></td> + <td + 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"> + Represents the OutputFileName macro value. The macro specifies the output + file name. The output file has the following meaning:<br> + 1. If a tool is not capable of producing multiple files of the primary + output type with one tool invocation the output file is the file of the + primary output type that is built with a given tool invocation.<br> + 2. If a tool is capable of producing multiple files of the primary + output type with one tool invocation the output file is undefined and + the macros representing the output file contain information about one of + the files of the primary output type that are built with a given tool + invocation.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">macroOutput FileExtValue</span></td> + <td + 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"> + Represents the OutputFileExt macro value. The macro specifies the output + file extension.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">macroOutput FileBaseNameValue</span></td> + <td + 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"> + Represents the OutputFileBaseName macro value. The macro specifies the + output file base name. That is the output file name with an extension + stripped.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">macroOutput FileRelPathValue</span></td> + <td + 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"> + Represents the OutputFileRelPath macro value. The macro specifies the + output file path relative to the current builder directory.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">macroOutput DirRelPathValue</span></td> + <td + 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"> + Represents the OutputDirRelPath macro value. The macro specifies the + output file directory path relative to the current builder directory.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">versionsSupported</span></td> + <td + 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"> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">convertToId</span></td> + <td + 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"> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_7">3.7 Target Platform</a></p> +<p class="MsoNormal">The targetPlatform element represents the os/architecture +combination(s) upon which the output of a tool-chain can be deployed. The <i> +osList </i>and <i>archList</i> attributes contain the Eclipse names of the +operating systems and architectures described by this element. </p> +<p class="MsoNormal" style="margin-top:6.0pt">CDT offers a facility for parsing +binary files if it knows which output format the build artifact has been +produced with. The <i>binaryParser</i> attribute must contain the id of the +appropriate parser if you want build artifacts of the tool-chain to be parsed in +the workspace.</p> +<p class="subsection">3.7.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table7"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + id</td> + <td + 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; vertical-align: top;"> + A unique identifier that the model manager will use to keep track of this + specific targetPlatform.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + name</td> + <td + 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; vertical-align: top;"> + Human-readable name for the targetPlatform to be used in the UI.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + superClass</td> + <td + 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; vertical-align: top;"> + <font size="2">The unique identifier of the targetPlatform that this + targetPlatform is derived from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + isAbstract</td> + <td + 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; vertical-align: top;"> + <font size="2">Flags the targetPlatform as abstract. An abstract + targetPlatform must be defined as a top level object in the model + definition and can not be selected by the user in the UI, but target + platforms derived from this target platform will inherit its attributes + and children. The default value is false.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + osList</td> + <td + 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; vertical-align: top;"> + <tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva"> + The list of operating systems that is valid for this target platform. + The valid list of</font></span></tt><font size="2"> operating system</font><tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">s + is the string values returned by Platform.getOS().</font></span></tt></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + archList</td> + <td + 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"> + <tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva"> + The list of architectures that is valid for this target platform. The + valid list of</font></span></tt><font size="2"> architecture</font><tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">s + is the string values returned by Platform.getOSArch().</font></span></tt></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">binaryParser</td> + <td + 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"><font size="2">The id of the appropriate parser for the build + artifact</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_8">3.8 Tool</a></p> +<p class="MsoNormal" style="margin-top:6.0pt">The tool element represents the +tool in the user model. <span style="color:red"> </span>A tool must have a +unique <i>id</i> for the build model, and a <i>name</i> 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">A tool contains one or more +children of type option which define the tool command line settings that can be +changed by the user.</p> +<p class="MsoNormal" style="margin-top:6.0pt">A tool contains 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. </p> +<p class="MsoNormal" style="margin-top:6.0pt">A tool contains 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i>natureFilter</i> 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 <i>not</i> 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">Each tool specifies a <i>command</i> +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 <i>outputFlag</i> attribute.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The <i>commandLineGenerator</i> +attribute allows the implementer to specify a class that implements the <code>IManagedCommandLineGenerator</code> +interface. An explanation of how to replace the default command line +generator can be found in § 7.4. </p> +<p class="MsoNormal" style="margin-top:6.0pt">Additional tool attributes are +described in the schema table below.</p> +<p class="subsection">3.8.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + <p>Attribute</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + <p>Description</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + <p>Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>id</p> + </td> + <td + 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"> + <p>A unique identifier for the tool that will be used by the +build model.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>name</p> + </td> + <td + 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"> + <p>Human-readable name for the tool to be used in the UI.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>no</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + superClass</td> + <td + 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"> + <font size="2">The unique identifier of the tool that this tool is derived + from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + isAbstract</td> + <td + 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"> + <font size="2">Flags the tool as abstract. An abstract tool must be + defined as a top level object in the model definition and can not be + selected by the user in the UI, but tools derived from this tool will + inherit its attributes and children. The default value is false.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p><span style="background-color: #00FFFF">sources</span></p> + </td> + <td + 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"> + <p>DEPRECATED - see the inputType element.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p><span style="background-color: #00FFFF">outputs</span></p> + </td> + <td + 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"> + <p>DEPRECATED - see the outputType element.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>outputFlag</p> + </td> + <td + 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"> + <p>An optional flag for tools that allow users to specify a name +for the artifact of the tool. For example, the GCC compiler and linker +tools typically allow the user to specify the name of the output with +the '-o' flag, whereas the archiver that creates libraries does not.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>no</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p><span style="background-color: #00FFFF">outputPrefix</span></p> + </td> + <td + 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"> + <p>DEPRECATED - see the outputType element.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #00FFFF">headerExtensions</span></td> + <td + 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"> + <p>DEPRECATED - see the inputType element.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + natureFilter</td> + <td + 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"> + Specify the project natures the tool should apply to. The default + value is "both".</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + command</td> + <td + 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"> + The command that invokes the tool. For example, gcc for the +Gnu C compiler, or g++ for the Gnu C++ compiler.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + in hierarchy</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + commandLinePattern</td> + <td + 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"> + <font size="2">Specifies a command “pattern” that indicates how the parts + of the command line are used to create the entire command line. The + pattern consists of the replaceable variables COMMAND, FLAGS, + OUTPUT_FLAG, OUTPUT_PREFIX, OUTPUT and INPUTS. The default command line + pattern is <br> + ${COMMAND} ${FLAGS} ${OUTPUT_FLAG}${OUTPUT_PREFIX}${OUTPUT} ${INPUTS}<br> + White space and other characters are significant and are copied to the + generated command.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">customBuildStep</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">When True, indicates that + the Tool represents a user-defined custom build step. The default is + False. When True, the default value of the commandLinePattern attribute + changes to “$(command)”.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + errorParsers</td> + <td + 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"> + <font size="2">Contains a semi-colon separated, ordered, list of error + parser ids. MBS adds the error parser(s) to the end of the toolChain + error parser list, if not already present, when a project resource is + defined to use the tool. The error parser(s) can be removed by the CDT + user, and is automatically removed when there are no more project + resources that use the tool.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p><span style="background-color: #00FFFF">dependencyCalculator</span></p> + </td> + <td + 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"> + <p>DEPRECATED - see the inputType element.<br> + </p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>commandLineGenerator</p> + </td> + <td + 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"> + <p class="MsoNormal">The name of a class that implements + IManagedCommandLineGenerator in order to provide custom command line + generation logic.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>no</p> + </td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_9">3.9 +<span style="background-color: #FFFF00">Input Type</span></a></p> +<p class="MsoNormal">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 +<span style="font-size:10.0pt;font-family:"Courier New""> +org.eclipse.core.runtime.contentTypes</span> extension point.) </p> +<p class="MsoNormal" style="margin-top:6.0pt">CDT pre-defines the following +content types:</p> +<ul> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">cSource .c</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">cHeader .h</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">cxxSource .cpp,.cxx,.cc</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">cxxHeader .hpp,.hh</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">asmSource .asm,.s</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">objectFile .o,.obj</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">executable .exe</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">staticLibrary .lib,.a</li> + <li> + <p class="MsoNormal" style="margin-top:6.0pt">sharedLibrary .dll,.so</li> +</ul> +<p class="MsoNormal" style="margin-top:6.0pt">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 <var>dependencyCalculator</var> attribute allows the +implementer to specify a class that implements the <code>IManagedDependencyGenerator</code> +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.<br> +</p> +<p class="MsoNormal" style="margin-top:6.0pt">Other +attributes of the InputType element are described in the table below.</p> +<p class="subsection">3.9.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table12"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">id</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">A unique identifier that + the MBS will use to track this element.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + Yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="19"> + <span style="background-color: #FFFF00">name</span></td> + <td + 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="19"> + <span style="font-family: Arial"><font size="2">The name of the input type + that is displayed to the user in the UI.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="19"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">superclass</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">The unique identifier of + the inputType that this inputType is derived from.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">sourceContentType</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">The id of an Eclipse + content type that describes this input type. If both the sources + attribute and the sourceContentType attribute are specified, the + sourceContentType will be used if it is defined in Eclipse.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">sources</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">A comma-separated list of + file extensions that the tool will produce output for. Note that the + user will not be able to modify the set of file extensions as they can + when sourceContentType is specified.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">dependencyContent Type</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">The id of an Eclipse + content type used for dependency files. If both the + dependencyExtensions attribute and the dependencyContentType attribute + are specified, the dependencyContentType will be used if it is defined + in Eclipse.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">dependencyExtensions</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">A comma-separated list of + file extensions used by dependency files. Note that the user will not be + able to modify the set of file extensions as they can when + dependencyContentType is specified.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">option</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">The id of the option that + is used on the command line to identify this input. The default is to + not use a command line option and to assign this input to the ${Inputs} + part of the command line.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">multipleOfType</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">True if all of the inputs + of this category are used in one invocation of the tool. The inputs can + be project resources, or the outputs of other tools in the tool-chain. + The default is False.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">primaryInput</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">True is this is considered + the primary input of the tool. The default is False.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">dependencyCalculator</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">The name of a class that + provides the source file dependency calculation for the input type. The + class implements the IManagedDependencyGenerator interface. The default + is none.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">buildVariable</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">A variable used in the + build file to represent the list of input files. The same variable name + can be used by an outputType to identify a set of output files that + contribute to this tool’s input (i.e., those using the same + buildVariable name). A build variable is ignored when multipleOfType is + false and this is the primary input of the tool. The default name is + chosen by MBS.</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_10">3.10 +<span style="background-color: #FFFF00">Additional Input</span></a></p> +<p class="MsoNormal">This element is a child of the InputType element. It +describes additional input of a particular input type.<span style="font-size:10.0pt;font-family:Arial"> +</span>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).</p> +<p class="subsection">3.10.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table14"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">paths</span></td> + <td + 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"> + <span style="font-family: Arial"><font size="2">Defines a semi-colon + separated list of the relative or absolute path of the resource(s) to + which this element applies. The resource(s) must be a member of the + project, the output from another tool in the tool-chain, or an external + file. The file name of a path can use GNU Make pattern rule syntax (in + order to generate the name from the output file name).</font></span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + Yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="18"> + <span style="background-color: #FFFF00">kind</span></td> + <td + 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="18"> + <p class="MsoNormal"><span style="font-size:10.0pt;font-family:Arial"> + Defines the kind of additional input. The valid string values are: + </span></p> + <ul style="margin-top: 0in; margin-bottom: 0in" type="disc"> + <li class="MsoNormal"> + <span style="font-size:10.0pt;font-family:Arial"> + AdditionalDependency – added as a tool dependency, but not to the + command line.</span></li> + <li class="MsoNormal"> + <span style="font-size:10.0pt;font-family:Arial">AdditionalInput – + added as an additional input to the command line, but not as a + dependency.</span></li> + <li class="MsoNormal"> + <span style="font-size:10.0pt;font-family:Arial"> + AdditionalInputDependency – added as both.</span></li> + </ul> + <span style="font-family: Arial"><font size="2">The default is </font> + </span><span style="font-size: 10.0pt; font-family: Arial"> + AdditionalInputDependency.</span></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="18"> + No</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_11">3.11 +<span style="background-color: #FFFF00">Output Type</span></a></p> +<p class="MsoNormal">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 +<span style="font-size:10.0pt;font-family:"Courier New""> +org.eclipse.core.runtime.contentTypes</span> extension point.) </p> +<p class="MsoNormal" style="margin-top:6.0pt">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:</p> +<ol style="margin-top: 0in; margin-bottom: 0in" start="1" type="1"> + <li class="MsoNormal" style="margin-top: 6.0pt"><font face="Arial" size="2"> + If this is the “target” tool in the tool-chain, and this is the primary + OutputType, use the user-defined artifact name and extension.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"><font face="Arial" size="2"> + If the <i>option</i> attribute is specified, use the value of the option.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"><font face="Arial" size="2"> + If the <i>nameProvider </i>attribute is specified, call the nameProvider and use + the returned name(s).</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"><font face="Arial" size="2"> + If the <i>outputNames </i>attribute is specified, use the value of the attribute.</font></li> + <li class="MsoNormal" style="margin-top: 6.0pt"><font face="Arial" size="2"> + Use the <i>namePattern</i> attribute value to construct the name from the input + file name.</font></li> +</ol> +<p> 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 <i>outputPrefix</i> +attribute.</p> +<p class="subsection">3.11.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table13"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">id</span></td> + <td + 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"> + A unique identifier that the MBS will use to track this element.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + Yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="19"> + <span style="background-color: #FFFF00">name</span></td> + <td + 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"> + The name of the input type that is displayed to the user in the UI.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top" height="18"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">superclass</span></td> + <td + 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"> + The unique identifier of the outputType that this outputType is derived + from.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">outputContentType</span></td> + <td + 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"> + The id of an Eclipse content type that describes this output type. If both + the outputs attribute and the outputContentType attribute are specified, + the outputContentType will be used if it is defined in Eclipse.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">outputs</span></td> + <td + 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"> + The default extension that the tool will produce from a given input. Note + that the user will not be able to modify the set of file extensions as + they can when outputContentType is specified.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">option</span></td> + <td + 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"> + The id of the option that is used on the command line to specify this + output. The default is to use the Tool “outputFlag” attribute if + primaryOutput is True. If option is not specified, and primaryOutput is + False, then the output file(s) of this outputType are not added to the + command line. </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">multipleOfType</span></td> + <td + 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"> + True if multiple outputs of this type are created by one invocation of the + tool. The default is False.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">primaryInputType</span></td> + <td + 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"> + Id of the input type that is used in determining the build “rules” for the + output type and for the default name of the output file. The default is + the input type with primaryInput == true..</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">primaryOutput</span></td> + <td + 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"> + If True, then this is the primary output of the tool. The default is + False.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">outputPrefix</span></td> + <td + 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"> + Some tools produce files with a special prefix that must be specified. + For example, a librarian on POSIX systems expects the output to be lib.a + so ‘lib’ would be the prefix. The default is to use the Tool + “outputPrefix” attribute if primaryOutput is True, otherwise the default + is an empty string.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">outputNames</span></td> + <td + 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 semi-colon delimited, complete set of output resource names + created by the output type.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">namePattern</span></td> + <td + 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 a name pattern with the file extension, using the Gnu pattern + rule syntax, for deriving the output resource name from the input + resource name. The default, “%”, is to use the input file base filename + with the output extension.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">nameProvider</span></td> + <td + 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"> + The name of a class that implements the IManagedOutputNameProvider + interface. When specified, the namePattern and outputNames attributes + are ignored. When multipleOfType is true, this attribute, or + the outputNames attribute, is required + in order for MBS to know the names of the output files.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">buildVariable</span></td> + <td + 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"> + A variable used in the build file to represent the list of output files. + The same variable name can be used by an inputType to identify a set of + output files that contribute to the tool’s input (i.e., those using the + same buildVariable name). The default name is chosen by MBS.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + No</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_12">3.12 Option Category</a></p> +<p><font size="2">The optionCategory element represents the option category in +the user model. A tool </font>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 <var>id</var> +attribute. This will be used by the build model to manage the category. +The user will see the value assigned to the <var>name</var> +attribute. If the category is nested inside another category, the +unique +identifier of the higher level category must be specified in the <var>owner</var> +attribute, otherwise specify the identifier of the tool +the category belongs to.</p> +<p class="subsection">3.12.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <th + style="border-left:1.5pt double windowtext; border-right:1pt solid windowtext; border-top:1.5pt double windowtext; border-bottom:1.5pt double windowtext; width: 106px; vertical-align: top; text-align: left; padding-left:5.4pt; padding-right:5.4pt; padding-top:0in; padding-bottom:0in"> + <p>Attribute</p> + </th> + <th + style="border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; width: 66%; vertical-align: top; text-align: left; border-left-style:none; border-left-width:medium; padding-left:5.4pt; padding-right:5.4pt; padding-top:0in; padding-bottom:0in"> + <p>Description</p> + </th> + <th + style="border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; width: 13%; vertical-align: top; border-left-style:none; border-left-width:medium; padding-left:5.4pt; padding-right:5.4pt; padding-top:0in; padding-bottom:0in"> + <p>Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>id</p> + </td> + <td + 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"> + <p>Used by the build model to uniquely identify the option +category.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>name</p> + </td> + <td + 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"> + <p>A human-readable category name, such as 'Pre-processor +Options'. This will be the name the user sees displayed in the UI.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid double double; border-width: medium 1pt 1.5pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>owner</p> + </td> + <td + style="border-style: none solid double none; border-width: medium 1pt 1.5pt medium; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>Option categories can be nested inside other option +categories. This is the ID of the owner of the category.</p> + </td> + <td + style="border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; width: 13%; vertical-align: top; border-left-style:none; border-left-width:medium; border-top-style:none; border-top-width:medium; padding-left:5.4pt; padding-right:5.4pt; padding-top:0in; padding-bottom:0in"> + <p>yes</p> + </td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_13">3.13 Option</a></p> +<p class="MsoNormal">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 <i>id</i> for the +build model to properly manage it. A descriptive <i>name</i> 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 <i>category</i> attribute.</p> +<p class="subsection">3.13.1 Option Types</p> +<p>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 <var>valueType</var> attribute is used +to +indicate to the build model what kind of option it is.</p> +<p>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 <code>string</code>, +<code>boolean</code>, <code>stringList</code>, and <code>enumerated</code>. +</p> +<p>There are also four specialized cases of list options, <code>includePath</code>, +<code>definedSymbols</code>, <code>libs</code>, and <code>userObjs</code> +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.</p> +<p class="subsection">3.13.1.1 String Options</p> +<p class="MsoNormal" style="margin-top:6.0pt">String options are used for tool +commands that take a user-defined value. The UI representation for a string +option is a text box.</p> +<p class="subsection">3.12.1.2 Boolean Options</p> +<p><font size="2">Boolean options are</font> 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 <var>command</var> +associated with +the option will be passed to the tool when it is invoked. If false, the +value associated with the <var>commandFalse</var> attribute will be passed.</p> +<p class="subsection">3.13.1.3 Enumerated Options</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="subsection">3.13.1.4 String List Options</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="subsection">3.13.1.4.1 Special List Options</p> +<p>There are four special cases of string list options; <code>includePaths</code> +specify the paths to search for header files, <code>definedSymbols</code> +for user-defined preprocessor defines, <code>libs</code> for libraries +that must be linked into the final build goal, and <code>userObjs</code> +for external object files that must be linked.</p> +<p>While specifying these types of options as type <var>stringList</var> +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.</p> +<p class="subsection">3.13.1.4.2 Browse Types</p> +<p>Certain types of list 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 must +specify the <var>browseType</var> for list options as <code>none</code> +(default), <code>file</code>, or <code>directory</code>. Note that +the <var>browseType</var> attribute is only used for list options. It +is ignored for all other option types.<br> +</p> +<p class="subsection">3.13.2 Values and Default Values</p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i>defaultValue</i> attribute. When an +option has a value that has been specifically set, the value is contained in the +<i>value</i> attribute. In order to determine the current value of an option, +MBS performs the following steps until a value is found:</p> +<ol> + <li><font face="arial, helvetica, geneva" size="2">Examine the <i>value</i> + attribute of the option.</font></li> + <li><font face="arial, helvetica, geneva" size="2">Examine the <i>value</i> + attribute of the option’s <i>superClass </i>recursively.</font></li> + <li><font face="arial, helvetica, geneva" size="2">Examine the <i> + defaultValue</i> attribute of the option.</font></li> + <li><font face="arial, helvetica, geneva" size="2">Examine the <i> + defaultValue</i> attribute of the option’s <i>superClass recursively</i>.</font></li> + <li><font face="arial, helvetica, geneva" size="2">Use the default value for + the option type.</font></li> +</ol> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="subsection">3.13.3 Option Commands</p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i>command</i> attribute is used to hold the +actual flag to pass along with the option value. </p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i>command </i> +attribute. The <i>command </i>attribute can be empty in order to support an area +for typing in additional options. For enumerated options, the <i>command</i> +associated with the selected enumerated value is used, not the command defined +in the option. For boolan options, the <i>command</i> is used if the option +value is set to true, otherwise the value of the <i>commandFalse</i> attribute +is used. For list options, the <i>command</i> is applied to each element of the +list.</p> +<table style="border: medium none ; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Option Value Type</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Uses Default Value</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Uses Command</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>UI Element</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>string</p> + </td> + <td + 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; width: 110.7pt;" + valign="top" width="148"> + <p>Yes</p> + </td> + <td + 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; width: 110.7pt;" + valign="top" width="148"> + Yes</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Text box</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>boolean</p> + </td> + <td + 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; width: 110.7pt;" + valign="top" width="148"> + <p>Yes</p> + </td> + <td + 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; width: 110.7pt;" + valign="top" width="148"> + <p>Yes if true, else commandFalse</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Check box</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>enumerated</p> + </td> + <td + 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; width: 110.7pt;" + valign="top" width="148"> + <p>Yes</p> + </td> + <td + 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; width: 110.7pt;" + valign="top" width="148"> + <p>No.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Combo box</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid double double; border-width: medium 1pt 1.5pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>stringList</p> + </td> + <td + style="border-style: none solid double none; border-width: medium 1pt 1.5pt medium; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>No.</p> + </td> + <td + style="border-style: none solid double none; border-width: medium 1pt 1.5pt medium; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>Yes.</p> + </td> + <td + style="border-style: none double double none; border-width: medium 1.5pt 1.5pt medium; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 110.7pt;" + valign="top" width="148"> + <p>List and button bar</p> + </td> + </tr> + </tbody> +</table> +<p class="subsection">3.13.4 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + <p>Attribute</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + <p>Description</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + <p>Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>id</p> + </td> + <td + 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; vertical-align: top;"> + <p>A unique identifier for the option that will be used by the +build model.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>name</p> + </td> + <td + 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; vertical-align: top;"> + <p>Human-readable name for the option to be used in the UI.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>no</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + superClass</td> + <td + 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; vertical-align: top;"> + <font size="2">The unique identifier of the option that this option is + derived from.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + isAbstract</td> + <td + 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; vertical-align: top;"> + <font size="2">Flags the option as abstract. An abstract option must be + defined as a top level object in the model definition and can not be + selected by the user in the UI, but options derived from this option + will inherit its attributes and children. The default value is false.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + category</td> + <td + 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; vertical-align: top;"> + This is the id of the option category for this option. The id +can be the id of the tool which is also a category.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + valueType</td> + <td + 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; vertical-align: top;"> + Type of value the option contains.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + in hierarchy</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;" height="18"> + value</td> + <td + 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; vertical-align: top;" height="18"> + <font size="2">Value assigned to the option by the end user or in a + default configuration.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;" height="18"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>defaultValue<br> + </p> + </td> + <td + 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; vertical-align: top;"> + <p>Optionally specifies the value for the option if the user has +not edited it. For options containing a Boolean value, the string +‘true’ is treated as true, any other value as false.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>no</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>command</p> + </td> + <td + 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"> + <p>An optional value that specifies the actual command that will +be passed to the tool on the command line. <font size="2">The command + provides a “pattern” for specifying where the value should be placed for + options of type string and stringlist. The pattern can + contain the replaceable variable “value”. If no ${value} is specified + in the command, the option value is appended to the end of the specified + command.</font></p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">commandFalse</td> + <td + 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">An optional value, used only with options of +type Boolean, that specifies the actual command that will be passed to +the tool on the command line when the value of the Boolean option is +False.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">browseType</td> + <td + 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">This value is used for list (and related) +options only. If you need a list option to prompt the user to browse +for a file or directory when adding a new value, set the value of the +attribute accordingly. By default the value is treated as no browsing +needed.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + <tr> + <td + style="border-style: none solid double double; border-width: medium 1pt 1.5pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top">resourceFilter</td> + <td + style="border-style: none solid double none; border-width: medium 1pt 1.5pt medium; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"><font size="2">Specifies the resource types that this option + applies to. The values are “project”, “file”, and “all”. The default + is “all”. Specifying “project” indicates that the option is displayed + when modifying a configuration’s options, but not when modifying an + individual file’s options. Specifying “file” indicates the opposite.</font></td> + <td + style="border-style: none double double none; border-width: medium 1.5pt 1.5pt medium; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top">no</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_14">3.14 List Option Value</a></p> +<p>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.</p> +<p>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 <var>builtIn</var> 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.</p> +<p class="subsection">3.14.1 Schema</p> +<table + style="border: medium none ; border-collapse: collapse; width: 642px;" + border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + <p>Attribute</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + <p>Description</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + <p>Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>value</p> + </td> + <td + 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"> + <p>The contents of the list item. The build model will apply the command defined in the option to each value in the list.</p> + </td> + <td + style="border-style: none double solid solid; border-width: medium 1.5pt 1pt 1pt; border-left: 1pt solid windowtext; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid double double; border-width: medium 1pt 1.5pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>builtIn</p> + </td> + <td + style="border-style: none solid double none; border-width: medium 1pt 1.5pt medium; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>An optional Boolean field that tells the build model to treat +the value defined as read-only.</p> + </td> + <td + style="border-style: none double double solid; border-width: medium 1.5pt 1.5pt 1pt; border-left: 1pt solid windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>no</p> + </td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_15">3.15 Enumerated Option +Value</a></p> +<p>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.</p> +<p>Each element of an enumerated option has a <var>name</var> that +will +be shown to the user in the UI. It also has a <var>command</var> which +should correspond to the command line option that gets passed to the +tool by the builder if this element is selected.</p> +<p>A default element can be indicated by setting the value of <var>isDefault</var> +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.</p> +<p class="subsection">3.15.1 Schema</p> +<table + style="border: medium none ; border-collapse: collapse; width: 681px;" + border="1" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + <p>Attribute</p> + </th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + <p>Description</p> + </th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + <p>Required</p> + </th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>id</p> + </td> + <td + 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"> + <p>A unique identifier for the tool that will be used by the +build model.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>name</p> + </td> + <td + 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"> + <p>A descriptive name that will be displayed to the user in the +UI as one of the option values to select.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>yes</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>isDefault</p> + </td> + <td + 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"> + <p>Flags this enumerated value as the default to apply to the +option if the user has not changed the setting.</p> + </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>no</p> + </td> + </tr> + <tr> + <td + style="border-style: none solid double double; border-width: medium 1pt 1.5pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>command</p> + </td> + <td + style="border-style: none solid double none; border-width: medium 1pt 1.5pt medium; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt;" + valign="top"> + <p>The command that the enumerated value translates to on the +command line.</p> + </td> + <td + style="border-style: none double double none; border-width: medium 1.5pt 1.5pt medium; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; vertical-align: top;"> + <p>yes</p> + </td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_16">3.16 Resource +Configuration</p> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The resourceConfiguration +attributes are specified in the schema table below.</p> +<p class="subsection">3.16.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table8"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + resourcePath</td> + <td + 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; vertical-align: top;"> + <font size="2">The path of the project resource to which this + resourceConfiguration applies.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + exclude</td> + <td + 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; vertical-align: top;"> + <font size="2">Specifies whether the resource is excluded from building in + the parent configuration. The default value is false. The + resourceConfiguration element should retain its tool children, if any + exist, even when excluded from the build.</font></td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + </tbody> +</table> +<p class="subsection"></a><a name="_TocSectionGrammar_17">3.17 +<span style="background-color: #FFFF00">Environment Variable Build Path</span></a></p> +<p class="MsoNormal">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.</p> + +<p class="MsoNormal" style="margin-top:6.0pt">The envVarBuildPath +attributes are specified in the schema table below.</p> +<p class="subsection">3.17.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table17"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">pathType</span></td> + <td + 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; vertical-align: top;"> + The build path type. Can be one of the following: “buildpathInclude”, + “buildpathLibrary”</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + </a> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">variableList</span></td> + <td + 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; vertical-align: top;"> + comma-separated list of the environment variable names used to store the + include paths</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">pathDelimiter</span></td> + <td + 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; vertical-align: top;"> + <p class="MsoNormal">Represent the delimiter used to separate the paths. + If omitted the default system delimiter will be used. That is the “:” + for Unix-like systems and the “;” for Windows systems. If the + “buildPathResolver” attribute is specified, the “pathDelimiter” is + ignored</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + <span style="background-color: #FFFF00">buildPathResolver</span></td> + <td + 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; vertical-align: top;"> + <p class="MsoNormal">The name of a class that implements the IBuildPathResolver interface + that the tool-integrator can supply in order to provide his/her own + logic of resolving the variable values to the build paths</p> + <p class="MsoNormal"><b>Design note:</b> the reason why this callback is + needed is because some tools may store the build paths in some special + way or in the format other than <path1><delimiter><path2><delimiter>…<pathN>. + The example of such a tool is gcc for Win32 Cygwin. The cygwin + version of gcc does not accept the windows-style paths stored in the + build paths environment variables. The path must be specified in + the POSIX format and using the “:” delimiter, for example: “/cygdrive/c/includes:/cygdrive/d/…”</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + no</td> + </tr> + </tbody> +</table> +<p class="subsection"><a name="_TocSectionGrammar_18">3.18 Managed Build Revision</a></p> +<p>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.<br> +</p> +<p class="subsection">3.18.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table11"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + fileVersion</td> + <td + 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; vertical-align: top;"> + A +string containing the three version tokens </td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + </tbody> +</table> +</a> +<p class="subsection"><a name="_TocSectionGrammar_19">3.19 Dynamic Element Provider</a></p> +<p>Tool integrators may supply this element to dynamically provided the +defintions that are otherwise specified in the buildDefinitions extension point. +Each configuration element returned from this IMangedConfigElementProvider +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.</p> +<p class="subsection">3.19.1 Schema</p> +<table + style="border: medium none ; width: 670px; border-collapse: collapse;" + border="1" cellpadding="0" cellspacing="0" id="table10"> + <tbody> + <tr> + <th + style="border-style: double solid double double; border-color: windowtext; border-width: 1.5pt 1pt 1.5pt 1.5pt; padding: 0in 5.4pt; width: 20%; vertical-align: top; text-align: left;"> + Attribute</th> + <th + style="border-style: double solid double none; border-width: 1.5pt 1pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 65%; vertical-align: top; text-align: left;"> + Description</th> + <th + style="border-style: double double double none; border-width: 1.5pt 1.5pt 1.5pt medium; border-top: 1.5pt double windowtext; border-right: 1.5pt double windowtext; border-bottom: 1.5pt double windowtext; padding: 0in 5.4pt; width: 15%; vertical-align: top;"> + Required</th> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt;" + valign="top"> + name</td> + <td + 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; vertical-align: top;"> + The name of the dynamic element provider.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + <tr> + <td + style="border-style: none solid solid double; border-width: medium 1pt 1pt 1.5pt; border-left: 1.5pt double windowtext; border-right: 1pt solid windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + class</td> + <td + 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; vertical-align: top;"> + The class that implements the IManagedConfigElementProvider interface. The + logic of determining the elements is left to the implementer, but they + must be correctly formed or the build model will have trouble loading.</td> + <td + style="border-style: none double solid none; border-width: medium 1.5pt 1pt medium; border-right: 1.5pt double windowtext; border-bottom: 1pt solid windowtext; padding: 0in 5.4pt; vertical-align: top;"> + yes</td> + </tr> + </tbody> +</table> +</a> +<p class="section"></a><a name="_TocSectionUIElements">4 UI Representation</a></p> +<p>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.</p> +<p class="subsection"><a name="_TocSectionUIElements_1">4.1 New Project Wizard</a></p> +<p>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 <var>isTest</var> and <var>isAbstract</var> +attribute are set to <code>false</code>. The value of the projectType's <var>name</var> +attribute is +used to populate the drop-down list-box selection widget. Similarly, +the configuration +check list is populated with all the defined configurations associated +with the selected projectType. <br> +</p> +<p> +<img style="border: 0px solid ;" + src="./image024.gif" + title="Figure 3 New project wizard" + alt="New project wizard project type selection page"></p> +<h5>Figure 3 New project wizard</h5> +<p class="subsection"><a name="_TocSectionUIElements_2">4.2 Build Property Page</a></p> +<p>The contents of the build property page for a project are created by +examining the 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.</p> +<p class="subsection">4.2.1 Managing the Configuration</p> +<p>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 <var>name</var> information.</p> +<p> +<img style="border: 0px solid ;" + src="./image026.gif" + title="Figure 4 Configuration selection" + alt="Project property page configuration selection/edit area"></p> +<h5>Figure 4 Configuration selection</h5> +<p>Users change the build settings for options associated with +categories 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 are the root +elements of the tree. Categories are displayed as leaves of the tool +they belong to. In both 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.</p> +<p> +<img style="border: 0px solid ; width: 575px; height: 413px;" + src="./image028.gif" + title="Figure 5 Tools and option category display" + alt="Project property page tool selection area"></p> +<h5>Figure 5 Tools and option category display</h5> +<p>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.</p> +<p>The Compiler Flags option contains a <var>string</var> 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.</p> +<p>The Optimization Level option is an <var>enumerated</var> option. +These types of options force the user to select a single value from a +list of possible choices. Note that the <var>name</var> of the option +is +applied to the label in the UI, whereas the <var>name</var> of each +individual <var>enumeratedOptionValue</var> element is used to +populate +the list.</p> +<p>The Include Paths option is a special case of a <var>stringList</var> +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 <var>optionType</var> +attribute +is set to <code>includePath</code>. 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.</p> +<p> +<img style="border: 0px solid ;" + src="./image030.gif" + title="Figure 6 Option display" + alt="Project property page option edit area"></p> +<h5>Figure 6 Option display</h5> +<p>Finally Verbose, a Boolean option, is displayed as a check-box. +Since +the default value for this option is defined as <code>false</code>, +the +check-box is left unselected when it is created.</p> +<p>Note that the UI actually builds itself <span + style="font-style: italic;">on the fly</span> 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.</p> +<p class="section"><a name="_TocSectionMakefile">5 Build File Generation</a></p> +<p>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 +the dependency calculator are shown in the model below.</p> +<p> +<img style="border: 0px solid ;" + src="./image031.gif" + title="Figure 6 Option display" + alt="Builder, generator, and dependency calculator model"></p> +<h5>Figure 6 Relationship between build file generator and dependency +calculator</h5> +<p class="subsection"><a name="_TocSectionMakefile_1">5.1 Default Build File +Generator</a></p> +<p>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 <code>source1/</code>, <code>source2/</code>, +and <code>source2/source21</code>. Header files are located in 2 +locations; <code>headers/</code>, and <code>source2/source21</code>. +To illustrate the problem of calculating source-level dependencies for <span + style="font-style: italic;">make</span>, <span + style="font-style: italic;">Class1</span> is in a has-a relationship +with <span style="font-style: italic;">Class2</span>.<br> +</p> +<table style="text-align: left; width: 739px; height: 269px;" border="0" + cellpadding="2" cellspacing="2"> + <tbody> + <tr> + <td> <img style="border: 0px solid ;" + src="./image032.gif" + title="" alt="Example project"> </td> + <td> <img style="width: 246px; height: 216px;" + alt="Has-a relationship between Class1 and Class2" + src="./image035.gif"> + </td> + </tr> + </tbody> +</table> +<p><br> +</p> +<h5>Figure 7 Example project source files</h5> +<p>While simple, this example illustrates some of the problems projects +using <span style="font-style: italic;">make</span> 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.</p> +<p>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 <span style="font-style: italic;">make</span> gives us +for free.</p> +<p>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 <span style="font-style: italic;">make</span> to +bring them all +together.</p> +<p>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.</p> +<p> +<img style="border: 0px solid ;" + src="./image034.gif" + title="" alt="Example project generated files"></p> +<h5>Figure 8 Generated makefiles</h5> +<p>In the next sections, we will examine the makefiles that are +generated by the default build file generator in more detail.</p> +<p class="subsection">5.1.1 Main Makefile</p> +<p> 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. </p> +<p> +<img + src="./image036.gif" + title="" alt="Generated main makefile" style="border: 0px solid ;"></p> +<p>This makefile is passed as an argument to <span + style="font-style: italic;">make</span>, so it contains +<span style="font-style: italic;">clean</span> +and <span style="font-style: italic;">all</span> +targets. It contains the build rules for the following types of tools +defined in the tool-chain:</p> +<ol> + <li>The target tool as defined by the tool-chain</li> + <li>All tools where the primary input-type defines multipleOfType == true</li> + <li>All tools that consume the output of type #2 tools</li> +</ol> +<p class="subsection">5.1.2 Makefile Fragments</p> +<p>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 <code>source1/</code> +subdirectory looks like.</p> +<p><img style="border: 0px solid ;" + src="./image038.gif" + title="" alt="Generated fragment makefile"></p> +<p>As you can see, the fragment contributes one file, <code>class1.cpp</code>, +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. </p> +<p class="subsection">5.1.3 Dependency Makefile Fragments</p> +<p>There is one final piece to the puzzle, and that is a list of +dependencies for each source file in the build. Recall that <span + style="font-style: italic;">make</span> +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 <span + style="font-style: italic;">make</span>. Consider the +dependencies of the final build target to <span + style="font-style: italic;">Class1</span>. It is obvious that if the +implementation file, <span style="font-style: italic;">Class1.cpp</span>, +changes then the object module, <span style="font-style: italic;">Class1.o</span>, +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 <span + style="font-style: italic;">Class1.h</span> changes. To make matters +more complex, <span style="font-style: italic;">Class1</span> is in a +has-a relationship with <span style="font-style: italic;">Class2</span>, +so any changes to <span style="font-style: italic;">Class2.h</span> +should result in a rebuild of <span style="font-style: italic;">Class1.o</span>. +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.<br> +</p> +The build file generator places the all of these dependencies +in +a separate makefile fragment for each file participating in the build. +The figure below +shows the fragment for <span style="font-family: monospace;">Class1</span><code></code>. +<p> +<img style="border: 0px solid ;" + src="./image040.gif" + title="" alt="Generated dependency makefile fragment" + name="Generated Dependencies"></p> +<p class="subsection">5.1.4 Support Makefiles</p> +<p>There are two other makefiles that are generated and included in the +main makefile. The first, <code>sources.mk</code>, +defines a list of source macros, such as <code>C_SRCS</code>, and all +of the subdirectories the builder believes contribute source code to +the build. The second, <code>objects.mk</code>, +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.</p> +<p class="subsection">5.1.5 Inter-Project +Dependencies</p> +<p>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.</p> +<p>For the remainder of this discussion, let us consider the following +basic scenario. Project <code>Makefile Example</code> builds an +executable, <code>Messages.exe</code>. It +references a project, <code>UI Widgets</code>, which builds a shared +library, <code>UIWidgets.dll</code>. +The +main build target in the makefile for <code>Makefile Example</code> +would be generated with the output of <code>UI Widgets</code> as a +dependency. </p> +<p> +<img style="border: 0px solid ;" + src="./image042.gif" + title="" alt="Generated inter-project dependency target"></p> +<p>As you can see from the generated makefile above, the rule for the +target <code>Messages.exe</code> will be run if <code>UIWidgets.dll</code> +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.</p> +<p>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. </p> +<p class="section"><a name="_TocSectionTutorial">6 Tutorial: An Example Tool +Integration</a></p> +<p>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.<br> +</p> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_1">6.1 Setting up your +Environment</a></p> +<p>Tool integrations are specified by extending the <code>buildDefinitions</code> +extension point defined in the <code>org.eclipse.cdt.managedbuilder.core</code> +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 <span + style="font-weight: bold;">Help > About Eclipse Platform > +Feature Details</span> 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.<br> +</p> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_2">6.2 Creating your +Plug-in +Project</a></p> +<p>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.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Open the <span style="font-weight: bold;">New Project... </span>wizard +(<span style="font-weight: bold;">File > New > Project...</span>), +choose <span style="font-weight: bold;">Plug-in Project</span> +from the <span style="font-weight: bold;">Plug-in Development</span> +category and click the <span style="font-weight: bold;">Next ></span> +button. <br> + </li> + <li>On the <span style="font-weight: bold;">Plug-in Project </span>page, +use <code>org.eclipse.cdt.example.toolchain</code> +as the name for your project, and click the <span + style="font-weight: bold;">Next ></span> button. <br> + </li> + <li>On the <span style="font-weight: bold;">Plug-in Content</span> +page, you will see that the wizard has set the id to <code>org.eclipse.cdt.example.toolchain</code> +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 <span + style="font-weight: bold;">"Generate the Java class that..."</span> +check-box and click on the <span style="font-weight: bold;">Finish</span> +button.</li> + <li>If asked if you would like to switch to the <span + style="font-weight: bold;">Plug-in +Development</span> perspective, answer <span style="font-weight: bold;">Yes</span>.</li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_3">6.3 Creating the +Extension</a></p> +<p>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 <code>buildDefinitions</code> extension point.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>If the xml file for the plugin was not opened by default when you +switched to the <span style="font-weight: bold;">Plug-in Development</span> +perspective, double click on the <code>org.eclipse.cdt.example.toolchain</code> +project in the <span style="font-weight: bold;">Package Explorer</span> +to expand it. Double click on +the <span style="font-weight: bold;">plugin.xml</span> file to edit +its contents.</li> + <li>We have to add a dependency between our project and the <code>org.eclipse.cdt.managedbuilder.core</code> +plug-in where the extension point is defined. Click on the <b>Dependencies</b> +tab located along the bottom of the manifest editor. Click the <span + style="font-weight: bold;">Add…</span> button located beside the <span + style="font-weight: bold;">Required Plug-Ins</span> +list. Select <code>org.eclipse.cdt.managedbuilder.core</code> from the +list and then click the <span style="font-weight: bold;">OK</span> +button.</li> + <li>Select the <span style="font-weight: bold;">Extensions</span> +tab located along the bottom of the +manifest editor. Click the <span style="font-weight: bold;">Add…</span> +button located beside the <span style="font-weight: bold;">All +Extensions</span> list.</li> + <li>You should now be on the <span style="font-weight: bold;">Extension +Points</span> tab on the <span style="font-weight: bold;">Extension +Point Selection</span> page. Make +sure that the <span style="font-weight: bold;">Show only extension +points from the required plug-ins</span> +check-box is selected. Select <code>org.eclipse.cdt.managedbuilder.core.buildDefintions</code> +from the list of extension points. Click the <span + style="font-weight: bold;">Finish</span> button.</li> + <li>In the Extension Details column in the manifest editor, use <code>org.eclipse.cdt.example.toolchain</code> +as the <span style="font-weight: bold;">ID</span> for the +extension, and <code>Example Tool Chain</code> +for the <span style="font-weight: bold;">Name</span>.</li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_4">6.4 Adding a Project Type</a></p> +<p>Now we will add a new projectType, configuration, toolChain, builder, +targetPlatform and an example tool to +the extension.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Right click on <code>org.eclipse.cdt.managedbuilder.core.buildDefinitions</code> +in the <span style="font-weight: bold;">All Extensions</span> column +of the manifest editor to access the context menu for the extension. +Select <span style="font-weight: bold;">New +> projectType</span> to add a projectType definition. A new projectType with the id <code>org.eclipse.cdt.example.toolchain.projectType[n]</code> +should appear below the extension point. That's a bit verbose, so +rename it to <code>example.toolchain.executable</code>.<br> + </li> + <li>Let’s give the new projectType a human-readable name. Locate the <span + style="font-weight: bold;">name</span> +property in the <span style="font-weight: bold;">Extension Element +Details</span> column. For now, let’s use the name <code>Example +Executable</code> for our projectType.</li> + <li>Make sure that the values of <span style="font-weight: bold;">isTest</span> + and<b> isAbstract</b> are<b> </b>set +to false.<br> + </li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_5">6.5 Adding a +Configuration</a></p> +<p>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.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Right click on <span style="font-weight: bold;">Example +Executable</span> in the <span style="font-weight: bold;">All +Extensions</span> list. From the context menu select <span + style="font-weight: bold;">New > +configuration</span>. <br> + </li> + <li>Change the value of the <span style="font-weight: bold;">name</span> +property and to be <code>Test Release</code> and the value of <span + style="font-weight: bold;">id</span> to be <code> +example.toolchain.configuration.release</code>.</li> + <li>Now set the clean command for the configuration. For the purposes of +this example, click on the <span style="font-weight: bold;">cleanCommand</span> +property to edit it and +enter <code>rm –f</code>.</li><a name="_TocSectionTutorial_13"> + <li>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 <code>org.eclipse.cdt.core.MakeErrorParser;org.eclipse.cdt.core.GCCErrorParser;org.eclipse.cdt.core.GLDErrorParser;<br> +org.eclipse.cdt.core.GASErrorParser;org.eclipse.cdt.core.VCErrorParser</code></li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_6">6.6 Adding a ToolChain</a></p> +<p style="font-weight: normal;"> +Each configuration requires a toolChain child that defines the set of tools used by +the configuration.</p> +<a name="_TocSectionTutorial_6"> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Right click on <span style="font-weight: 700">Test Release</span> in the <span style="font-weight: bold;">All +Extensions</span> list. From the context menu select <span + style="font-weight: bold;">New > + toolChain</span>. <br> + </li> + <li>Change the value of the <span style="font-weight: bold;">name</span> +property and to be <code>Example Tool-chain </code> and the value of <span + style="font-weight: bold;">id</span> to be <code> +example.toolchain.toolchain</code>.</li> + <li>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 <span + style="font-weight: bold;">osList</span> +property and click it to edit the value. Enter <code>win32</code> if +you are running the tutorial on Windows, <code>linux</code> if you are +running on one of the Linux distributions, <code>solaris, hpux, </code>or<code> +aix</code> if +you are running on a version of Solaris, or <code>other</code> if none +of the above apply.</li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_7">6.7 Adding a </a>Builder</p> +<p style="font-weight: normal;"> +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.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li><a name="_TocSectionTutorial_14">Right click on + <span style="font-weight: 700">Example Tool-chain</span> in the <span style="font-weight: bold;">All +Extensions</span> list. From the context menu select <span + style="font-weight: bold;">New > + builder</span>. + </li><a name="_TocSectionTutorial_15"> + <li>Change the value of the <span style="font-weight: bold;">name</span> +property to be <code>Example Builder </code>and the value of <span + style="font-weight: bold;">id</span> to be <code> +example.toolchain.builder</code>.</li> + </a> + <li>Locate the <span + style="font-weight: bold;">Command</span> +property, click on it to edit the value, and enter <code>make</code>.</li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_8">6.8 Adding a TargetPlatform</a></p> +<p style="font-weight: normal;"> +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.</p> +<a name="_TocSectionTutorial_8"> +<ol style="margin-top: 0in;" start="1" type="1"> + <li><a name="_TocSectionTutorial_16">Right click on + <span style="font-weight: 700">Example Tool-chain</span> in the <span style="font-weight: bold;">All +Extensions</span> list. From the context menu select <span + style="font-weight: bold;">New > + targetPlatform</span>. + </li><a name="_TocSectionTutorial_17"> + <li>Change the value of the <span style="font-weight: bold;">name</span> +property and to be <code>Example Target Platform </code> and the value of <span + style="font-weight: bold;">id</span> to be <code> +example.toolchain.targetplatform</code>.</li></a></a> + <li>Our target platform is the same as our host platform. Enter the + same value for the <b>osList</b> property as entered for the ToolChain <b> + osList</b>.</li> + <a name="_TocSectionTutorial_8"> + <li>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 <code>org.eclipse.cdt.core.ELF</code>. +If you are running the tutorial on Windows, enter the value <code>org.eclipse.cdt.core.PE</code>.</li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_9">6.9 Adding a Tool</a></p> +<p style="font-weight: normal;"> +Each toolChain describes the set of tools used by the build utility to create +the build artifacts of the configuration.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Right click on <span style="font-weight: bold;">Example + Tool-chain</span> to get the context menu +and select <span style="font-weight: bold;">New > tool</span>. Name +the tool <code>Compiler</code> and make its <span + style="font-weight: bold;">id</span> <code>example.toolchain.compiler</code>.</li> + <li>Let us assume that the tool should appear for both C and C++ +projects, although this is not always the case. Locate the <span + style="font-weight: bold;">natureFilter</span> +property and select <code>both</code> from the list of choices.</li> + <li>Tools declare which file extensions they operate on and, +optionally, the file extensions they produce. Our imaginary compiler +only works on files with a ‘c’ or ‘C’ extension. Locate the <span + style="font-weight: bold;">sources</span> +property and set its contents to be a comma-separated list containing <code>c,C</code>. +Note that there should not be any spaces between the values. Let us +assume that the output of the compiler is an object module that has the +extension ‘o’. Set the value of the <span style="font-weight: bold;">outputs</span> +property of the +tool to <code>o</code>.</li> + <li>The build model needs to know if there are any special file +extensions that indicate a file is a ‘header’ file. Set the <span + style="font-weight: bold;">headersExtension</span> +property to be a comma-separated list containing <code>h,H</code>.</li> + <li>Tools often have a flag to specify the output of a tool. For the +purposes of this example, set the <span style="font-weight: bold;">outputFlag</span> +property to <code>-o</code>.</li> + <li>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 <code>ccc</code> as the value for the <span + style="font-weight: bold;">command</span> +property.</li> +</ol> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_10">6.10 Testing the ProjectType</a></p> +<p>We have now defined enough information to create a project for +our +new example project-type, so let’s go test it out.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Make sure our example project is selected in the <span + style="font-weight: bold;">Package +Explorer</span>. Select <span style="font-weight: bold;">Run > +Debug As > Run-time Workbench</span> +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 <span style="font-weight: bold;">Yes</span>.<br> + </li> + <li>In the new workspace, open the <span style="font-weight: bold;">C/C++</span> +perspective.</li> + <li>Run the new project wizard. From the Selection page choose either +a managed C or C++ project. Click the <span style="font-weight: bold;">Next +></span> button, give +your project any name you wish, and click <span + style="font-weight: bold;">Next ></span> again. <br> + </li> + <li>You should now be at the <span style="font-weight: bold;">Select a type of + project</span> page. Your new + project-type will appear as a choice in the <span style="font-weight: bold;">Project + Type</span> + selection widget. Select it and note that the list of available + configurations now contains the single configuration we defined for the + project-type. <br> + </li> + <li>Click <span style="font-weight: bold;">Finish</span>.<br> + </li> + <li>Right click on your new project in the <span + style="font-weight: bold;">Navigator</span> or <span + style="font-weight: bold;">C/C++ +Projects</span> view to access the context menu, and select <span + style="font-weight: bold;">Properties</span> +to open the property browser for the project. Select <span + style="font-weight: bold;">C/C++ Build</span> +from the choices, select the <b>Tool Settings</b> tab, and note that the tool we defined appears in the list.</li> + <li>Select the <b>Build Settings</b> tab. The user can change the + build output name and the build command from here, and the MBS +will manage that selection between sessions.</li> + <li>Select the <span style="font-weight: bold;">Error Parsers</span> + 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.<br> + </li> + <li>Select the <span + style="font-weight: bold;">Binary Parser</span> 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.</li> +</ol> +<p>At this point, you have no doubt noticed that the <span + style="font-weight: bold;">C/C++ Build</span> 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.</p> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_11">6.11 Adding Tool Options</a></p> +<p>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.</p> +<ol style="margin-top: 0in;" start="1" type="1"> + <li>Shutdown the debug session.<br> + </li> + <li>Switch back to the <span style="font-weight: bold;">Plug-in +Development</span> perspective. Right +click on the <code>Compiler</code> entry in the extension description +to bring up the context menu. Select <span style="font-weight: bold;">New +> optionCategory</span> to +add the category. Set the <span style="font-weight: bold;">name</span> +of the category to <code>General</code>.</li> + <li>You must specify the id of the tool the category belongs to in +the <span style="font-weight: bold;">owner</span> property. The +simplest way to do this is to copy the <span style="font-weight: bold;">id + </span>from the compiler description and paste it into the <span + style="font-weight: bold;">owner</span> property of the +category.<br> + </li> + <li>Set the unique <span style="font-weight: bold;">id</span> of the +category to <code>example.compiler.optionCategory.general</code>.</li> + <li>Right click on the tool, not the category, to bring up its +context menu and select <span style="font-weight: bold;">New > +option</span> to add our first +option. Name the option <code>Include paths</code> and set the <span + style="font-weight: bold;">id</span> to <code>example.toolchain.compiler.general.incpath</code>.<br> + </li> + <li>Set the <span style="font-weight: bold;">valueType</span> +property to <code>includePath</code> from the list of choices. Please +refer to § 3.10 for a description of option value types and what +this decision implies. <br> + </li> + <li>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 <span style="font-weight: bold;">browseType</span> property to + <code>directory</code>.<br> + </li> + <li>In +the <span style="font-weight: bold;">command</span> property, enter <code>-I</code>. + <br> + </li> + <li>In the <span style="font-weight: bold;">category</span> +property, put the unique <span style="font-weight: bold;">id</span> of +the category that you entered in step 4.</li> + <li>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 <span style="font-weight: bold;">category</span> property). +Set the <span style="font-weight: bold;">name</span> of the option to <code>Other +flags</code>, its <b>id</b> to <code>example.toolchain.compiler.general.otherflags</code>, its <span style="font-weight: bold;">valueType</span> +to <code>string</code>, and its <span style="font-weight: bold;">defaultValue</span> +to <code>-c</code>.</li> + <li>Add a check-box option to the 'General' category of the compiler. Name it <code>Error messages, </code> + set the<b> id</b> to <code>example.toolchain.compiler.general.errmsgs,</code> and set its + <b>valueType</b> to <code>boolean</code>. +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 <span style="font-weight: bold;">command</span> property to <code>-Wall</code> +to turn on error reporting, and set the <span + style="font-weight: bold;">commandFalse</span> property to <code>-w</code> +to disable it.<br> + </li> +</ol> +<p>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.</p> +<p> +<img style="border: 0px solid ;" + src="./image044.gif" + title="" alt="Tutorial project property page"></p> +<h5>Figure 9 MBS property page with tool, category, and options<br> +</h5> +<p style="font-weight: normal;" class="subsection"> +<a name="_TocSectionTutorial_12">6.12 Taking the Next Step</a></p> +<p>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.</p> +<p style="font-weight: normal;" class="subsection">6.12.1 Adding More +Tools</p> +<p>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.</p> +<p style="font-weight: normal;" class="subsection">6.12.2 Defined +Symbols and Header File Search +Paths</p> +<p>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. The build model only +promises to store the type and value of an option, it does not know +anything about the contents. However, you can flag certain 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 answer +them to the appropriate clients in the CDT core without any further +intervention on your part.</p> +<p style="font-weight: normal;" class="subsection">6.12.3 Built-in +Symbols and Search Paths</p> +<p>We have automated the discovery of paths and symbols for standard +GCC compilers that are building targets for the platform they are +hosted on. Work is in progress to make this completely replaceable so +that cross-compilers and non-GCC compilers can be more easily +integrated. Until then, there are two approaches you can take, but both +involve hard-coding the include path and defined symbol options with +list +option values containing the correct information. If you add a value to +the include path or symbol option, it will be displayed to the user by +default. This may be the right approach to take if you believe that +users will change these values frequently. However, it will clutter the +UI with values and since they are editable, users may delete them +accidentally.</p> +The alternative is to flag the list option value as a built-in +value. +In this case, the user will not be able to edit the values through the +UI. This has the advantage of keeping the UI cleaner, but the only way +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. +<p style="font-weight: normal;" class="subsection">6.12.4 User-Specified +Libraries and Object +Modules</p> +<p>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 answer a valid list. Flag the +option value type as “libs” for external libraries or “userObjs” for +object modules.</p> +<p style="font-weight: normal;" class="subsection">6.12.5 ProjectType and Other +Element +Hierarchies</p> +<p>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.</p> +<p>Since 2.1 +it is now 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.<br> +</p> +<p style="font-weight: normal;" class="subsection">6.12.6 Publishing +your Plug-in</p> +<p>The subject of packaging Eclipse plug-ins is well covered in the <span + style="font-style: italic;">Platform Plug-in Developer Guide</span>. +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.<b> +</b></p> +<ol> + <li style="font-weight: normal;">From the <span + style="font-weight: bold;">Plug-in +Development +Perspective</span>, select the plugin.xml +file for your plug-in in the package explorer. Open the <span + style="font-weight: bold;">File > +Export...</span> wizard. On the <span style="font-weight: bold;">Select</span> +page, chose <span style="font-weight: bold;">File system</span> from +the export +destination list. Click the <span style="font-weight: bold;">Next ></span> +button. </li> + <li style="font-weight: normal;">Make sure that <code>org.eclipse.cdt.example.toolchain</code> +is +selected in the left-hand list and that only plugin.xml is selected in the + right. To select an export destination, click the Browse... button beside + the text box labeled To directory. +Browse to the plugins +subdirectory of your Eclipse installation. Click the Finish +button.</li> + <li>Restart Eclipse, switch to the <span style="font-weight: bold;">C/C++ +Development Perspective</span> and run the new project wizard to create +a new project based on your tool integration.</li> +</ol> +<p class="section"><a name="_TocSectionDynamic">7 Adding Dynamic Behavior</a></p> +<p class="subsection"><a name="_TocSectionDynamic_1">7.1 Overview</p> +<p>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.</p> +<p class="subsection"><a name="_TocSectionDynamic_2">7.2 Replacing the Build File Generator</a></p> +<p>You can specify a replacement +build file generator for a project configuration. You must specify and supply a class +that +implements the <code>IManagedBuilderMakefileGenerator</code> +interface shown below. The class name is assigned to the builder element, +buildfileGenerator attribute. </p> +<p> +<img style="border: 0px solid ;" + src="./image060.gif" + title="" alt="Makefile generator interface"> </p> +<h5>Figure 10 Makefile generator interface</h5> +<p>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.</p> +<p> +<img style="border: 0px solid ;" + src="./image062.gif" + title="" alt="MBS makefile generator initialization routine"></p> +<p>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 <code>MultiStatus</code> 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.<br> +</p> +<p> +<img style="border: 0px solid ;" + src="./image064.gif" + title="" alt="Return value"></p> +<p>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.</p> +<p class="subsection"><a name="_TocSectionDynamic_3">7.3 Replacing the +Dependency Calculator</a></p> +<p>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 <var>makedepend</var> to calculate +source-level +dependencies. Other tool integrations might provide dependency calculation +along with the other build tools, like the GCC preprocessor. Still +others leave +it to the developer to manage them manually. The replaceable dependency +generator in the MBS tries to accommodate all three types of dependency +discovery mechanisms. </p> +<p>If you replace the build file generator in your configuration, the odds are +good that you will also have to replace the dependency calculator or +perform the calculation internally. 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 <code>IManagedDependencyGenerator</code> +shown in the figure below and specify that class in an inputType element, +dependencyCalculator attribute. </p> +<p> +<img style="border: 0px solid ;" + src="./image066.gif" + title="" alt="Dependency generator interface"></p> +<h5>Figure 11 Dependency generator interface</h5> +<p>Typically, these types of dependencies are only relevant for the +compiler but what tool you use to specify the generator (or generators) +is arbitrary. +Your replacement +build file generator can instantiate and use the calculator whenever +it is needed. Recall that the build file generator will be asked to +generate the dependencies by the MBS builder, so perhaps that is the +only time you will need it. Of course, you may prefer to generate the +dependencies during the build, so the dependency calculator may be +needed when the command for the compiler is generated in the build file. </p> +<p>By design, a dependency calculator must answer what type of +dependency generation it will do. If it is a command-, or external-type +generator, +the client can ask it for the command given a resource and the build +information for a project configuration. If you are using an external process, the +answer might be a properly formatted command to execute in an external +shell. The default dependency calculator provides +the GCC compiler with a command that gets executed when the source file +is built. The code snippet below shows the transformation that is +needed in that case.</p> +<p> +<img style="border: 0px solid ;" + src="./image068.gif" + title="" alt="Dependency generator code snippet"></p> +<p>If you do not have an external process or tool to calculate this, +you can 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 <code>IResource</code> +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.<br> +</p> +<p class="subsection"><a name="_TocSectionDynamic_4">7.4 Replacing the Command Line Generator</p> +<p>You can specify a replacement command line generator for a tool. You must specify and supply a class +that +implements the <code>IManagedCommandLineGenerator</code> +interface. The class name is assigned to the tool element, commandLineGenerator attribute. </p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier">public interface +IManagedCommandLineGenerator {</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public +IManagedCommandLineInfo generateCommandLineInfo(</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> ITool tool,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String +commandName,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String[] +flags,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String +outputFlag,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String +outputPrefix,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String +outputName,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String[] +inputResources,</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> String +commandPattern); </span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier">}</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier">public interface +IManagedCommandLineInfo {</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String +getCommandLine();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String +getCommandName();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String getFlags();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String +getOutputFlag();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String +getOutputPrefix();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String +getOutputName();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier"> public String +getInputResources();</span></p> +<p class="MsoNormal" style="text-autospace: none; margin-left: .25in; margin-top: 0; margin-bottom: 0"> +<span style="font-size: 10.0pt; font-family: Courier">}</span></p> +<p class="MsoNormal" style="text-autospace: none">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.</p> +</a> +<p class="subsection"><a name="_TocSectionDynamic_5">7.5 Determining if a Tool Chain is Installed</p> +<p class="subsection"><a name="_TocSectionDynamic_6">7.6 Defining Environment Variables</a></p> +<p>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.</p> +<p class="MsoNormal">The tool-integrator can provide Project-level and +Configuration-level environment variable suppliers separately: </p> +<p class="MsoNormal" style="margin-left: 0in">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 </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IConfigurationEnvironmentVariableSupplier{</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @variableName the variable mane</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param configuration configuration</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +environment variable provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * environment variables from within +the supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined environment instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* +ManagedBuildManager.getEnvironmentVariableProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching the variables for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the environment variables defined for the +higher levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the reference to the +IBuildEnvironmentVariable interface representing </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * the variable of a given name</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +IBuildEnvironmentVariable getVariable(String variableName, </p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 2.95in; margin-top: 0; margin-bottom: 0"> +IConfiguration configuration,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 2.95in; margin-top: 0; margin-bottom: 0"> +IEnvironmentVariableProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param configuration configuration</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +environment variable provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * environment variables from within +the supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined environment instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* +ManagedBuildManager.getEnvironmentVariableProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching the variables for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the environment variables defined for the +higher levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the array of +IBuildEnvironmentVariable that represents the environment variables</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +IBuildEnvironmentVariable[] getVariables (IConfiguration configuration,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 2.95in; margin-top: 0; margin-bottom: 0"> +IEnvironmentVariableProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<p class="MsoNormal" style="margin-left: 0in">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 </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IProjectEnvironmentVariableSupplier{</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @variableName the variable mane</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param project the managed project</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +environment variable provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * environment variables from within +the supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined environment instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* +ManagedBuildManager.getEnvironmentVariableProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching the variables for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the environment variables defined for the +higher levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the reference to the +IBuildEnvironmentVariable interface representing </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * the variable of a given name</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +IBuildEnvironmentVariable getVariable(String variableName, </p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 177.0pt; margin-top: 0; margin-bottom: 0"> +IManagedProject project,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 177.0pt; margin-top: 0; margin-bottom: 0"> +IEnvironmentVariableProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param project the managed project</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +environment variable provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * environment variables from within +the supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined environment instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* +ManagedBuildManager.getEnvironmentVariableProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching the variables for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the environment variables defined for the +higher levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the array of +IBuildEnvironmentVariable that represents the environment variables </span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +IBuildEnvironmentVariable[] getVariables (IManagedProject project,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 177.0pt; margin-top: 0; margin-bottom: 0"> +IEnvironmentVariableProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<p class="MsoNormal">The IBuildEnvironmentVariable interface returns information regarding an +individual environment variable. </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IBuildEnvironmentVariable{</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +public static final int ENVVAR_REPLACE = 1;</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +public static final int ENVVAR_REMOVE = 2;</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +public static final int ENVVAR_PREPEND = 3;</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +public static final int ENVVAR_APPEND = 4;</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> + </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> String +getName();</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> String +getValue();</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return one of the +IBuildEnvironmentVariable.ENVVAR_* operation types</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> int +getOperation();</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return if the variable can hold the +list of values this method returns the String representing</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * the delimiter that is used to separate values. +This information is used for the following:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * 1. in append and prepend operations:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * If the variable already exists and contains some +value the new </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * value will be calculated in the following way:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * For the “prepend” operation:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * <New value> = <the value from the +getValue() method><delimiter><Old value></span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * For the “append” operation:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * <New value> = <Old value><delimiter><the +value from the getValue() method></span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The Environment Variable Provider will also +remove the duplicates of “sub-values” </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * in the resulting value. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * For example:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * If the current value is +“string1:string2:string3”, the getDelimiter() method returns “:” </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and getValue() method returns “string4:string2” +the new value will contain:</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * For the “prepend” operation: +“string4:string2:string1:string3”</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * For the “append” operation: +“string1:string3:string4:string2”</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * 2. Since the environment variables are also +treated as build macros the delimiter is also used </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * by the BuildMacroProvider to determine the type +of the macro used to represent the</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * given environment variable. If the variable has +the delimiter it is treated as the Text-List macro</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * otherwise it is treated as the Text macro. (See +Build Macro design for more details)</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * To specify that no delimiter should be used, the +getDelimiter() method should</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * return null or an empty string</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> String +getDelimiter();</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<a name="_TocSectionDynamic_14"> +<p class="subsection"><a name="_TocSectionDynamic_7">7.7 Defining a Build Path Resolver</a> </p> +<p class="MsoNormal" style="margin-left: 0in">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 of resolving the environment variable values to build paths.</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IBuildPathResolver {</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param pathType one of the +IEnvVarBuildPath.BUILDPATH _xxx</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param variableName represents the name of the +variable that holds the build paths</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param variableValue represents the value of the +value specified with the </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * variableName argument</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param configuration represents configuration +for which the build paths are requested</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +String[] resolveBuildPaths(</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> + int pathType,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 70.8pt; margin-top: 0; margin-bottom: 0"> +String variableName, </p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 70.8pt; margin-top: 0; margin-bottom: 0"> +String variableValue,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 70.8pt; margin-top: 0; margin-bottom: 0"> +IConfiguration configuration);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<p class="subsection"><a name="_TocSectionDynamic_8">7.8 Defining Build Macros</a></p> +<p class="MsoNormal">The IConfigurationBuildMacroSupplier interface and the IProjectBuildMacroSupplier interface allow a tool-integrator to define build +macros and their values.</p> +<p class="MsoNormal">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</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IConfigurationBuildMacroSupplier {</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @ macroName the macro mane</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param configuration configuration</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +build macro provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * build macros from within the +supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined build macros instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* ManagedBuildManager.getBuildMacroProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching macros for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the build macros defined for the higher +levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the reference to the +IBuildMacro interface representing </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * the build macro of a given name or null if the +macro of that name is not defined</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +IBuildMacro getMacro(String macroName, </p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 70.8pt; margin-top: 0; margin-bottom: 0"> +IConfiguration configuration, </p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 70.8pt; margin-top: 0; margin-bottom: 0"> +IBuildMacroProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param configuration configuration</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +build macro provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * build macros from within the +supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined build macros instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* ManagedBuildManager.getBuildMacroProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching macros for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the build macros defined for the higher +levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the IBuildMacro[] array +representing defined macros </span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +IBuildMacro[] getMacros(IConfiguration configuration,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 70.8pt; margin-top: 0; margin-bottom: 0"> +IBuildMacroProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IProjectBuildMacroSupplier {</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @ macroName the macro mane</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param project the instance of the +managed project</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +build macro provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * build macros from within the +supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined build macros instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* ManagedBuildManager.getBuildMacroProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching macros for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the build macros defined for the higher +levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the reference to the +IBuildMacro interface representing </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * the build macro of a given name or null if the +macro of that name is not defined</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +IBuildMacro getMacro(String macroName, </p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 106.2pt; margin-top: 0; margin-bottom: 0"> +IManagedProject project,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 106.2pt; margin-top: 0; margin-bottom: 0"> +IBuildMacroProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param project the instance of the +managed project</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @param provider the instance of the +build macro provider to be used for querying the</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * build macros from within the +supplier. The supplier should use this provider to obtain</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* the already defined build macros instead of using +the “default” provider returned by the</span></p> +<p class="MsoNormal" style="text-indent: 3.0pt; margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366">* ManagedBuildManager.getBuildMacroProvider().</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * The provider passed to a supplier will ignore +searching macros for the levels </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * higher than the current supplier level, will +query only the lower-precedence suppliers </span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * for the current level and will query all +suppliers for the lower levels. </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * This is done to avoid infinite loops that could +be caused if the supplier calls the provider </span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * and the provider in turn calls that supplier +again. Also the supplier should not know anything</span></p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * about the build macros defined for the higher +levels.</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @return the IBuildMacro[] array +representing defined macros </span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-left: 35.4pt; margin-top: 0; margin-bottom: 0"> +IBuildMacro[] getMacros(IManagedProject project,</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 106.2pt; margin-top: 0; margin-bottom: 0"> +IBuildMacroProvider provider);</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<p class="MsoNormal">The IBuildMacro interface returns information regarding an +individual build macro. </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">public interface +IBuildMacro{</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_TEXT = 1; //can hold any text string</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_TEXT_LIST = 2; //can hold the array of text string values</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_PATH_FILE = 3; //can hold file path</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_PATH_FILE_LIST = 4; //can hold the array of file path +values</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_PATH_DIR = 5; //can hold dir path</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_PATH_DIR_LIST = 6; //can hold the array of dir path +values</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_PATH_ANY = 7; //can hold both file and dir path</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> public +static final int VALUE_PATH_ANY_LIST = 8; //can hold the array of PATH_ANY</p> +<p class="MsoNormal" style="text-indent: 35.4pt; margin-left: 283.2pt; margin-top: 0; margin-bottom: 0"> +// values </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> String +getName();</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @returns IBuildMacro.VALUE_xxx</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> int +getMacroValueType();</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @throws BuildMacroException if macro +holds StringList-type value</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> String +getStringValue() throws BuildMacroException;</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> </p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> * @throws BuildMacroException if macro +holds single String-type value</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="color: #003366"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +String[] getStringListValue() throws BuildMacroException;</p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0">}</p> +<p class="subsection"><a name="_TocSectionDynamic_9">7.9 Defining a Configuration Name Provider</p> +<p class="subsection"><a name="_TocSectionDynamic_10">7.10 Defining an Output Name Provider</p> +<p>You can specify an output name provider for an outputType. You must specify +and supply a class that implements the <code>IManagedOutputNameProvider</code> +interface shown below. The class name is assigned to the outputType element, +nameProvider attribute. </p> +<p class="MsoNormal"><span style="font-size:10.0pt;font-family:Courier">public +interface IManagedOutputNameProvider{</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> /**</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> * Returns the output names +corresponding to the primary input name(s)</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> *</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> * @returns String[]</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> */</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier"> IPath[] +getOutputPaths(ITool tool, IPath[] primaryInputs);</span></p> +<p class="MsoNormal" style="margin-top: 0; margin-bottom: 0"> +<span style="font-size:10.0pt;font-family:Courier">}</span></p> +<p class="MsoNormal" style="margin-top: 6px; margin-bottom: 0">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.</p> +</a> +<p class="subsection"><a name="_TocSectionDynamic_11">7.11 Defining an Option Value Handler</p> +<p class="subsection"><a name="_TocSectionDynamic_12">7.12 Defining an Option Applicability Calculator</p> +<p class="subsection"><a name="_TocSectionDynamic_13">7.13 Defining a Dynamic Element Provider</p> +<p class="section"><a name="_TocSectionAdvanced"> Advanced Features</a></p> +<p class="subsection"><a name="_TocSectionAdvanced_1">8.1 Converting CDT 2.0 Manifest Files</p> +</a> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The figure below shows the CDT 2.0 +object model. The CDT 3.0 object model is shown earlier in the document.</p> +<p class="MsoNormal"> <img style="border: 0px solid ;" + src="./image004.gif" + title="Figure 2 Managed build model elements" + alt="UML model of schema elements"></p> +<h5>Figure 12 CDT 2.0 Managed build model elements</h5> +<p class="MsoNormal">Below are the detailed instructions for converting a +manifest from the old model to the new model.</p> +<h3 class="subsection">8.1.1 MBS Manifest Extension Point</h3> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<h3 class="subsection">8.1.2 MBS 2.0 Target Element</h3> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The Target attributes <i>name, id, +isTest </i>and<i> isAbstract</i> should be transferred to a new ProjectType +element in the new model. The <i>id</i> 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.</p> +<h3 class="subsection">8.1.3 MBS 2.0 Configuration Element</h3> +<p class="MsoNormal" style="margin-top:6.0pt">The Configuration children of the +Target element are made Configuration children of the new ProjectType element. +The Configuration <i>name </i>and <i> id</i> attributes should be transferred +with the Configuration. The <i>id</i> assigned to the Configuration must remain +unchanged in order to support the conversion of old model project files. The +Target attributes <i>artifactName, cleanCommand </i>and <i>errorParsers </i> +attributes should be transferred to the Configuration element. The Target <i> +defaultExtension </i>attribute should be transferred to the Configuration +element +as the <i>artifactExtension </i>attribute (Note the name change).</p> +<p class="MsoNormal" style="margin-top:6.0pt">A new ToolChain element should be +created as the child of each Configuration element. The <i>name</i> and <i>id</i> +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 <i>id</i> of your new ToolChain must be the parent +Configuration <i>id, </i>appended with “.toolchain”. The Target <i>isAbstract, +osList, </i>a<i>rchList</i> and <i>scannerInfoCollector </i>attributes are +transferred to the ToolChain element.</p> +<p class="MsoNormal" style="margin-top:6.0pt">A new Builder element can be +created as the child of each ToolChain element. The <i>name</i> and <i>id</i> 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 <i>id</i> of your new Builder must be the parent +Configuration <i>id, </i>appended with “.builder”. The target <i>isAbstract</i> +attribute is transferred to the Builder element. <i> </i>The target <i> +makeCommand</i> attribute should be transferred to the Builder element as the <i> +command </i>attribute (Note the name change).<i> </i>The target <i> +makeArguments </i>attribute should be transferred to the Builder element as the +<i>arguments </i>attribute (Note the name change).<i> </i>The target <i> +makefileGenerator </i>attribute should be transferred to the Builder element as +the <i>buildfileGenerator </i>attribute (Note the name change).</p> +<p class="MsoNormal" style="margin-top:6.0pt">A new TargetPlatform element can be +created as the child of each ToolChain element. The <i>name</i> and <i>id</i> 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 <i>id</i> of your new TargetPlatform must be the +parent Configuration <i>id, </i>appended with “.targetplatform”. The target <i> +isAbstract</i> and <i>binaryParser </i>attributes are transferred to the +TargetPlatform element. The TargetPlatform element contains <i>osList </i>and <i> +archList</i> attributes that specify the architecture(s) and operating system(s) +on which the Configuration’s build artifact(s) execute. You can transfer the +Target <i>osList </i>and <i>archList</i> attributes if appropriate.</p> +<h3 class="subsection">8.1.4 MBS 2.0 Tool Element</h3> +<p class="MsoNormal">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The <i>id</i> assigned to the Tool +must remain unchanged in order to support the conversion of old model project +files. The <i>outputs </i>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 (<i>superClass</i>).</p> +<h3 class="subsection">8.1.5 MBS 2.0 ToolReference Element</h3> +<p class="MsoNormal">The new model does not define a ToolReference element. +Instead, a Tool element can specify the <i>superClass</i> 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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 <i>id </i>attribute to +the Tool <i>superClass </i>attribute.</p> +<p class="MsoNormal" style="margin-top:6.0pt">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.</p> +<h3 class="subsection">8.1.6 MBS 2.0 Option Element</h3> +<p class="MsoNormal" style="margin-top:6.0pt">All of the old model Option +attributes are supported by the new model.</p> +<p class="MsoNormal" style="margin-top:6.0pt">The <i>id</i> assigned to the +Option must remain unchanged in order to support the conversion of old model +project files.</p> +<h3 class="subsection">8.1.7 MBS 2.0 OptionReference Element</h3> +<p class="MsoNormal">The new model does not define an OptionReference element. +Instead, an Option element can specify the <i>superClass</i> 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.</p> +<p class="MsoNormal" style="margin-top:6.0pt">All OptionReference elements should +be converted to Option elements, transferring the value of the <i>id </i> +attribute to the Option <i>superClass </i>attribute.</p> +<h3 class="subsection">8.1.8 MBS 2.0 OptionCategory, EnumeratedOptionValue, ListOptionValue +Elements</h3> +<p class="MsoNormal">There are no changes to these elements.</p> +<h3 class="subsection">8.1.9 MBS 2.0 DynamicElementProvider Element</h3> +<p class="MsoNormal">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.</p> +</body> +</html>
\ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image002.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image002.gif Binary files differnew file mode 100644 index 00000000000..f54d599e83d --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image002.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image003.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image003.gif Binary files differnew file mode 100644 index 00000000000..7322aa92b5c --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image003.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image004.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image004.gif Binary files differnew file mode 100644 index 00000000000..9748f468934 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image004.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image024.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image024.gif Binary files differnew file mode 100644 index 00000000000..d3347e1850f --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image024.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image026.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image026.gif Binary files differnew file mode 100644 index 00000000000..a92ccd536fd --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image026.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif Binary files differnew file mode 100644 index 00000000000..443cd8b87da --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image028.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image030.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image030.gif Binary files differnew file mode 100644 index 00000000000..cd10890dcb0 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image030.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif Binary files differnew file mode 100644 index 00000000000..d1a9035bc43 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image031.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image032.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image032.gif Binary files differnew file mode 100644 index 00000000000..958926a1273 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image032.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image034.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image034.gif Binary files differnew file mode 100644 index 00000000000..1f8a82b0a00 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image034.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image035.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image035.gif Binary files differnew file mode 100644 index 00000000000..9f2a4c92953 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image035.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image036.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image036.gif Binary files differnew file mode 100644 index 00000000000..f3107f521e1 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image036.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif Binary files differnew file mode 100644 index 00000000000..d4bc0a0c049 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image038.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image040.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image040.gif Binary files differnew file mode 100644 index 00000000000..986b0936480 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image040.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image042.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image042.gif Binary files differnew file mode 100644 index 00000000000..46cdd9b5ca0 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image042.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image044.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image044.gif Binary files differnew file mode 100644 index 00000000000..569e4433dc8 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image044.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image060.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image060.gif Binary files differnew file mode 100644 index 00000000000..b7de98c5e1c --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image060.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image062.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image062.gif Binary files differnew file mode 100644 index 00000000000..41ce3b36ea6 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image062.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image064.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image064.gif Binary files differnew file mode 100644 index 00000000000..c1ff28bba21 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image064.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image066.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image066.gif Binary files differnew file mode 100644 index 00000000000..e18a0bc3628 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image066.gif diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image068.gif b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image068.gif Binary files differnew file mode 100644 index 00000000000..84ad44f1342 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/image068.gif |