Add the assignToOption attribute and update other attribute descriptions

doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html

@@ -86,7 +86,7 @@ managed build system and how to extend it.</font></td>
     <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%" rowspan="5">Revision Date</td>
     <td width="50%">10/21/2003 - Version: 0.1.0</td>
   </tr>
   <tr>
@@ -99,8 +99,11 @@ managed build system and how to extend it.</font></td>
     <td width="50%">8/10/2005 - Version 3.0.0</td>
   </tr>
   <tr>
-    <td width="50%" rowspan="4">Change History</td>
+    <td width="50%">9/28/2005 - Version 3.0.1</td>
-    <td width="50%">0.1.0 - Document Creation</td>
+  </tr>
+  <tr>
+    <td width="50%" rowspan="5">Change History</td>
+    <td width="50%" height="22">0.1.0 - Document Creation</td>
   </tr>
   <tr>
     <td width="50%">2.0.0 - Updated for CDT 2.0</td>
@@ -111,6 +114,9 @@ managed build system and how to extend it.</font></td>
   <tr>
     <td width="50%">3.0 - Updated for CDT 3.0</td>
   </tr>
+  <tr>
+    <td width="50%">3.0.1 - Updated for CDT 3.0.1</td>
+  </tr>
 </table>
 <br>
 <!-- End of Document Header --><!-- Table of Contents -->
@@ -664,6 +670,8 @@ ancestor that specifies a value for the attribute.</p>
 	indicate attributes that are deprecated in CDT 3.0.&nbsp; Each of these 
 	attributes describes the new method to use to obtain equivalent 
 	functionality.</li>
+	<li>Attributes highlighted in <span style="background-color: #00FF00">green</span> 
+	implement functionality that is new for CDT 3.0.1.</li>
 	<li>The &quot;Required&quot; column can contain 3 values.&nbsp; &quot;Yes&quot; means 
 that the attribute is required by the schema for every instance of the element.&nbsp; 
 &quot;No&quot; means that the attribute is never required and an appropriate default is 
@@ -930,7 +938,7 @@ project/configurations for modification by the user.</p>
  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>
+UI. This is the name that the user entered in the New Project wizard.</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">
@@ -1336,7 +1344,7 @@ the schema table below.</p>
       <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. &nbsp;The 
+		The comma separated list of operating systems that the tool-chain is supported on. &nbsp;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 
@@ -1358,7 +1366,7 @@ the schema table below.</p>
  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. &nbsp;The 
+		The comma separated list of architectures that the tool-chain is supported on. &nbsp;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>
@@ -1619,8 +1627,11 @@ track of this specific builder.</font></td>
       <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.&nbsp; The default is 
+      <font face="Arial">Specifies the default command to start the build 
-		&#8220;make&#8221;.</font></td>
+		utility for your toolchain. If the user changes this through the UI, the 
+		overriden value will be stored in the project build file. The build 
+		model will default to this value if the user ever resets a change.&nbsp; 
+		The default is &quot;make&quot;.</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>
@@ -1631,8 +1642,12 @@ track of this specific builder.</font></td>
       <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 
+      <font size="2" face="Arial">Specifies the additional, default arguments 
-		line.&nbsp; The default is &#8220;-k&#8221;.</font></td>
+		that will be passed to the build utility when it is called by the 
+		builder. If the user changes the flags through the UI, the overriden 
+		value will be stored in the project build settings file. The build model 
+		will default to this value if the user ever resets a change. The default 
+		is &#8220;-k&#8221;.</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>
@@ -1643,8 +1658,11 @@ track of this specific builder.</font></td>
       <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 
+      Specifies the default list of error parsers used by the builder. These 
-		to be used with this builder.</font></td>
+		error parsers are added to this list specified by the parent tool-chain. 
+		It is an ordered, semi-colon separated list of parser IDs. The order 
+		specifies the order in which the error parsers are invoked during a 
+		build.</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">
@@ -2084,7 +2102,9 @@ the workspace.</p>
       <tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">
 		The list of operating systems that is valid for this target platform. 
 		&nbsp;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>
+		is the string values returned by Platform.getOS().&nbsp; </font></span></tt><font size="2">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 &quot;all&quot;, then 
+		the target platform supports all operating systems.</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">
@@ -2101,7 +2121,9 @@ the workspace.</p>
       <tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">
 		The list of architectures that is valid for this target platform. &nbsp;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>
+		is the string values returned by Platform.getOSArch().&nbsp; </font></span></tt><font size="2">I</font><tt><span style="font-size: 10.0pt"><font face="arial, helvetica, geneva">f 
+		the archList attribute is not specified, or if the value is &quot;all&quot;, then 
+		the target platform supports all architectures.</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">
@@ -2350,8 +2372,14 @@ the '-o' flag, whereas the archiver that creates libraries does not.</p>
       <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.&nbsp; The default 
+      Filters the display (and use) of the tool by the nature of the project. 
-		value is &quot;both&quot;.</td>
+		Selecting a value of &amp;apos;cnature&amp;apos; insures that the tool will be 
+		displayed IFF there is a cnature associated with the project. A ccnature 
+		will filter this tool out. If &amp;apos;ccnature&amp;apos; is selected, the tool 
+		will only be available for C++ projects. If &amp;apos;both&amp;apos; is 
+		selected, the tool will be displayed when either nature is present. This 
+		attribute is required if it is not inherited from its superClass. The 
+		default value is &quot;both&quot;.</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">
@@ -2385,7 +2413,8 @@ Gnu C compiler, or g++ for the Gnu C++ compiler.</td>
 		pattern consists of the replaceable variables COMMAND, FLAGS, 
 		OUTPUT_FLAG, OUTPUT_PREFIX, OUTPUT and INPUTS.&nbsp; The default command line 
 		pattern is <br>
-		${COMMAND} ${FLAGS} ${OUTPUT_FLAG}${OUTPUT_PREFIX}${OUTPUT} ${INPUTS}<br>
+		${COMMAND} ${FLAGS} ${OUTPUT_FLAG}${OUTPUT_PREFIX}${OUTPUT} ${INPUTS}, 
+		except when customBuildStep is true, where the default is $(COMMAND).&nbsp;
 		White space and other characters are significant and are copied to the 
 		generated command.</font></td>
       <td
@@ -2714,10 +2743,9 @@ attributes of the InputType element are described in the table below.</p>
       <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 
+      The id of an Option element that is used on the command line to identify 
-		is used on the command line to identify this input.&nbsp; The default is to 
+		inputs of this type. If specified, the name(s) of the input files for 
-		not use a command line option and to assign this input to the ${Inputs} 
+		this input type are taken from the value specified for the option.</td>
-		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">
@@ -2726,6 +2754,25 @@ attributes of the InputType element are described in the table below.</p>
     <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: #00FF00">assignToOption</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 Option element whose value is to be assigned to the file(s) 
+		calculated for this input type. The default is not to assign the input 
+		file(s) to a command line option but to assign the files to the 
+		${Inputs} part of the command line. Note that the option value is only 
+		updated during build file generation and therefore could be out of sync 
+		with the project until build file generation occurs.</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">
+      &nbsp;</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
@@ -2942,7 +2989,7 @@ attribute.</p>
       <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>
+      The name of the output 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">
@@ -3007,7 +3054,8 @@ attribute.</p>
 		output.&nbsp; The default is to use the Tool &#8220;outputFlag&#8221; attribute if 
 		primaryOutput is True.&nbsp; 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>
+		command line.&nbsp; If specified, the nameProvider, namePattern and 
+		outputNames are 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;"
  valign="top">
@@ -3022,7 +3070,8 @@ attribute.</p>
  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.&nbsp; The default is False.</td>
+		tool.&nbsp; The default is False.&nbsp; If True, the nameProvider 
+		attribute or outputNames attribute must be 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">
@@ -3038,7 +3087,7 @@ attribute.</p>
  valign="top">
       Id of the input type that is used in determining the build &#8220;rules&#8221; for the 
 		output type and for the default name of the output file.&nbsp; The default is 
-		the input type with primaryInput == true..</td>
+		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">
@@ -3086,7 +3135,8 @@ attribute.</p>
  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>
+		created by the output type.&nbsp; If specified, the namePattern 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;"
  valign="top">
@@ -3222,9 +3272,9 @@ Options'. This will be the name the user sees displayed in the UI.</p>
       <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>Option categories can be nested inside other option
+      <p>Option categories can belong to a tool, a toolChain or be nested inside 
-categories. This is the ID of the owner of the category.&nbsp; The default owner 
+		other option categories. This is the ID of the owner of the category.&nbsp; The default owner 
-		if the parent tool.</p>
+		if the parent tool or tool-chain.</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;"
@@ -3586,7 +3636,19 @@ can be the id of the tool which is also a category.&nbsp; The default category
       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>
+      General options can be one of the following types; 'string' for catch-all 
+		entries for options that cannot be easily defined any other way, 'string 
+		list' for entries that consist of a list of values such as defined 
+		symbols or paths, 'boolean' for options that have two values, and 
+		'enumerated' for options that are one-of a list of values.<br>
+		<br>
+		Additional special types exist to flag options of special relevance to 
+		the build model; 'include', 'libs', 'userObjs' and 'definedSymbols'. You 
+		can pre-populate with optionValues, and they will display in the UI the 
+		same way the 'stringList' options do. The build model will look 
+		specifically for these value types when clients query for include paths 
+		and preprocessor defines. The makefile generator treats the libs and 
+		userObjs entries differently than other stringLists.</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>
@@ -3598,7 +3660,8 @@ can be the id of the tool which is also a category.&nbsp; The default category
       <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>
+		default configuration.&nbsp; </font>For options containing a Boolean 
+		value, the string &#8216;true&#8217; is treated as true, any other value as 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; vertical-align: top;" height="18">
       no</td>
@@ -3663,7 +3726,7 @@ False.</td>
  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)
+ valign="top">This value is used for string and stringlist (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
@@ -3794,8 +3857,12 @@ clients of the build model that specifically request them.</p>
       <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
+      <p>This attribute flags the list value as a built-in value as opposed to 
-the value defined as read-only.</p>
+		something the user has entered. Built-ins will not be passed to clients 
+		that generate command lines (like the makefile generator). However, 
+		clients that need to take these settings into account (like the indexing 
+		service), will receive these settings. These values will appear grey in 
+		the UI.</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;">
@@ -3957,7 +4024,7 @@ attributes are specified in the schema table below.</p>
  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.&nbsp; The default value is false.&nbsp; The 
-		resourceConfiguration element should retain its tool children, if any 
+		resourceConfiguration element retains 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;">