From 880cbc564ec60cb475d12e094abcc467409cb87c Mon Sep 17 00:00:00 2001 From: Leo Treggiari Date: Wed, 10 Aug 2005 18:48:12 +0000 Subject: [PATCH] Another update to MBS Extensibility Guide --- .../Managed_Build_Extensibility.html | 1472 +++++++++++------ 1 file changed, 932 insertions(+), 540 deletions(-) diff --git a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html index 6d14ae4510c..7f92e93a8af 100644 --- a/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html +++ b/doc/org.eclipse.cdt.doc.isv/guide/mbs/extensibilityGuide/Managed_Build_Extensibility.html @@ -77,7 +77,7 @@ managed build system and how to extend it. - +
@@ -3215,35 +3215,37 @@ Options'. This will be the name the user sees displayed in the UI.

+ 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" height="52"> +

no

Authors Sean Evoy

owner

Option categories can be nested inside other option -categories. This is the ID of the owner of the category.

+categories. This is the ID of the owner of the category.  The default owner + if the parent tool.

 -

yes

+ 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
+ valign="top" height="53"> icon + valign="top" height="52"> Path to a 16x16 pixel big icon that is to be displayed instead of the default icon.  The path is relative to the plug-in directory which defines the build definitions. - no
@@ -3571,7 +3573,9 @@ build model.

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. +can be the id of the tool which is also a category.  The default category + is the parent tool.  Note that an optionCategory id must be + supplied as the value for an option that is a child of a toolChain. no @@ -3670,40 +3674,42 @@ needed. resourceFilter 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. no valueHandler   + 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 IManagedOptionValueHandler + interface.  This interface is used to dynamically manage the value + of an option.  See § 7.11. no valueHandlerExtra Argument   + 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 extra text string that is passed into the valueHandler. no @@ -3716,7 +3722,7 @@ needed. runtime whether the option is visible, enabled, and used in command line generation. This class must implement the IOptionApplicability interface. If no calculator is specified then the option is always - visible, enabled, and used in command line generation. + visible, enabled, and used in command line generation.  See § 7.12. no @@ -4505,6 +4511,37 @@ 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.

+

5.1.6 Makefile Generator Constraints

+

The current implementation of the default Gnu makefile generator assumes a +set of constraints that must be met in your tool-chain definition in order for +it to generate valid makefiles:

+
    +
  1. Input files must be specified via project relative or absolute paths.
    2. +
  2. Output files must be specified via configuration build directory + relative or absolute paths.
    3. +
  3. A tool with a primary input type where the multipleOfType attribute is + set to true executes once during the build using all of the project + resources and generated outputs that match its input file extensions.  + A subset of the full set of input files can be defined using the + buildVariable attribute in the inputType of the tool, and the outputType of + other tools.
    4. +
  4. If any inputType of a tool has the multipleOfType attribute set to true, + then primary inputType of the tool must have the multipleOfType attribute + set to true.
    5. +
  5. A tool with a primary input type where the multipleOfType attribute is + set to false executes per project resource and generated output that match + its input file extensions.  A subset of the full set of input files can + be defined using the buildVariable attribute in the inputType of the tool, + and the outputType of other tools.
    6. +
  6. A tool must be able to determine all of its output file names and + dependencies given the name(s) of its primary input file(s).
    7. +
  7. The main makefile contains the rules for the "target" tool, for all + tools with a primary input type where the multipleOfType attribute is set to + true, and for any tool that consumes the output of these tools.
    8. +
  8. Each fragment makefile contains the rules for all project resources in + the current directory and for generated outputs that are not consumed by + tools where the multipleOfType attribute is set to true.
    9. +

6 Tutorial: An Example Tool Integration

One of the features of the MBS is that you can add custom project-types and tool @@ -5188,67 +5225,66 @@ that implements the IManagedCommandLineGenerator interface.  The class name is assigned to the tool element, commandLineGenerator attribute.

-public interface +public interface IManagedCommandLineGenerator {

-   public +   public IManagedCommandLineInfo generateCommandLineInfo(

-               ITool tool,

+               ITool tool,

-               String +               String commandName,

-               String[] +               String[] flags,

-               String +               String outputFlag,

-               String +               String outputPrefix,

-               String +               String outputName,

-               String[] +               String[] inputResources,

-               String +               String commandPattern);

-}

+}

 

-public interface +public interface IManagedCommandLineInfo {

-   public String +   public String getCommandLine();

-   public String +   public String getCommandName();

-   public String getFlags();

+   public String getFlags();

-   public String +   public String getOutputFlag();

-   public String +   public String getOutputPrefix();

-   public String +   public String getOutputName();

-   public String +   public String getInputResources();

-}

-

MBS calls -IManagedCommandLineGenerator.generateCommandLineInfo to generate the command +}

+

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

@@ -5263,14 +5299,17 @@ given project type are not supported the project type is treated as unsupported.

In order to provide this functionality, the “isToolChainSupported” attribute in the toolChain definition must be specified. The value of this attribute should be set to the -name of the class which implements the IManagedIsToolChainSupported +name of the class which implements the IManagedIsToolChainSupported interface.

-

public interface -IManagedIsToolChainSupported{

-

            boolean +

+public interface +IManagedIsToolChainSupported{

+

+        boolean isSupported(IToolChain toolChain, PluginVersionIdentifier version, String -instance);

-

}

+instance);

+

+}

 

The version argument specifies the version of the ToolChain, or null if the ToolChain does @@ -5290,630 +5329,815 @@ Configuration-level environment variable suppliers separately: 

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 +name of the class which implements the IConfigurationEnvironmentVariableSupplier interface

-

public interface -IConfigurationEnvironmentVariableSupplier{

-            /**

+public interface +IConfigurationEnvironmentVariableSupplier{

-             *

+  /**

-             * @variableName the variable mane

+   *

-             * @param configuration configuration

+   * @variableName the variable mane

-             * @param provider the instance of the -environment variable provider to be used for querying the

+   * @param configuration configuration

-             * environment variables from within -the supplier. The supplier should use this provider to obtain

-

-* the already defined environment instead of using -the “default” provider returned by the

-

-* -ManagedBuildManager.getEnvironmentVariableProvider().

-

- * The provider passed to a supplier will ignore -searching the variables for the levels

-

+   * @param provider the instance of the +environment variable provider to be used for querying the

+

+   * environment variables from within +the supplier. The supplier should use this provider to obtain

+

+  + * the already defined environment instead of using +the “default” provider returned by the

+

+  + * +ManagedBuildManager.getEnvironmentVariableProvider().

+

+   * +The provider passed to a supplier will ignore +searching the variables for the levels

+

+   * higher than the current supplier level, will -query only the lower-precedence suppliers

-

+query only the lower-precedence suppliers

+

+   * for the current level and will query all -suppliers for the lower levels.

-

+suppliers for the lower levels.

+

+   * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

+be caused if the supplier calls the provider

+

+   * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

+again. Also the supplier should not know anything

+

+   * about the environment variables defined for the -higher levels.

+higher levels.

-             * @return the reference to the -IBuildEnvironmentVariable interface representing

-

- * the variable of a given name

+ +   * @return the reference to the IBuildEnvironmentVariable interface representing +

-             */

-

            -IBuildEnvironmentVariable getVariable(String variableName,

+  + * the variable of a given name

+

+   */

+

+   IBuildEnvironmentVariable getVariable(String variableName, +

-IConfiguration configuration,

+IConfiguration configuration,

-IEnvironmentVariableProvider provider);

+IEnvironmentVariableProvider provider);

 

-            /**

+  /**

-             * @param configuration configuration

+   * @param configuration configuration

-             * @param provider the instance of the -environment variable provider to be used for querying the

+   * @param provider the instance of the +environment variable provider to be used for querying the

-             * environment variables from within -the supplier. The supplier should use this provider to obtain

-

-* the already defined environment instead of using -the “default” provider returned by the

-

-* -ManagedBuildManager.getEnvironmentVariableProvider().

-

+   * environment variables from within +the supplier. The supplier should use this provider to obtain

+

+   * the already defined environment instead of using +the “default” provider returned by the

+

+   +* +ManagedBuildManager.getEnvironmentVariableProvider().

+

+   * The provider passed to a supplier will ignore -searching the variables for the levels

-

+searching the variables for the levels

+

+   * higher than the current supplier level, will -query only the lower-precedence suppliers

-

+query only the lower-precedence suppliers

+

+   * for the current level and will query all -suppliers for the lower levels.

-

+suppliers for the lower levels. 

+

+   * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

+be caused if the supplier calls the provider

+

+   * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

+again. Also the supplier should not know anything

+

+   * about the environment variables defined for the -higher levels.

+higher levels.

-             * @return the array of -IBuildEnvironmentVariable that represents the environment variables

+   * @return the array of IBuildEnvironmentVariable that represents the environment variables

-             */

-

            -IBuildEnvironmentVariable[] getVariables (IConfiguration configuration,

+   */

+

+   IBuildEnvironmentVariable[] getVariables (IConfiguration configuration,

-IEnvironmentVariableProvider provider);

-

}

+IEnvironmentVariableProvider provider);

+

+}

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

-

public interface -IProjectEnvironmentVariableSupplier{

+name of the class which implements the IProjectEnvironmentVariableSupplier +interface.

-            /**

+public interface +IProjectEnvironmentVariableSupplier{

-             *

+ +  /**

-             * @variableName the variable mane

+   * @variableName the variable mane

-             * @param project the managed project

+   * @param project the managed project

-             * @param provider the instance of the -environment variable provider to be used for querying the

+   * @param provider the instance of the +environment variable provider to be used for querying the

-             * environment variables from within -the supplier. The supplier should use this provider to obtain

-

-* the already defined environment instead of using -the “default” provider returned by the

-

-* -ManagedBuildManager.getEnvironmentVariableProvider().

-

+   * environment variables from within +the supplier. The supplier should use this provider to obtain

+

+   +* the already defined environment instead of using +the “default” provider returned by the

+

+   +* +ManagedBuildManager.getEnvironmentVariableProvider().

+

+   * The provider passed to a supplier will ignore -searching the variables for the levels

-

+searching the variables for the levels

+

+   * higher than the current supplier level, will -query only the lower-precedence suppliers

-

+query only the lower-precedence suppliers

+

+   * for the current level and will query all -suppliers for the lower levels.

-

+suppliers for the lower levels.

+

+   * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

+be caused if the supplier calls the provider

+

+   * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

+again. Also the supplier should not know anything

+

+   * about the environment variables defined for the -higher levels.

+higher levels.

-             * @return the reference to the -IBuildEnvironmentVariable interface representing

-

- * the variable of a given name

+ +   * @return the reference to the IBuildEnvironmentVariable interface representing +

-             */

-

            -IBuildEnvironmentVariable getVariable(String variableName,

+  + * the variable of a given name

+

+ +   */

+

+   IBuildEnvironmentVariable getVariable(String variableName, +

-IManagedProject project,

+IManagedProject project,

-IEnvironmentVariableProvider provider);

+IEnvironmentVariableProvider provider);

 

-            /**

+ +  /**

-             *

+ +   *

-             * @param project the managed project

+ +   * @param project the managed project

-             * @param provider the instance of the -environment variable provider to be used for querying the

+ +   * @param provider the instance of the +environment variable provider to be used for querying the

-             * environment variables from within -the supplier. The supplier should use this provider to obtain

-

-* the already defined environment instead of using -the “default” provider returned by the

-

-* -ManagedBuildManager.getEnvironmentVariableProvider().

-

+ +   * environment variables from within +the supplier. The supplier should use this provider to obtain

+

+   +* the already defined environment instead of using +the “default” provider returned by the

+

+   +* +ManagedBuildManager.getEnvironmentVariableProvider().

+

+   * The provider passed to a supplier will ignore -searching the variables for the levels

-

+searching the variables for the levels

+

+   * higher than the current supplier level, will -query only the lower-precedence suppliers

-

+query only the lower-precedence suppliers

+

+   * for the current level and will query all -suppliers for the lower levels.

-

+suppliers for the lower levels.

+

+   * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

+be caused if the supplier calls the provider

+

+   * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

+again. Also the supplier should not know anything

+

+   * about the environment variables defined for the -higher levels.

+higher levels.

-             * @return the array of -IBuildEnvironmentVariable that represents the environment variables

+ +   * @return the array of IBuildEnvironmentVariable that represents the environment variables +

-             */

-

            -IBuildEnvironmentVariable[] getVariables (IManagedProject project,

+ +   */

+

+   IBuildEnvironmentVariable[] getVariables (IManagedProject project,

-IEnvironmentVariableProvider provider);

-

}

-

The IBuildEnvironmentVariable interface returns information regarding an +IEnvironmentVariableProvider provider);

+

+}

+

The IBuildEnvironmentVariable interface returns information regarding an individual environment variable. 

-

public interface -IBuildEnvironmentVariable{

-

-public static final int ENVVAR_REPLACE = 1;

-

-public static final int ENVVAR_REMOVE = 2;

-

-public static final int ENVVAR_PREPEND = 3;

-

-public static final int ENVVAR_APPEND = 4;

+

+public interface +IBuildEnvironmentVariable{

+

+    +public static final int ENVVAR_REPLACE = 1;

+

+    +public static final int ENVVAR_REMOVE = 2;

+

+    +public static final int ENVVAR_PREPEND = 3;

+

+    +public static final int ENVVAR_APPEND = 4;

 

-

            String -getName();

-

 

-

            String -getValue();

+

+    String getName();

 

-            /**

-

-             * @return one of the -IBuildEnvironmentVariable.ENVVAR_* operation types

-

-             */

-

            int -getOperation();

+    String getValue();

 

-            /**

+ +   /**

-             * @return if the variable can hold the -list of values this method returns the String representing

-

- * the delimiter that is used to separate values. -This information is used for the following:

-

- *

-

- * 1. in append and prepend operations:

-

- * If the variable already exists and contains some -value the new

-

- * value will be calculated in the following way:

-

- * For the “prepend” operation:

-

- *         <New value> = <the value from the -getValue() method><delimiter><Old value>

-

- * For the “append” operation:

-

- *         <New value> = <Old value><delimiter><the -value from the getValue() method>

-

- *

-

- * The Environment Variable Provider will also -remove the duplicates of “sub-values”

-

- * in the resulting value.

-

- * For example:

-

- * If the current value is -“string1:string2:string3”, the getDelimiter() method returns “:”

-

- * and getValue() method returns “string4:string2” -the new value will contain:

-

- * For the “prepend” operation: -“string4:string2:string1:string3”

-

- * For the “append” operation: -“string1:string3:string4:string2”

-

- *

-

- * 2. Since the environment variables are also -treated as build macros the delimiter is also used

-

- * by the BuildMacroProvider to determine the type -of the macro used to represent the

-

- * given environment variable. If the variable has -the delimiter it is treated as the Text-List macro

-

- * otherwise it is treated as the Text macro. (See -Build Macro design for more details)

-

- *

-

- * To specify that no delimiter should be used, the -getDelimiter() method should

-

- * return null or an empty string

+ +    * @return one of the IBuildEnvironmentVariable.ENVVAR_* operation types

-             */

-

            String -getDelimiter();

-

}

+ +    */

+

+    int +getOperation();

+

 

+

+ +   /**

+

+ +    * @return if the variable can hold the +list of values this method returns the String representing

+

+   + * the delimiter that is used to separate values. +This information is used for the following:

+

+   + *

+

+   + * 1. in append and prepend operations:

+

+   + * If the variable already exists and contains some +value the new

+

+   + * value will be calculated in the following way:

+

+   + * For the “prepend” operation:

+

+   + *         <New value> = <the value from the +getValue() method><delimiter><Old value>

+

+   + * For the “append” operation:

+

+   + *         <New value> = <Old value><delimiter><the +value from the getValue() method>

+

+   + *

+

+   + * The Environment Variable Provider will also +remove the duplicates of “sub-values”

+

+   + * in the resulting value. +

+

+   + * For example:

+

+   + * If the current value is +“string1:string2:string3”, the getDelimiter() method returns “:” +

+

+   + * and getValue() method returns “string4:string2” +the new value will contain:

+

+   + * For the “prepend” operation: +“string4:string2:string1:string3”

+

+   + * For the “append” operation: +“string1:string3:string4:string2”

+

+   + *
+    * 2. Since the environment variables are also +treated as build macros the delimiter is also used

+

+   + * by the BuildMacroProvider to determine the type +of the macro used to represent the

+

+   + * given environment variable. If the variable has +the delimiter it is treated as the Text-List macro

+

+   + * otherwise it is treated as the Text macro. (See +Build Macro design for more details)

+

+   + *

+

+   + * To specify that no delimiter should be used, the +getDelimiter() method should
+    * return null or an empty string

+

+ +    */

+

+    String getDelimiter();

+

+}

7.7 Defining a Build Path Resolver 

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 +name of the class which implements the IBuildPathResolver interface.  This allows the tool-integrator to provide his/her own logic for resolving the environment variable values to build paths.

-

public interface -IBuildPathResolver {

+

+public interface +IBuildPathResolver {

 

-            /**

+ +   /**

-             *

+ +    *

-             * @param pathType one of the -IEnvVarBuildPath.BUILDPATH _xxx

-

- * @param variableName represents the name of the -variable that holds the build paths

-

- * @param variableValue represents the value of the -value specified with the

-

- *     variableName argument

-

- * @param configuration represents configuration -for which the build paths are requested

+ +    * @param pathType one of the +IEnvVarBuildPath.BUILDPATH _xxx

-             */

-

            -String[] resolveBuildPaths(

-

            -                        int pathType,

-

-String variableName,

-

-String variableValue,

-

-IConfiguration configuration);

-

}

+   + * @param variableName represents the name of the +variable that holds the build paths

+

+   + * @param variableValue represents the value of the +value specified with the

+

+   + *     variableName argument

+

+   + * @param configuration represents configuration +for which the build paths are requested

+

+ +    */

+

+    +String[] resolveBuildPaths(

+

+                 int pathType,

+

+                 +String variableName,

+

+                 +String variableValue,

+

+                 +IConfiguration configuration);

+

+}

 

See org.eclipse.cdt.managedbuilder.gnu.cygwin.CygwinPathResolver for an example of a -build path resolver.  It converts Cygwin paths to Windows paths.

+build path resolver.  It converts Cygwin-style paths to Windows paths.

7.8 Defining Build Macros

-

The IConfigurationBuildMacroSupplier interface and the IProjectBuildMacroSupplier interface allow a tool-integrator to define build +

The IConfigurationBuildMacroSupplier interface and the +IProjectBuildMacroSupplier interface allow a tool-integrator to define build macros and their values.

-

All methods of the IConfigurationBuildMacroSupplier +

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

-

public interface -IConfigurationBuildMacroSupplier {

-            /**

+public interface +IConfigurationBuildMacroSupplier {

-             *

+   /**

-             * @ macroName the macro mane

+ +    *

-             * @param configuration configuration

+ +    * @ macroName the macro name

-             * @param provider the instance of the -build macro provider to be used for querying the

+ +    * @param configuration configuration

-             * build macros from within the -supplier. The supplier should use this provider to obtain

-

-* the already defined build macros instead of using -the “default” provider returned by the

-

-* ManagedBuildManager.getBuildMacroProvider().

-

- * The provider passed to a supplier will ignore -searching macros for the levels

-

- * higher than the current supplier level, will -query only the lower-precedence suppliers

-

- * for the current level and will query all -suppliers for the lower levels.

-

- * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

- * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

- * about the build macros defined for the higher -levels.

+ +    * @param provider the instance of the +build macro provider to be used for querying the

-             * @return the reference to the -IBuildMacro interface representing

-

- * the build macro of a given name or null if the -macro of  that name is not defined

+ +    * build macros from within the +supplier. The supplier should use this provider to obtain

-             */

-

-IBuildMacro getMacro(String macroName,

+    +* the already defined build macros instead of using +the “default” provider returned by the

+

+    +* ManagedBuildManager.getBuildMacroProvider().

+

+   + * The provider passed to a supplier will ignore +searching macros for the levels
+    * higher than the current supplier level, will +query only the lower-precedence suppliers

+

+   + * for the current level and will query all +suppliers for the lower levels.

+

+   + * This is done to avoid infinite loops that could +be caused if the supplier calls the provider

+

+   + * and the provider in turn calls that supplier +again. Also the supplier should not know anything
+    * about the build macros defined for the higher +levels.

+

+ +    * @return the reference to the IBuildMacro interface representing +

+

+   + * the build macro of a given name or null if the +macro of  that name is not defined

+

+ +    */

+

+    +IBuildMacro getMacro(String macroName,

-IConfiguration configuration,

+IConfiguration configuration,

-IBuildMacroProvider provider);

+IBuildMacroProvider provider);

 

-            /**

+ +   /**

-             *

+ +    *

-             * @param configuration configuration

+ +    * @param configuration configuration

-             * @param provider the instance of the -build macro provider to be used for querying the

+ +    * @param provider the instance of the +build macro provider to be used for querying the

-             * build macros from within the -supplier. The supplier should use this provider to obtain

-

-* the already defined build macros instead of using -the “default” provider returned by the

-

-* ManagedBuildManager.getBuildMacroProvider().

-

- * The provider passed to a supplier will ignore -searching macros for the levels

-

- * higher than the current supplier level, will -query only the lower-precedence suppliers

-

- * for the current level and will query all -suppliers for the lower levels.

-

- * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

- * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

- * about the build macros defined for the higher -levels.

+ +    * build macros from within the +supplier. The supplier should use this provider to obtain

-             * @return the IBuildMacro[] array -representing defined macros

+    +* the already defined build macros instead of using +the “default” provider returned by the

-             */

-

-IBuildMacro[] getMacros(IConfiguration configuration,

+    +* ManagedBuildManager.getBuildMacroProvider().

+

+    +* The provider passed to a supplier will ignore +searching macros for the levels

+

+    +* higher than the current supplier level, will +query only the lower-precedence suppliers

+

+   + * for the current level and will query all +suppliers for the lower levels.

+

+   + * This is done to avoid infinite loops that could +be caused if the supplier calls the provider

+

+   + * and the provider in turn calls that supplier +again. Also the supplier should not know anything

+

+   + * about the build macros defined for the higher +levels.

+

+ +    * @return the IBuildMacro[] array +representing defined macros

+

+ +    */

+

+    +IBuildMacro[] getMacros(IConfiguration configuration,

-IBuildMacroProvider provider);

-

}

-

All methods of the IProjectBuildMacroSupplier interface +IBuildMacroProvider provider);

+

+}

+

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.

-

public interface -IProjectBuildMacroSupplier {

-            /**

+public interface +IProjectBuildMacroSupplier {

-             *

+ +   /**

-             * @ macroName the macro mane

+ +    *

-             * @param project the instance of the -managed project

+ +    * @ macroName the macro mane

-             * @param provider the instance of the -build macro provider to be used for querying the

+ +    * @param project the instance of the +managed project

-             * build macros from within the -supplier. The supplier should use this provider to obtain

-

-* the already defined build macros instead of using -the “default” provider returned by the

-

-* ManagedBuildManager.getBuildMacroProvider().

-

- * The provider passed to a supplier will ignore -searching macros for the levels

-

- * higher than the current supplier level, will -query only the lower-precedence suppliers

-

- * for the current level and will query all -suppliers for the lower levels.

-

- * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

- * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

- * about the build macros defined for the higher -levels.

+ +    * @param provider the instance of the +build macro provider to be used for querying the

-             * @return the reference to the -IBuildMacro interface representing

-

- * the build macro of a given name or null if the -macro of  that name is not defined

+ +    * build macros from within the +supplier. The supplier should use this provider to obtain

-             */

-

-IBuildMacro getMacro(String macroName,

+    +* the already defined build macros instead of using +the “default” provider returned by the

+

+    +* ManagedBuildManager.getBuildMacroProvider().

+

+   + * The provider passed to a supplier will ignore +searching macros for the levels

+

+   + * higher than the current supplier level, will +query only the lower-precedence suppliers

+

+   + * for the current level and will query all +suppliers for the lower levels.

+

+   + * This is done to avoid infinite loops that could +be caused if the supplier calls the provider

+

+   + * and the provider in turn calls that supplier +again. Also the supplier should not know anything

+

+   + * about the build macros defined for the higher +levels.

+

+ +    * @return the reference to the IBuildMacro interface representing +

+

+   + * the build macro of a given name or null if the +macro of  that name is not defined

+

+ +    */

+

+    +IBuildMacro getMacro(String macroName,

-IManagedProject project,

+IManagedProject project,

-IBuildMacroProvider provider);

+IBuildMacroProvider provider);

 

-            /**

+ +   /**

-             *

+ +    *

-             * @param project the instance of the -managed project

+ +    * @param project the instance of the +managed project

-             * @param provider the instance of the -build macro provider to be used for querying the

+ +    * @param provider the instance of the +build macro provider to be used for querying the

-             * build macros from within the -supplier. The supplier should use this provider to obtain

-

-* the already defined build macros instead of using -the “default” provider returned by the

-

-* ManagedBuildManager.getBuildMacroProvider().

-

- * The provider passed to a supplier will ignore -searching macros for the levels

-

- * higher than the current supplier level, will -query only the lower-precedence suppliers

-

- * for the current level and will query all -suppliers for the lower levels.

-

- * This is done to avoid infinite loops that could -be caused if the supplier calls the provider

-

- * and the provider in turn calls that supplier -again. Also the supplier should not know anything

-

- * about the build macros defined for the higher -levels.

+ +    * build macros from within the +supplier. The supplier should use this provider to obtain

-             * @return the IBuildMacro[] array -representing defined macros

+    +* the already defined build macros instead of using +the “default” provider returned by the

-             */

-

-IBuildMacro[] getMacros(IManagedProject project,

+    +* ManagedBuildManager.getBuildMacroProvider().

+

+   + * The provider passed to a supplier will ignore +searching macros for the levels

+

+   + * higher than the current supplier level, will +query only the lower-precedence suppliers

+

+   + * for the current level and will query all +suppliers for the lower levels.

+

+   + * This is done to avoid infinite loops that could +be caused if the supplier calls the provider

+

+   + * and the provider in turn calls that supplier +again. Also the supplier should not know anything

+

+   + * about the build macros defined for the higher +levels.

+

+ +    * @return the IBuildMacro[] array +representing defined macros

+

+ +    */

+

+    +IBuildMacro[] getMacros(IManagedProject project,

-IBuildMacroProvider provider);

-

}

-

The IBuildMacro interface returns information regarding an +IBuildMacroProvider provider);

+

+}

+

The IBuildMacro interface returns information regarding an individual build macro. 

-

public interface -IBuildMacro{

-

            public -static final int VALUE_TEXT = 1; //can hold any text string

-

            public -static final int VALUE_TEXT_LIST = 2; //can hold the array of text string values

-

            public -static final int VALUE_PATH_FILE = 3; //can hold file path

-

            public +

+public interface +IBuildMacro{

+

+    public +static final int VALUE_TEXT = 1; //can hold any text string

+

+    public +static final int VALUE_TEXT_LIST = 2; //can hold the array of text string values

+

+    public +static final int VALUE_PATH_FILE = 3; //can hold file path

+

+    public static final int VALUE_PATH_FILE_LIST = 4; //can hold the array of file path -values

-

            public -static final int VALUE_PATH_DIR = 5; //can hold dir path

-

            public +values

+

+    public +static final int VALUE_PATH_DIR = 5; //can hold dir path

+

+    public static final int VALUE_PATH_DIR_LIST = 6; //can hold the array of dir path -values

-

            public -static final int VALUE_PATH_ANY = 7; //can hold both file and dir path

-

            public -static final int VALUE_PATH_ANY_LIST = 8; //can hold the array of  PATH_ANY

+values

+

+    public +static final int VALUE_PATH_ANY = 7; //can hold both file and dir path

+

+    public +static final int VALUE_PATH_ANY_LIST = 8; //can hold the array of  PATH_ANY

-// values 

-

 

-

            String -getName();

-

           

-

-            /**

-

-             * @returns IBuildMacro.VALUE_xxx

-

-             */

-

            int -getMacroValueType();

+// values 

 

-            /**

+    String getName();

-             * @throws BuildMacroException if macro -holds StringList-type value

+            +

-             */

-

            String -getStringValue() throws BuildMacroException;

+ +    /**

+

+ +     * @returns IBuildMacro.VALUE_xxx

+

+ +     */

+

+    int +getMacroValueType();

 

-            /**

+ +    /**

-             * @throws BuildMacroException if macro -holds single String-type value

+ +     * @throws BuildMacroException if macro +holds StringList-type value

-             */

-

            -String[] getStringListValue() throws BuildMacroException;

-

}

+ +     */

+

+    String getStringValue() throws BuildMacroException;

+

+ 

+

+    /**

+

+     * @throws BuildMacroException if macro +holds single String-type value

+

+     */

+

+    +String[] getStringListValue() throws BuildMacroException;

+

+}

7.9 Defining a Configuration Name Provider

All the configuration names must be unique within a project.  You can provide unique configuration names in your build @@ -5958,87 +6182,255 @@ String [] usedConfigurationNames );
and supply a class that implements the IManagedOutputNameProvider interface shown below.  The class name is assigned to the outputType element, nameProvider attribute.

-

public +

public interface IManagedOutputNameProvider{

-  /**

+  /**

-   *

+   *

-   * Returns the output names +   * Returns the output names corresponding to the primary input name(s)

-   *

+   *

-   * @returns String[]

+   * @returns String[]

-   */

+   */

-   IPath[] +   IPath[] getOutputPaths(ITool tool, IPath[] primaryInputs);

-}

+}

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.

7.11 Defining an Option Value Handler

+

You can specify a value handler for an option.  You must specify and +supply a class that implements the +IManagedOptionValueHandler interface shown below.  This interface is +used to dynamically manage the value of an option.

+

public interface IManagedOptionValueHandler{
+
+    public final int EVENT_OPEN = 1;  /** The option is +opened, i.e. its UI element
+                                      +* is created. The valueHandler can override
+                                      +* the value of the option. If it does not,
+                                      +* the last persisted value is used. */
+    public final int EVENT_CLOSE = 2; /** The option is closed. +i.e. its value has been
+                                      +* destroyed when a configuration/resource gets deleted.
+                                      +* The valuehandler can do various things assocaited with
+                                      +* destroying the option such as freeing the memory
+                                      +* associated with this option callback, if needed. */
+    public final int EVENT_SETDEFAULT = 3; /** The default value +option::defaultValue has
+                                      +* been set. The handleValue callback is called
+                                      +* afterwards to give the handler a chance to
+                                      +* override the value or to update the value in
+                                      +* its back-end. Typically this event will be called
+                                      +* when the Restore Defaults button is pressed. */
+    public final int EVENT_APPLY = 4; /** The option has been set +by pressing the Apply
+                                      +* button (or the OK button). The valueHandler can
+                                      +* transfer the value of the option to its own
+                                      +* back-end. */
+
+   /**
+    * Handles transfer between values between UI element and
+    * back-end in different circumstances.
+    *
+    * @param configuration build configuration of option
+    * (may be IConfiguration or IResourceConfiguration)
+    * @param holder contains the holder of the option
+    * @param option the option that is handled
+    * @param extraArgument extra argument for handler
+    * @param event event to be handled
+    *
+    * @return True when the event was handled, false otherwise.
+    * This enables default event handling can take place.
+    */
+    boolean handleValue(IBuildObject configuration,
+        IHoldsOptions holder,
+        IOption option,
+        String extraArgument,
+        int event);
+
+   /**
+    * Checks whether the value of an option is its default value.
+    *
+    * @param configuration build configuration of option
+    * (may be IConfiguration or IResourceConfiguration)
+    * @param holder contains the holder of the option
+    * @param option the option that is handled
+    * @param extraArgument extra argument for handler
+    *
+    * The additional options besides configuration are supplied +to
+    * provide enough information for querying the default value +from
+    * a potential data storage back-end.
+    *
+    * @return True if the options value is its default value and
+    * False otherwise. This enables that default event handling +can
+    * take place.
+    */
+    boolean isDefaultValue(IBuildObject configuration,
+        IHoldsOptions holder,
+        IOption option,
+        String extraArgument);
+
+   /**
+    * Checks whether an enumeration value of an option is +currently a
+    * valid choice. The use-case for this method is the case, +where
+    * the set of valid enumerations in the plugin.xml file +changes.
+    * The UI will remove entries from selection lists if the +value
+    * returns false.
+    *
+    * @param configuration build configuration of option
+    * (may be IConfiguration or IResourceConfiguration)
+    * @param holder contains the holder of the option
+    * @param option the option that is handled
+    * @param extraArgument extra argument for handler
+    * @param enumValue enumeration value that is to be checked
+    *
+    * The additional options besides configuration are supplied +to
+    * provide enough information for querying information from a +
+    * a potential data storage back-end.
+    *
+    * @return True if the enumeration value is valid and False +
+    * otherwise.
+    */
+    boolean isEnumValueAppropriate(IBuildObject configuration, +
+        IHoldsOptions holder,
+        IOption option,
+        String extraArgument,
+        String enumValue);
+}

+

See the Shared Tool Options design document in bugzilla #90481 +for additional information.

7.12 Defining an Option Applicability Calculator

You can specify an option applicability calculator for an option.  You must specify and supply a -class that implements the IManagedOutputNameProvider +class that implements the IManagedOutputNameProvider interface shown below.  The class name is assigned to the outputType element, nameProvider attribute.  You should implement this interface when an option is not always applicable - for example, when an option is only used if another option has a particular value.

public interface IOptionApplicability {
+  /**
+  * This method is queried whenever a makefile or makefile fragment is
+  * generated which uses this option, and in the C/C++ Build property
+  * pages when displaying the current command line.
+  *
+  * @param configuration build configuration of option
+  * (may be IConfiguration or IResourceConfiguration)
+  * @param holder contains the holder of the option
-* @param option the option itself
+  +* @param option the option itself 
+  *
+  * @return true if this option is to be used in command line
+  * generation, false otherwise
+  */
+  public boolean isOptionUsedInCommandLine(
    IBuildObject configuration,
    IHoldsOptions holder,
    IOption option);

+  /**
+  * This method is queried whenever a new option category is displayed.
+  *
+  * @param configuration build configuration of option
+  * (may be IConfiguration or IResourceConfiguration)
+  * @param holder contains the holder of the option
+  * @param option the option itself
+  *
+  * @return true if this option should be visible in the build options page,
+  * false otherwise
+  */
+  public boolean isOptionVisible(
    IBuildObject configuration,
    IHoldsOptions holder,
    IOption option);

+  /**
+  * Whenever the value of an option changes in the GUI, this method is
+  * queried on all other visible options for the same category. Note that
+  * this occurs when the GUI changes - the user may opt to cancel these
+  * changes.
+  *
+  * @param configuration build configuration of option
+  * (may be IConfiguration or IResourceConfiguration)
+  * @param holder contains the holder of the option
+  * @param option the option itself
+  *
+  * @return true if this option should be enabled in the build options page,
+  * or false if it should be disabled (grayed out)
+  */
+  public boolean isOptionEnabled(
    IBuildObject configuration,
    IHoldsOptions holder,