Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "PTP/user-guides/jaxb etfw workflow"
(→Environment Variables) |
|||
(123 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
== Overview == | == Overview == | ||
− | The intent of this user guide is to provide information on writing ETFw XML workflows using JAXB by going through the various parts of the workflow. This user guide is not yet complete so if you are currently using this page as a reference for building JAXB workflows, take note that some of how this information is organized may change. | + | The intent of this user guide is to provide information on writing ETFw XML workflows using Resource Manager (RM) JAXB by going through the various parts of the workflow. This user guide is not yet complete so if you are currently using this page as a reference for building JAXB workflows, take note that some of how this information is organized may change. |
− | + | == Extension Point == | |
The extension point for adding new JAXB ETFw workflows is '''org.eclipse.ptp.etfw.jaxb.workflows'''. The following information is required for a new workflow: | The extension point for adding new JAXB ETFw workflows is '''org.eclipse.ptp.etfw.jaxb.workflows'''. The following information is required for a new workflow: | ||
− | * '''name''' - the name of the tool. This is displayed in the tool selection dropdown menu (e.g. TAU, PPW_UPC, etc). | + | * '''workflowDefinitionXML''' |
− | * '''file''' - the path to the XML file containing the ETFw workflow. | + | ** '''name''' - the name of the tool. This is displayed in the tool selection dropdown menu (e.g. TAU, PPW_UPC, etc). |
+ | ** '''file''' - the path to the XML file containing the ETFw workflow. | ||
<source lang="XML"> | <source lang="XML"> | ||
− | <extension point="org.eclipse.ptp.etfw.jaxb.workflows" | + | <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> |
− | name="TAU" | + | <workflowDefinitionXML |
− | + | name="TAU" | |
+ | file="TAU.xml"> | ||
+ | </workflowDefinitionXML> | ||
</extension> | </extension> | ||
</source> | </source> | ||
Line 19: | Line 22: | ||
== Creating an ETFw Workflow == | == Creating an ETFw Workflow == | ||
− | This section explains how to create new ETFw workflows, provide reference information for the XML tags inside an ETFw workflow, and show some snippets of the TAU | + | This section explains how to create new ETFw workflows, provide reference information for the XML tags inside an ETFw workflow, and show some snippets of the TAU XML file. Each ETFw workflow begins with the top-level tag <etfwTool>. Within this top-level tag can be one or more Control Data (<controlData>), Build Tool (<buildTool>), Execution Tool (<execTool>) and/or Analysis Tool (<analysisTool>) tags. |
<source lang="XML"> | <source lang="XML"> | ||
<etfwTool> | <etfwTool> | ||
+ | <controlData> | ||
... | ... | ||
+ | </controlData> | ||
+ | <buildTool> | ||
+ | ... | ||
+ | </buildTool> | ||
+ | <execTool> | ||
+ | ... | ||
+ | </execTool> | ||
+ | <analysisTool> | ||
+ | ... | ||
+ | </analysisTool> | ||
</etfwTool> | </etfwTool> | ||
</source> | </source> | ||
Line 58: | Line 72: | ||
The primary parts of the attribute for setting environment variables are: | The primary parts of the attribute for setting environment variables are: | ||
− | * name | + | * '''name''' |
** TAU Runtime.performance.options.environmentvariables.configuration_id_ is the key and should match the option panes <configVarId /> tag to which it belongs. | ** TAU Runtime.performance.options.environmentvariables.configuration_id_ is the key and should match the option panes <configVarId /> tag to which it belongs. | ||
** TAU_SYNCHRONIZE_CLOCKS is the environment variable to set. | ** TAU_SYNCHRONIZE_CLOCKS is the environment variable to set. | ||
− | * type | + | * '''type''' |
− | * translateBooleanAs - In many cases, environment attributes are tied to checkbox UI options that returns a boolean that needs to be translated to something else (e.g. 1 or 0, or even a string). In the case of this attribute above, the boolean is translated as 1 for true, empty for false. | + | ** boolean |
+ | ** string | ||
+ | ** choice | ||
+ | ** integer | ||
+ | * '''translateBooleanAs''' - In many cases, environment attributes are tied to checkbox UI options that returns a boolean that needs to be translated to something else (e.g. 1 or 0, or even a string). In the case of this attribute above, the boolean is translated as 1 for true, empty for false. | ||
− | Below is a snippet of the | + | Below is a snippet of the XML workflow that creates the checkbox attribute and associate it with a tool pane. The critical parts to understand are the <configVarId> and the <rm:widget> tags. The other XML tags are explained later in this document. |
<source lang="XML"> | <source lang="XML"> | ||
Line 70: | Line 88: | ||
<global> | <global> | ||
<toolPanes virtual="false" embedded="false"> | <toolPanes virtual="false" embedded="false"> | ||
− | + | <configId>TAU Runtime.performance.options.configuration_id_</configId> | |
− | + | <configVarId>TAU Runtime.performance.options.environmentvariables.configuration_id_</configVarId> | |
− | + | <optionPane> | |
− | + | <rm:title>Tau Runtime</rm:title> | |
− | + | <rm:layout> | |
− | + | <rm:grid-layout /> | |
− | + | </rm:layout> | |
<rm:composite> | <rm:composite> | ||
<rm:layout> | <rm:layout> | ||
Line 88: | Line 106: | ||
<rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="3" /> | <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="3" /> | ||
</rm:layout-data> | </rm:layout-data> | ||
− | + | </rm:widget> | |
</rm:composite> | </rm:composite> | ||
</optionPane> | </optionPane> | ||
Line 96: | Line 114: | ||
</source> | </source> | ||
− | ==== Program | + | ==== Program Argument Attributes ==== |
This section discusses how UI options get translated into program arguments using the above control data as an example. In the Control Data, the option -optVerbose should get passed as a program argument based on a boolean translation (similar to the environment variable). As with the environment variable, the main parts of the attribute are: | This section discusses how UI options get translated into program arguments using the above control data as an example. In the Control Data, the option -optVerbose should get passed as a program argument based on a boolean translation (similar to the environment variable). As with the environment variable, the main parts of the attribute are: | ||
Line 102: | Line 120: | ||
** Tau Compiler.performance.options.configuration_id_ is the key and should match the option panes <configId /> tag to which it belongs. This lets the system know that it is a program argument for this tools option pane and the value should be passed to the tool. | ** Tau Compiler.performance.options.configuration_id_ is the key and should match the option panes <configId /> tag to which it belongs. This lets the system know that it is a program argument for this tools option pane and the value should be passed to the tool. | ||
** -OPTVERBOSE_ARGUMENT_DEFAULT - Unlike the environment variable, this string can be anything since it doesn't have any significance. | ** -OPTVERBOSE_ARGUMENT_DEFAULT - Unlike the environment variable, this string can be anything since it doesn't have any significance. | ||
+ | * '''type''' | ||
+ | ** boolean | ||
+ | ** string | ||
+ | ** choice | ||
+ | ** integer | ||
* '''translateBooleanAs''' - Similar to environment variables, attributes containing program arguments are primarily tied to checkbox UI widgets that returns a boolean that needs to be translated to something else (e.g. a string value). In the case of this attribute above, the boolean is translated as -optVerbose for true, empty for false. | * '''translateBooleanAs''' - Similar to environment variables, attributes containing program arguments are primarily tied to checkbox UI widgets that returns a boolean that needs to be translated to something else (e.g. a string value). In the case of this attribute above, the boolean is translated as -optVerbose for true, empty for false. | ||
− | Below is a snippet of the | + | Below is a snippet of the XML workflow that creates the checkbox widget for this program argument and associate it with the specified tool pane. The critical parts to understand are the <configId> and the <rm:widget> tags. The other XML tags are explained later in this document. |
<source lang="XML"> | <source lang="XML"> | ||
Line 132: | Line 155: | ||
</source> | </source> | ||
− | ==== Paired Program | + | ==== Paired Program Argument Attributes ==== |
This section discusses the other type of program arguments, paired program arguments. That is, when you have something similar to the previous discussion about program arguments, but you want to pass a value for that argument. For example, looking at the control data, we want to pass a value for the program argument '''-optPdtDir=''' where one UI widget contains the program argument and another contains the value to pass. The last two attributes in the control data above represent paired program arguments and the details about how they are paired are highlighted below. | This section discusses the other type of program arguments, paired program arguments. That is, when you have something similar to the previous discussion about program arguments, but you want to pass a value for that argument. For example, looking at the control data, we want to pass a value for the program argument '''-optPdtDir=''' where one UI widget contains the program argument and another contains the value to pass. The last two attributes in the control data above represent paired program arguments and the details about how they are paired are highlighted below. | ||
Line 144: | Line 167: | ||
** Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED | ** Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED | ||
− | As with normal program arguments, the first part of the name must match the value found in the tool pane's <configId /> field so that the system knows that the program argument is for the tool that the pane is associated with. The difference is that the second key that has the value must end with _SAVED. When parsing program arguments, the system looks at the launch configuration to see if there is another attribute that matches the original key value, but ends with _SAVED. This way it knows that '''-optPdtDir=''' should be paired with whatever value is in the second attribute. Below is a snippet of the | + | As with normal program arguments, the first part of the name must match the value found in the tool pane's <configId /> field so that the system knows that the program argument is for the tool that the pane is associated with. The difference is that the second key that has the value must end with _SAVED. When parsing program arguments, the system looks at the launch configuration to see if there is another attribute that matches the original key value, but ends with _SAVED. This way it knows that '''-optPdtDir=''' should be paired with whatever value is in the second attribute. Below is a snippet of the XML workflow that creates the checkbox widget for this program argument and a browse widget that allows the user to either browse for the location of PDT or enter it. The critical parts to understand are the <configId> and the pair of <rm:widget> and <rm:browse> tags. The first is for the checkbox and the other for a special widget for the browse button / Text field. The other XML tags are explained later in this document. |
<source lang="XML"> | <source lang="XML"> | ||
Line 172: | Line 195: | ||
*'''<etfwTool>''' - Top level tag for enclosing an ETFw workflow. | *'''<etfwTool>''' - Top level tag for enclosing an ETFw workflow. | ||
+ | ** Attributes: | ||
+ | *** '''xmlns:rm''' "http://eclipse.org/ptp/schemas" - resource manager (rm) namespace | ||
+ | *** '''name''' - string - the workflow name | ||
+ | *** '''prepend-execution''' - boolean - If true the actual executable is an argument passed to one or more additional utilities. | ||
+ | *** '''recompile''' - boolean - If true the program is recompiled with performance-analysis specific modifications. | ||
+ | *** '''explicit-execution''' - boolean - If true there is no automatic assumptions about when execute steps must be performed. Automatic execution does not take place after build steps! | ||
*'''<controlData>''' - Contains all of the attributes associated with the workflow. These are tied to UI widgets to save information based on user selections. | *'''<controlData>''' - Contains all of the attributes associated with the workflow. These are tied to UI widgets to save information based on user selections. | ||
− | **'''<attribute>''' | + | **'''<attribute name="" type="" translateBooleanAs="">''' |
− | *'''<buildTool> - Represents a compilation step in the workflow. | + | *'''<buildTool>''' - Represents a compilation step in the workflow. |
− | **'''<global>''' | + | ** Attributes: |
− | ***'''<toolPanes>''' | + | *** '''tool-id''' - string - a unique tag for this application. Optional. |
− | ****'''< | + | *** '''tool-name''' - string - name of the tool |
− | **'''< | + | *** '''tool-type''' - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file. |
− | **'''<cxx-compiler>''' | + | *** <strike>'''require-true''' - string - a launch configuration attribute name which causes this tool step execute if it is defined.</strike>'''Deprecated - use <tool-state> instead''' |
− | **'''< | + | *** '''replace-compiler''' - boolean - specify true if the compiler command is entirely replaced rather than prepended. |
− | **'''<all- | + | *** '''set-success-attribute''' - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution. |
− | ***'''< | + | **'''<global>''' - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the '''<execTool>''' tag. |
− | ****'''< | + | ***'''<toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with="">''' - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc. |
− | *'''<execTool>''' | + | ****'''<configId>''' - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most likely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes. |
− | **'''<global>''' | + | ****'''<configVarId>''' - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool. |
+ | ****'''<optionPane>''' - this is where the User Interface is defined by adding widgets to control what options are available for the tool. It represents a UI tab from the RM JAXB schema. | ||
+ | **'''<cc-compiler>''', '''<cxx-compiler>''', '''<f90-compiler>''', '''upc-compiler''', '''<all-compilers>''' - Special cases representing the different compiler types that can either replace or be prepended to the default compilers for those languages. If the individual compiler tags are not defined and a command is specified for allcompilers it replaces or prepends the command for every language. If the individual compilers are defined along with allcompilers the individual compilers are used and each is given arguments defined by allcompilers. Since these are all represented by the same data type, this can probably be simplified. | ||
+ | *** '''tool-id''' - string - a unique tag for this application. Optional. | ||
+ | *** '''tool-name''' - string - name of the tool | ||
+ | *** '''tool-command''' - string - command used to invoke the tool | ||
+ | *** '''tool-group''' - string - tools in the same group are assumed to share the same binary location | ||
+ | *** '''out-to-file''' - string - the file to which the standard out of this tool must be written | ||
+ | *** '''visualizer''' - boolean - if true, the command is launched and the output is not handled. Otherwise, output is manged for printing on the console. | ||
+ | ***'''<toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with="">''' - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc. | ||
+ | ****'''<configId>''' - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. | ||
+ | ****'''<configVarId>''' - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool. | ||
+ | ****'''<optionPane>''' - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema. | ||
+ | **'''<tool-state>''' - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's '''set-success-attribute'''. | ||
+ | ***'''<execute-if attribute="" [value=""]>''' - execute this tool step if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<do not execute-if>''' - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<execute-if>''' - execute this tool step if the contained conditional expression is true. | ||
+ | ****'''<not>|<and>|<or>''' - the 'not', 'and', and 'or' of the contained conditional expression. | ||
+ | *****'''<rule attribute="" [value=""]>''' - true if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<do not execute-if>''' - do not execute this tool step if the contained conditional expression is true. | ||
+ | ****'''<not>|<and>|<or>''' - the 'not', 'and', and 'or' of the contained conditional expression. | ||
+ | *****'''<rule attribute="" [value=""]>''' - true if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | *'''<execTool>''' - Represents a execution step in the workflow. | ||
+ | ** Attributes: | ||
+ | *** '''tool-id''' - string - a unique tag for this application. Optional. | ||
+ | *** '''tool-name''' - string - name of the tool | ||
+ | *** '''tool-type''' - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file. | ||
+ | *** <strike>'''require-true''' - string - a launch configuration attribute name which causes this tool step execute if it is defined.</strike>'''Deprecated - use <tool-state> instead''' | ||
+ | *** '''prepend-execution''' - boolean - if true, the actual executable is an argument passed to one or more utilities | ||
+ | *** '''replace-execution''' - boolean - if true, the executable and arguments in the launch configuration are ignored and the utilities are run instead | ||
+ | *** '''set-success-attribute''' - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution. | ||
+ | **'''<global>''' - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the '''<execTool>''' tag. | ||
+ | ***'''<toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with="">''' - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc. | ||
+ | ****'''<configId>''' - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most liklely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes. | ||
+ | ****'''<configVarId>''' - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool. | ||
+ | ****'''<optionPane>''' - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema. | ||
**'''<execUtils>''' | **'''<execUtils>''' | ||
− | *'''< | + | *** '''tool-id''' - string - a unique tag for this application. Optional. |
− | **'''<global>''' | + | *** '''tool-name''' - string - name of the tool |
− | **'''< | + | *** '''tool-command''' - string - command used to invoke the tool |
+ | *** '''tool-group''' - string - tools in the same group are assumed to share the same binary location | ||
+ | *** '''out-to-file''' - string - the file to which the standard out of this tool must be written | ||
+ | *** '''visualizer''' - boolean - if true, the command is launched and the output is not handled. Otherwise, output is printed on the console. | ||
+ | ***'''<toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with="">''' - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc. | ||
+ | ****'''<configId>''' - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. | ||
+ | ****'''<configVarId>''' - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool. | ||
+ | ****'''<optionPane>''' - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema. | ||
+ | **'''<tool-state>''' - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's '''set-success-attribute'''. | ||
+ | ***'''<execute-if attribute="" [value=""]>''' - execute this tool step if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<do not execute-if>''' - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<execute-if>''' - execute this tool step if the contained conditional expression is true. | ||
+ | ****'''<not>|<and>|<or>''' - the 'not', 'and', and 'or' of the contained conditional expression. | ||
+ | *****'''<rule attribute="" [value=""]>''' - true if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<do not execute-if>''' - do not execute this tool step if the contained conditional expression is true. | ||
+ | ****'''<not>|<and>|<or>''' - the 'not', 'and', and 'or' of the contained conditional expression. | ||
+ | *****'''<rule attribute="" [value=""]>''' - true if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | *'''<analysisTool>''' - Represents a analysis step in the workflow. | ||
+ | ** Attributes: | ||
+ | *** '''tool-id''' - string - a unique tag for this application. Optional. | ||
+ | *** '''tool-name''' - string - name of the tool | ||
+ | *** '''tool-type''' - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file. | ||
+ | *** <strike>'''require-true''' - string - a launch configuration attribute name which causes this tool step execute if it is defined.</strike>'''Deprecated - use <tool-state> instead''' | ||
+ | *** '''depth''' - integer - | ||
+ | *** '''useDefaultLocation''' - boolean - | ||
+ | *** '''useLatestFileOnly''' - boolean - | ||
+ | *** '''set-success-attribute''' - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution. | ||
+ | **'''<global>''' - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the '''<execTool>''' tag. | ||
+ | ***'''<toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with="">''' - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc. | ||
+ | ****'''<configId>''' - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most likely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes. | ||
+ | ****'''<configVarId>''' - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool. | ||
+ | ****'''<optionPane>''' - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema. | ||
+ | **'''<analysis-commands>''' | ||
+ | *** '''tool-id''' - string - a unique tag for this application. Optional. | ||
+ | *** '''tool-name''' - string - name of the tool | ||
+ | *** '''tool-command''' - string - command used to invoke the tool | ||
+ | *** '''tool-group''' - string - tools in the same group are assumed to share the same binary location | ||
+ | *** '''out-to-file''' - string - the file to which the standard out of this tool must be written | ||
+ | *** '''visualizer''' - boolean - if true, the command is launched and the output is not handled. Otherwise, output is manged for printing on the console. | ||
+ | ***'''<toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with="">''' - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc. | ||
+ | ****'''<configId>''' - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. | ||
+ | ****'''<configVarId>''' - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool. | ||
+ | ****'''<optionPane>''' - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema. | ||
+ | **'''<for-all-like>''' - TBD | ||
+ | **'''<tool-state>''' - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's '''set-success-attribute'''. | ||
+ | ***'''<execute-if attribute="" [value=""]>''' - execute this tool step if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<do not execute-if>''' - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<execute-if>''' - execute this tool step if the contained conditional expression is true. | ||
+ | ****'''<not>|<and>|<or>''' - the 'not', 'and', and 'or' of the contained conditional expression. | ||
+ | *****'''<rule attribute="" [value=""]>''' - true if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | ***'''<do not execute-if>''' - do not execute this tool step if the contained conditional expression is true. | ||
+ | ****'''<not>|<and>|<or>''' - the 'not', 'and', and 'or' of the contained conditional expression. | ||
+ | *****'''<rule attribute="" [value=""]>''' - true if either the attribute is defined [no value given] or matches the value [value given]. | ||
+ | |||
+ | == Appendix 1: PerfSuite Example == | ||
+ | |||
+ | This section provides detailed steps for creating an ETFw XML workflow for the [http://perfsuite.ncsa.illinois.edu/ PerfSuite] profiling tool. This example assumes that PerfSuite is compiled and running on your machine with PAPI support. Most of PerfSuite's options can either be passed to the psrun executable at the command line or set as environment variables. For this example, most are passed at the command line and one is set as an environment variable to illustrate how the ETFw JAXB system works. | ||
+ | |||
+ | The profiling tool from PerfSuite we want to run is '''psrun'''. The configurable commands are listed below under three categories, environment variables, program arguments and paired program arguments: | ||
+ | |||
+ | * '''Environment Variables''' | ||
+ | ** '''File Format''' - output the results in XML or plain text. | ||
+ | * '''Program Arguments''' | ||
+ | ** '''MD5 checksum''' - include MD5 checksums in output | ||
+ | * '''Paired Program Arguments''' | ||
+ | ** '''Configuration''' - specify the configuration file to use. | ||
+ | ** '''Domain''' - select the counting domain (user, kernel, all) | ||
+ | ** '''POSIX''' - enable POSIX thread support | ||
+ | ** '''Resource Usage''' - include resource usage statistics | ||
+ | ** '''Resource Usage Only''' - include only resource usage statistics | ||
+ | ** '''Write Signal Numbers''' - Specify signal numbers to write before process exits. | ||
+ | ** '''Overflow Threshold''' - specify overflow threshold to use for profiling | ||
+ | |||
+ | The environment variables is set in the environment prior to launch, program arguments and paired program arguments are passed to the '''psrun''' executable at the command line. For example, to specify that we include md5 checksums and set the domain to kernel the command is: | ||
+ | |||
+ | '''psrun --md5 -d kernel shallow''' | ||
+ | |||
+ | where '''shallow''' is the name of the program executable to profile. Now that we know the inputs we need to tie to the User Interface (UI), we can start building the XML workflow that ties the UI selections to program arguments or environment variables. | ||
+ | |||
+ | The extension point for PerfSuite is shown below: | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> | ||
+ | <workflowDefinitionXML | ||
+ | name="PerfSuite" | ||
+ | file="perfsuite.xml"> | ||
+ | </workflowDefinitionXML> | ||
+ | </extension> | ||
+ | </source> | ||
+ | |||
+ | Since PerfSuite is run with the program executable as input, we don't need to concern ourselves with the '''buildTool''' and '''analysisTool''' tags. We only need the '''execTool''' tag. The basic workflow is something similar to the one below: | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas" | ||
+ | xsi:schemaLocation="etfw_tool_type.xsd" name="perfsuite" prepend-execution="false" recompile="false" explicit-execution="false"> | ||
+ | |||
+ | <!-- attributes are stored in the control data --> | ||
+ | <controlData> | ||
+ | |||
+ | </controlData> | ||
+ | |||
+ | <!-- This is the tool to execute --> | ||
+ | <execTool tool-name="PerfSuite"> | ||
+ | |||
+ | </execTool> | ||
+ | |||
+ | </etfwTool> | ||
+ | </source> | ||
+ | |||
+ | For simplicity, we just add the necessary pieces to perform the previous example (e.g. '''psrun --md5 -d kernel shallow''') and specify that we want to have the output in XML (by specifying the environment variable '''PS_HWPC_FORMAT'''. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas" | ||
+ | xsi:schemaLocation="etfw_tool_type.xsd" name="perfsuite" prepend-execution="false" recompile="false" explicit-execution="false"> | ||
+ | |||
+ | <!-- attributes are stored in the control data ---> | ||
+ | <controlData> | ||
+ | <attribute name="PERFSUITE_psrun.environmentvariables.configuration_id_PS_HWPC_FORMAT" type="choice"> | ||
+ | <rm:description>Specify the output format (XML or plain text)</rm:description> | ||
+ | <rm:choice>xml,text</rm:choice> | ||
+ | <rm:default>xml</rm:default> | ||
+ | </attribute> | ||
+ | <attribute name="PERFSUITE_psrun.configuration_id_-MD5" type="boolean" translateBooleanAs="--md5, "> | ||
+ | <rm:description>Include MD5 checksums in output</rm:description> | ||
+ | <rm:default> </rm:default> | ||
+ | </attribute> | ||
+ | <attribute name="PERFSUITE_psrun.configuration_id_-DOMAIN" type="boolean" translateBooleanAs="-d, "> | ||
+ | <rm:description>Specify domain</rm:description> | ||
+ | <rm:default> </rm:default> | ||
+ | </attribute> | ||
+ | <attribute name="PERFSUITE_psrun.configuration_id_-DOMAIN_SAVED" type="choice"> | ||
+ | <rm:description>Specified domain</rm:description> | ||
+ | <rm:choice>user,kernel,all</rm:choice> | ||
+ | <rm:default>user</rm:default> | ||
+ | </attribute> | ||
+ | </controlData> | ||
+ | |||
+ | <execTool tool-name="PerfSuite"> | ||
+ | <!-- This is the set of tools to execute, in this case just one tool is defined --> | ||
+ | <execUtils tool-command="psrun"> | ||
+ | <!-- A single tool could have multiple panes, in this case there is just one --> | ||
+ | <toolPanes virtual="false" embedded="false"> | ||
+ | <configId>PERFSUITE_psrun.configuration_id_</configId> | ||
+ | <configVarId>PERFSUITE_psrun.environmentvariables.configuration_id_</configVarId> | ||
+ | |||
+ | <!-- This is the actual UI tab that is displayed with the defined UI widgets --> | ||
+ | <optionPane> | ||
+ | <rm:title>PerfSuite</rm:title> | ||
+ | <rm:layout> | ||
+ | <rm:grid-layout /> | ||
+ | </rm:layout> | ||
+ | <rm:composite> | ||
+ | <rm:layout> | ||
+ | <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" /> | ||
+ | </rm:layout> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:widget type="combo" title="File Format" readOnly="true" style="SWT.LEFT" | ||
+ | attribute="PERFSUITE_psrun.environmentvariables.configuration_id_PS_HWPC_FORMAT"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="2" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:tooltip>Output format, either XML or text</rm:tooltip> | ||
+ | </rm:widget> | ||
+ | <rm:widget type="checkbox" title="Domain" buttonId="domain-button" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-DOMAIN"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="1" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:tooltip>Select counting domain (user, kernel, all)</rm:tooltip> | ||
+ | </rm:widget> | ||
+ | <rm:widget type="combo" readOnly="true" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-DOMAIN_SAVED"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="2" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:control-state> | ||
+ | <rm:enable-if button="domain-button" selected="true" /> | ||
+ | </rm:control-state> | ||
+ | </rm:widget> | ||
+ | <rm:widget type="checkbox" title="MD5 checksum" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-MD5"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="3" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:tooltip>Include MD5 checksums in output</rm:tooltip> | ||
+ | </rm:widget> | ||
+ | </rm:composite> | ||
+ | </optionPane> | ||
+ | </toolPanes> | ||
+ | </execUtils> | ||
+ | </execTool> | ||
+ | </etfwTool> | ||
+ | </source> | ||
+ | |||
+ | Using the above XML workflow as a reference, let's break down where the pieces of the command '''psrun --md5 -d kernel shallow''' are in the workflow. If you find the '''execUtils''' tag, you see that it contains the tool-command we want to run, ''''psrun'''. The rest of what is contained between the tags allows the user to select the additional input flags. For example, looking at the checkbox widget with title '''MD5 checksum''', you see that it is tied to the attribute '''PERFSUITE_psrun.configuration_id_-MD5'''. If you find that attribute in the '''controlData''' section, it translates to --md5 when it is selected and the empty string when it is not selected. In addition, notice that the first part of the attribute, '''PERFSUITE_psrun.configuration_id_''' corresponds to the '''configId''' for that tool's pane. This is how the system understands which attributes belong to which tools so the correct tool gets the --md5 input flag. | ||
+ | |||
+ | The rest of the inputs, including the environment variable for specifying text or XML output can be deduced by reviewing the sections above about setting environment variables and pairing attributes and then locating the UI widgets in the XML workflow. | ||
+ | |||
+ | == Appendix 2: Converting ETFw XML to ETFw Resource Manager (RM) JAXB XML == | ||
+ | |||
+ | This appendix is to aid developers in converting existing ETFw XML to the new ETFw Resource Manager (RM) JAXB XML. | ||
+ | |||
+ | 1. The existing "org.eclipse.ptp.etfw.workflows" extension point with <workflowDefinitionXML> containing XMLFile in plugin.xml file from: | ||
+ | <source lang="XML"> | ||
+ | <extension point="org.eclipse.ptp.etfw.workflows"> | ||
+ | <workflowDefinitionXML | ||
+ | XMLFile="HPCTOptions.xml"> | ||
+ | </workflowDefinitionXML> | ||
+ | </extension> | ||
+ | </source> | ||
+ | to new "org.eclipse.ptp.etfw.jaxb.workflows" extension point with <workflowDefinitionXML> containing file and name in plugin.xml file : | ||
+ | <source lang="XML"> | ||
+ | <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> | ||
+ | <workflowDefinitionXML | ||
+ | file="HPCTOptions.xml" | ||
+ | name="HPC Toolkit"> | ||
+ | </workflowDefinitionXML> | ||
+ | </extension> | ||
+ | </source> | ||
+ | |||
+ | 2. Change outermost XML definition in HPCTOptions.xml file from <toolset.01><tool>: | ||
+ | <source lang="XML"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <toolset.01> | ||
+ | <tool name="HPC Toolkit" explicitexecution="true"> | ||
+ | ... | ||
+ | </tool> | ||
+ | </toolset.01> | ||
+ | </source> | ||
+ | to <etfwTool> with matching explicit-execution and a <controlData> section in HPCTOptions.xml file: | ||
+ | <source lang="XML"> | ||
+ | <etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas" | ||
+ | xsi:schemaLocation="etfw_tool_type.xsd" name="hpctoolkit" prepend-execution="false" recompile="false" explicit-execution="true"> | ||
+ | <controlData> | ||
+ | ... | ||
+ | </controlData> | ||
+ | ... | ||
+ | </etfwTool> | ||
+ | </source> | ||
+ | |||
+ | 3. Change each execute/global from <execute><global> in <toolset.01><tool>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <execute> | ||
+ | <global name="HPC Toolkit"> | ||
+ | ... | ||
+ | </global> | ||
+ | </execute> | ||
+ | ... | ||
+ | </source> | ||
+ | to <execTool><global><toolPanes> with <configId> and <configVarId> in <etfwTool>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <execTool tool-name="HPC Toolkit"> | ||
+ | <global> | ||
+ | <toolPanes virtual="false" embedded="false"> | ||
+ | <configId>HPCTOOLKIT_global.configuration_id_</configId> | ||
+ | <configVarId>HPCTOOLKIT_global.environmentvariables.configuration_id_</configVarId> | ||
+ | ... | ||
+ | </toolPanes> | ||
+ | <!-- ************************************************************************************** --> | ||
+ | </global> | ||
+ | </execTool> | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | 4. Change each option pane from <optionpane> in <execute><global>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <optionpane title="Data Collection" virtual="true" displayoptions="false"> | ||
+ | ... | ||
+ | </optionpane> | ||
+ | ... | ||
+ | </source> | ||
+ | to <optionPane><rm:composite> with <rm:title>, <rm:layout>, and <rm:composite> in <execTool><global><toolPanes>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <optionPane> | ||
+ | <rm:title>Data Collection</rm:title> | ||
+ | <rm:layout> | ||
+ | <rm:grid-layout /> | ||
+ | </rm:layout> | ||
+ | <rm:composite> | ||
+ | <rm:layout> | ||
+ | <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" /> | ||
+ | </rm:layout> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> | ||
+ | </rm:layout-data> | ||
+ | ... | ||
+ | </rm:composite> | ||
+ | </optionPane> | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | 5a. '''Checkbox''': Change each checkbox environment variable from type=toggle <togoption> in <optionpane>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <togoption label="Generate unique filenames:" optname="HPC_UNIQUE_FILE_NAME" envvar="true" tooltip="Generate unique filenames for each MPI task's output (HPC_UNIQUE_FILE_NAME)"> | ||
+ | <optvalue type="toggle" seton="yes" /> | ||
+ | </togoption> | ||
+ | ... | ||
+ | </source> | ||
+ | to a type=boolean attribute in <controlData> and type=checkbox RM widget definition in <optionPane><rm:composite>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_UNIQUE_FILE_NAME" type="boolean" translateBooleanAs="yes,no"> | ||
+ | </attribute> | ||
+ | ... | ||
+ | <rm:widget type="checkbox" title="Generate unique filenames:" style="SWT.LEFT" | ||
+ | attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_UNIQUE_FILE_NAME"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="3" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:tooltip>Generate unique filenames for each MPI task's output (HPC_UNIQUE_FILE_NAME)</rm:tooltip> | ||
+ | </rm:widget> | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | 5b. '''Text Field''': Change each text field environment variable from type=text <togoption> in <optionpane>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <togoption label="Output file name:" optname="HPC_OUTPUT_NAME" envvar="true" required="true" tooltip="Specify output file name (HPC_OUTPUT_NAME)"> | ||
+ | <optvalue type="text" fieldrequired="true" /> | ||
+ | </togoption> | ||
+ | ... | ||
+ | </source> | ||
+ | to a type=string attribute in <controlData> and type=label & type=text RM widget definitions in <optionPane><rm:composite>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_OUTPUT_NAME" type="string"> | ||
+ | </attribute> | ||
+ | ... | ||
+ | <rm:widget type="label" style="SWT.LEFT"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data horizontalAlign="SWT.BEGINNING" verticalAlign="SWT.CENTER" grabExcessHorizontal="false" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:fixed-text>Output file name: </rm:fixed-text> | ||
+ | </rm:widget> | ||
+ | <rm:widget type="text" style="SWT.BORDER" | ||
+ | attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_OUTPUT_NAME"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="2" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:tooltip>Specify output file name (HPC_OUTPUT_NAME)</rm:tooltip> | ||
+ | </rm:widget> | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | 5c. '''Choice''': Change each choice environment variable from type=combo <togoption> in <optionpane>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <togoption label="Application time criteria: " optname="HPC_EXCEPTION_METRIC" envvar="true" required="true" | ||
+ | tooltip="Select run time criteria: wall clock or elapsed time (HPC_EXCEPTION_METRIC)"> | ||
+ | <optvalue type="combo" items="ELAPSED_TIME:::CPU_TIME" /> | ||
+ | </togoption> | ||
+ | ... | ||
+ | </source> | ||
+ | to a type=choice attribute in <controlData> and type=combo RM widget definition in <optionPane><rm:composite>: | ||
+ | <source lang="XML"> | ||
+ | ... | ||
+ | <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_EXCEPTION_METRIC" type="choice"> | ||
+ | <rm:choice>ELAPSED_TIME,CPU_TIME</rm:choice> | ||
+ | <rm:default>ELAPSED_TIME</rm:default> | ||
+ | </attribute> | ||
+ | ... | ||
+ | <rm:widget type="combo" title="Application time criteria: " readOnly="true" style="SWT.LEFT" | ||
+ | attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_EXCEPTION_METRIC"> | ||
+ | <rm:layout-data> | ||
+ | <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="2" /> | ||
+ | </rm:layout-data> | ||
+ | <rm:tooltip>Select run time criteria: wall clock or elapsed time (HPC_EXCEPTION_METRIC)</rm:tooltip> | ||
+ | </rm:widget> | ||
+ | ... | ||
+ | </source> | ||
+ | |||
+ | == Appendix 3: Temporary XML Schema Modification until Officially Committed == | ||
+ | |||
+ | The ETFw schema file "etfw_tool_type.xsd", which can be found in project org.eclipse.ptp.etfw.jaxb needs to be modified. It is presently pointing at where the RM schema was located in a local development environment workspace (/home/cnavarro/workspaces/ptp-dev/git/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd). If you open this ETFw schema file, near the top you'll see a few comments about the resource manager schema and why it points at a local one instead of the existing remote one. In short, the ETFw schema file was modified because the resource manager schema needed to be changed to support the additional TAU widgets. Otherwise, TAU wouldn't work since it would always fail to load those widgets. | ||
+ | |||
+ | If you apply all the patches (for both bug reports: Bug 397684 - ETFw using JAXB framework, and Bug 397685 - TAU JAXB workflow for ETFw), then you have to update the ETFw schema to point at the resource_manager_type.xsd in your local org.eclipse.ptp.rm.jaxb.core project. If you apply only the framework itself (for bug report: Bug 397684 - ETFw using JAXB framework) , then you can safely point at the RM schema at http://eclipse.org/ptp/schemas/rm.xsd. In other word, if you patch for the TAU support then you need the modified RM schema. | ||
+ | |||
+ | Here is what you do for the time being until these changes are formally released: | ||
+ | |||
+ | Changed in project org.eclipse.ptp.etfw.jaxb in data/etfw_tool_type.xsd from | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <!-- Point this schema to the location of the resource manager schema. This is required until the new widgets are added for TAU --> | ||
+ | <xs:import schemaLocation="file:/home/cnavarro/workspaces/ptp-dev/git/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd" namespace="org.eclipse.ptp" /> | ||
+ | </source> | ||
+ | |||
+ | to | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <!-- Point this schema to the location of the resource manager schema. This is required until the new widgets are added for TAU --> | ||
+ | <xs:import schemaLocation="file:User_Development_Environment_Directory/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd" namespace="org.eclipse.ptp" /> | ||
+ | </source> | ||
+ | |||
+ | == Appendix 4: Conditional Workflow Processing Examples == | ||
+ | |||
+ | The first workflow, workflow1.xml, is patterned after an existing workflow, that is, one that does not contain any <tool-state><execute-if> elements. This workflow has three steps. The first is a pre-processing analysis step which invokes the Java class BeforeStep. The second is the execution step which launches the application specified within the launch configuration. The third step is a post-processing analysis step which invokes the Java class AfterStep. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the host Eclipse output for both a successful execution and an unsuccessful one. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
+ | xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd" | ||
+ | name="SAMPLE1" prepend-execution="false" recompile="false" | ||
+ | explicit-execution="true"> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="BeforeStep" tool-group="internal" /> | ||
+ | </analysisTool> | ||
+ | |||
+ | <execTool/> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="AfterStep" tool-group="internal" /> | ||
+ | </analysisTool> | ||
+ | |||
+ | </etfwTool> | ||
+ | </source> | ||
+ | |||
+ | For the first workflow the console output of a successful execution is as follows. First the BeforeStep writes its output, next the execution step runs successfully, and finally the AfterStep writes its output. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | @@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 1 Pass projectLocation=/u/bwatt | ||
+ | |||
+ | !ENTRY org.eclipse.ptp.rm.lml.monitor.core 4 4 2013-03-22 14:50:03.892 | ||
+ | !MESSAGE /home/bwatt/runtime-Eclipse/.metadata/.plugins/org.eclipse.ptp.rm.lml.monitor.core/monitors.xml (No such file or directory) | ||
+ | @@@ In AfterStep.process projname=shallow_Linux configuration=Sample 1 Pass projectLocation=/u/bwatt | ||
+ | </source> | ||
+ | |||
+ | For the first workflow the console output of a failed execution is as follows. First the BeforeStep writes its output, next the execution step fails, which causes the AfterStep step to NOT run. Internally a global state variable is used. Initially is is set to true. Before each step is run this variable is checked if it is true the step is run if it is false the step is not run. After each step is run the step's success is 'anded' into the global state. Therefore following along with this workflow's execution, the global state is true and the BeforeStep is runs and completes successfully, next because the global state is still true the execution step runs, but it fails which sets the global state to false, which causes the AfterStep to NOT run. In other words, once the global state is set to false then all of the follow-on steps are not executed, that is, failure cascades unless a step uses the new <tool-state><execute-if> elements. which this workflow does not. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | @@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 1 Fail projectLocation=/u/bwatt | ||
+ | |||
+ | !ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:50:17.313 | ||
+ | !MESSAGE Execution Error | ||
+ | !STACK 1 | ||
+ | org.eclipse.core.runtime.CoreException: d956bfa5-5b7b-458b-ba67-cbcc9e665cc0: FAILED | ||
+ | ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. | ||
+ | must have at least 2 processes, not 1 | ||
+ | ::::PoePid=2286:::: | ||
+ | argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow | ||
+ | |||
+ | |||
+ | at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160) | ||
+ | at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591) | ||
+ | at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233) | ||
+ | at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61) | ||
+ | at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308) | ||
+ | at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95) | ||
+ | at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53) | ||
+ | !SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:50:17.314 | ||
+ | !MESSAGE d956bfa5-5b7b-458b-ba67-cbcc9e665cc0: FAILED | ||
+ | ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. | ||
+ | must have at least 2 processes, not 1 | ||
+ | ::::PoePid=2286:::: | ||
+ | argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow | ||
+ | </source> | ||
+ | |||
+ | The second workflow, workflow2.xml, contains a simple example of the new workflow conditional processing support. This workflow has now four steps. The first is a pre-processing analysis step which invokes the Java class BeforeStep. The second is the execution step which launches the application specified within the launch configuration, but it now sets the attribute "x". The third step is a post-processing analysis step which invokes the Java class AfterStep. The second step should only runs when the execution step succeeds. The fourth step is another post-processing analysis step which invokes the Java class CleanupStep. This new step should only runs when the execution step fails. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the host Eclipse output for both a successful execution and an unsuccessful one. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
+ | xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd" | ||
+ | name="SAMPLE2" prepend-execution="false" recompile="false" | ||
+ | explicit-execution="true"> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="BeforeStep" tool-group="internal" /> | ||
+ | </analysisTool> | ||
+ | |||
+ | <execTool set-success-attribute="x"/> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="AfterStep" tool-group="internal" /> | ||
+ | </analysisTool> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="CleanupStep" tool-group="internal" /> | ||
+ | <tool-state> | ||
+ | <execute-if attribute="x" value="false"/> | ||
+ | </tool-state> | ||
+ | </analysisTool> | ||
+ | |||
+ | </etfwTool> | ||
+ | </source> | ||
+ | |||
+ | For the second workflow the console output of a successful execution is as follows. First the BeforeStep writes its output. Next the execution step runs successfully. Afterwards since it includes a 'set-success-attribute' at sets the specified launch configuration attribute "x" to the string "true" and updates the global state to still be true. Next the AfterStep writes its output. The AfterStep runs because it does not contain any <tool-state><execute-if> elements which means it checks the global state which is true so it runs. However CleanupStep is different. It contains some <tool-state><execute-if> elements and global state is ignored and instead the conditional expression is evaluated. The expression specified that step 4 only runs if the value of the "x" attribute is "false" and since it is actually "true" the CleanupStep does NOT run. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | @@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 2 Pass projectLocation=/u/bwatt | ||
+ | @@@ In AfterStep.process projname=shallow_Linux configuration=Sample 2 Pass projectLocation=/u/bwatt | ||
+ | </source> | ||
+ | |||
+ | For the second workflow the console output of a failed execution is as follows. As before first the BeforeStep writes its output. But then the execution step fails. Afterwards since it includes a 'set-success-attribute' at sets the specified launch configuration attribute "x" to the string "false" and updates the global state to false. The AfterStep does not runs because it does not contain any <tool-state><execute-if> elements which means it checks the global state which is false so it is NOT run. However CleanupStep evaluates its conditional expression which causes it to runs because the value of the "x" attribute is actually "false". | ||
+ | |||
+ | <source lang="XML"> | ||
+ | @@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 2 Fail projectLocation=/u/bwatt | ||
+ | |||
+ | !ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:50:57.876 | ||
+ | !MESSAGE Execution Error | ||
+ | !STACK 1 | ||
+ | org.eclipse.core.runtime.CoreException: 2cb4d5ff-8c36-448d-9bda-de295ea4a45c: FAILED | ||
+ | ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. | ||
+ | must have at least 2 processes, not 1 | ||
+ | ::::PoePid=2512:::: | ||
+ | argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow | ||
+ | |||
+ | |||
+ | at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160) | ||
+ | at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591) | ||
+ | at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233) | ||
+ | at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61) | ||
+ | at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308) | ||
+ | at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95) | ||
+ | at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53) | ||
+ | !SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:50:57.876 | ||
+ | !MESSAGE 2cb4d5ff-8c36-448d-9bda-de295ea4a45c: FAILED | ||
+ | ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. | ||
+ | must have at least 2 processes, not 1 | ||
+ | ::::PoePid=2512:::: | ||
+ | argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow | ||
+ | |||
+ | |||
+ | @@@ In CleanupStep.process projname=shallow_Linux configuration=Sample 2 Fail projectLocation=/u/bwatt | ||
+ | </source> | ||
+ | |||
+ | The third workflow, workflow3.xml, contains a more complex example of the new workflow conditional processing support. This workflow still has four steps. The first still invokes the Java class BeforeStep, but it also now sets the attribute "x". The second is the execution step, and now it sets the attribute "y". The third step invokes the Java class AfterStep. The second step should only runs when both the BeforeStep and the execution step succeeds. The fourth step invokes the Java class CleanupStep. This step only runs when either the BeforeStrep or execution step fails. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the host Eclipse output for both a successful execution and an unsuccessful one. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
+ | xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd" | ||
+ | name="SAMPLE3" prepend-execution="false" recompile="false" | ||
+ | explicit-execution="true"> | ||
+ | |||
+ | <analysisTool set-success-attribute="x"> | ||
+ | <analysis-commands tool-command="BeforeStep" tool-group="internal" /> | ||
+ | </analysisTool> | ||
+ | |||
+ | <execTool set-success-attribute="y"> | ||
+ | </execTool> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="AfterStep" tool-group="internal" /> | ||
+ | <tool-state> | ||
+ | <do-not-execute-if> | ||
+ | <or> | ||
+ | <rule attribute="x" value="false"/> | ||
+ | <rule attribute="y" value="false"/> | ||
+ | </or> | ||
+ | </do-not-execute-if> | ||
+ | </tool-state> | ||
+ | </analysisTool> | ||
+ | |||
+ | <analysisTool> | ||
+ | <analysis-commands tool-command="CleanupStep" tool-group="internal" /> | ||
+ | <tool-state> | ||
+ | <execute-if> | ||
+ | <or> | ||
+ | <rule attribute="x" value="false"/> | ||
+ | <rule attribute="y" value="false"/> | ||
+ | </or> | ||
+ | </execute-if> | ||
+ | </tool-state> | ||
+ | </analysisTool> | ||
+ | |||
+ | </etfwTool> | ||
+ | </source> | ||
+ | |||
+ | For the third workflow the console output of a successful execution is as follows. First the BeforeStep writes its output and sets the specified attribute "x" to the string "true". Next the execution step runs successfully and sets the attribute "y" to the string "true". Next the AfterStep conditional expression is evaluated. This step "does not execute" if either attribute "x" or attribute "y" are "false". Both are "true" so it does run and writes its output. Next the CleanupStep conditional expression is evaluated. This step "does execute" if either attribute "x" or attribute "y" are "false". Both are "true" so it does NOT run. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | @@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 3 Pass projectLocation=/u/bwatt | ||
+ | @@@ In AfterStep.process projname=shallow_Linux configuration=Sample 3 Pass projectLocation=/u/bwatt | ||
+ | </source> | ||
+ | |||
+ | For the third workflow the console output of a failed execution is as follows. First the BeforeStep writes its output and sets the specified attribute "x" to the string "true". Next the execution step fails and sets the attribute "y" to the string "false". Next the AfterStep conditional expression is evaluated. This step "does not execute" if either attribute "x" or attribute "y" are "false". One of them is "false" so it does NOT run. Next the CleanupStep conditional expression is evaluated. This step "does execute" if either attribute "x" or attribute "y" are "false". One of them is "false" so it does run and writes its output. | ||
+ | |||
+ | <source lang="XML"> | ||
+ | @@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 3 Fail projectLocation=/u/bwatt | ||
+ | |||
+ | !ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:51:16.469 | ||
+ | !MESSAGE Execution Error | ||
+ | !STACK 1 | ||
+ | org.eclipse.core.runtime.CoreException: 343bf3cf-520e-4fca-94b0-f9673d08fae3: FAILED | ||
+ | ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. | ||
+ | must have at least 2 processes, not 1 | ||
+ | ::::PoePid=2679:::: | ||
+ | argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow | ||
+ | |||
+ | |||
+ | at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329) | ||
+ | at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160) | ||
+ | at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591) | ||
+ | at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233) | ||
+ | at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61) | ||
+ | at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308) | ||
+ | at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95) | ||
+ | at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53) | ||
+ | !SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:51:16.469 | ||
+ | !MESSAGE 343bf3cf-520e-4fca-94b0-f9673d08fae3: FAILED | ||
+ | ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. | ||
+ | must have at least 2 processes, not 1 | ||
+ | ::::PoePid=2679:::: | ||
+ | argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow | ||
+ | |||
+ | |||
+ | @@@ In CleanupStep.process projname=shallow_Linux configuration=Sample 3 Fail projectLocation=/u/bwatt | ||
+ | </source> | ||
+ | |||
+ | The sample plugin XML contains references to the previous three workflows as "Sample 1" file workflow1.xml. "Sample 2" file workflow2.xml, and "Sample 3" file workflow3.xml. It also defines three analysis tools as Java classes BeforeStep, AfterStep and CleanupStep. Each of these tools output a single line of output when their process method is executed, for example, "@@@ In [BeforeStep|AfterStep|CleanupStep].process ...". | ||
+ | |||
+ | <source lang="XML"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <?eclipse version="3.2"?> | ||
+ | <plugin> | ||
+ | |||
+ | <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> | ||
+ | <workflowDefinitionXML | ||
+ | file="workflow1.xml" | ||
+ | name="Sample 1"> | ||
+ | </workflowDefinitionXML> | ||
+ | </extension> | ||
+ | |||
+ | <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> | ||
+ | <workflowDefinitionXML | ||
+ | file="workflow2.xml" | ||
+ | name="Sample 2"> | ||
+ | </workflowDefinitionXML> | ||
+ | </extension> | ||
+ | |||
+ | <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> | ||
+ | <workflowDefinitionXML | ||
+ | file="workflow3.xml" | ||
+ | name="Sample 3"> | ||
+ | </workflowDefinitionXML> | ||
+ | </extension> | ||
+ | |||
+ | <extension point="org.eclipse.ptp.etfw.dataManagers"> | ||
+ | <PerformanceDataManager | ||
+ | class="com.sample.workflow.BeforeStep"> | ||
+ | </PerformanceDataManager> | ||
+ | </extension> | ||
+ | |||
+ | <extension point="org.eclipse.ptp.etfw.dataManagers"> | ||
+ | <PerformanceDataManager | ||
+ | class="com.sample.workflow.AfterStep"> | ||
+ | </PerformanceDataManager> | ||
+ | </extension> | ||
+ | |||
+ | <extension point="org.eclipse.ptp.etfw.dataManagers"> | ||
+ | <PerformanceDataManager | ||
+ | class="com.sample.workflow.CleanupStep"> | ||
+ | </PerformanceDataManager> | ||
+ | </extension> | ||
+ | |||
+ | </plugin> | ||
+ | </source> | ||
+ | |||
+ | Below is the BeforeStep.java Java file. The BeforeStep.java, AfterStep.java and CleanupStep.java files are copies of one another with only their names and internal strings changed. Therefore only the BeforeStep.java file is provided. | ||
+ | |||
+ | <source lang="Java"> | ||
+ | package com.sample.workflow; | ||
+ | |||
+ | import org.eclipse.core.runtime.CoreException; | ||
+ | import org.eclipse.debug.core.ILaunchConfiguration; | ||
+ | import org.eclipse.ptp.etfw.AbstractToolDataManager; | ||
+ | |||
+ | public class BeforeStep extends AbstractToolDataManager { | ||
+ | |||
+ | @Override | ||
+ | public String getName() { | ||
+ | String result = "BeforeStep"; | ||
+ | return result; | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void cleanup() { | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void process(String projname, ILaunchConfiguration configuration, String projectLocation) throws CoreException { | ||
+ | System.out.println("@@@ In BeforeStep.process projname="+projname+" configuration="+configuration+" projectLocation="+projectLocation); | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void view() { | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public void setExternalTarget(boolean external) { | ||
+ | } | ||
+ | |||
+ | } | ||
+ | </source> | ||
+ | |||
+ | == FAQ == | ||
+ | |||
+ | * What happens to attributes that are prefixed with the <configId>? Answer: They become program arguments at launch. | ||
+ | * What happens to attributes that are prefixed with the <configVarId>? Answer They become environment variables at launch. | ||
+ | * What happens to attributes that are not prefixed with either <configId> or <configVarId>? Answer: ETFw with JAXB parsing won't know what those attributes are and wouldn't do anything with them except put them in the launch config. | ||
+ | |||
+ | == References == | ||
+ | |||
+ | * The ETFw documentation at: http://wiki.eclipse.org/PTP/ETFw/PTP_External_Tools_Framework | ||
+ | * The rm (resource manager) documentation is located at: http://wiki.eclipse.org/PTP/designs/Resource_Manager_Configuration | ||
+ | * The rm (resource manager) schema is located at: http://eclipse.org/ptp/schemas/rm.xsd |
Latest revision as of 18:32, 22 March 2013
Contents
- 1 Overview
- 2 Extension Point
- 3 Creating an ETFw Workflow
- 4 Appendix 1: PerfSuite Example
- 5 Appendix 2: Converting ETFw XML to ETFw Resource Manager (RM) JAXB XML
- 6 Appendix 3: Temporary XML Schema Modification until Officially Committed
- 7 Appendix 4: Conditional Workflow Processing Examples
- 8 FAQ
- 9 References
Overview
The intent of this user guide is to provide information on writing ETFw XML workflows using Resource Manager (RM) JAXB by going through the various parts of the workflow. This user guide is not yet complete so if you are currently using this page as a reference for building JAXB workflows, take note that some of how this information is organized may change.
Extension Point
The extension point for adding new JAXB ETFw workflows is org.eclipse.ptp.etfw.jaxb.workflows. The following information is required for a new workflow:
- workflowDefinitionXML
- name - the name of the tool. This is displayed in the tool selection dropdown menu (e.g. TAU, PPW_UPC, etc).
- file - the path to the XML file containing the ETFw workflow.
<extension point="org.eclipse.ptp.etfw.jaxb.workflows"> <workflowDefinitionXML name="TAU" file="TAU.xml"> </workflowDefinitionXML> </extension>
Creating an ETFw Workflow
This section explains how to create new ETFw workflows, provide reference information for the XML tags inside an ETFw workflow, and show some snippets of the TAU XML file. Each ETFw workflow begins with the top-level tag <etfwTool>. Within this top-level tag can be one or more Control Data (<controlData>), Build Tool (<buildTool>), Execution Tool (<execTool>) and/or Analysis Tool (<analysisTool>) tags.
<etfwTool> <controlData> ... </controlData> <buildTool> ... </buildTool> <execTool> ... </execTool> <analysisTool> ... </analysisTool> </etfwTool>
Control Data
For those that are familiar with creating target configurations, this is probably a familiar term. The control data tag contains all of the attributes that are associated with the workflow. The attributes are used to control UI actions and store information based on user selections. Below is a snippet from the ETFw TAU XML workflow. These attributes were selected because they illustrate how environment variables are stored, how UI options can be translated into program arguments and how a program argument can be paired with another attribute that has the value to pass in. In the next few sub-sections, each set of attributes are explained in more detail with the corresponding XML UI code.
<controlData> <!-- This is how an environment variable, TAU_SYNCHRONIZE_CLOCKS is set --> <attribute name="TAU Runtime.performance.options.environmentvariables.configuration_id_TAU_SYNCHRONIZE_CLOCKS" type="boolean" translateBooleanAs="1, "> <rm:default>1</rm:default> </attribute> <!-- This is how a program option is set, e.g. -optVerbose, which gets passed as a command line argument --> <attribute name="Tau Compiler.performance.options.configuration_id_-OPTVERBOSE_ARGUMENT_DEFAULT" type="boolean" translateBooleanAs="-optVerbose, "> <rm:description>Turn on verbose debugging message</rm:description> <rm:tooltip>Turn on verbose debugging message</rm:tooltip> <rm:default> </rm:default> </attribute> <!-- These last two attributes contain the program argument, -optPdtDir=, and the value to set it equal to --> <attribute name="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT" type="boolean" translateBooleanAs="-optPdtDir=, "> <rm:description></rm:description> <rm:tooltip></rm:tooltip> <rm:default> </rm:default> </attribute> <attribute name="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED" type="string"> <rm:default></rm:default> </attribute> </controlData>
Environment Variables Attributes
The primary parts of the attribute for setting environment variables are:
- name
- TAU Runtime.performance.options.environmentvariables.configuration_id_ is the key and should match the option panes <configVarId /> tag to which it belongs.
- TAU_SYNCHRONIZE_CLOCKS is the environment variable to set.
- type
- boolean
- string
- choice
- integer
- translateBooleanAs - In many cases, environment attributes are tied to checkbox UI options that returns a boolean that needs to be translated to something else (e.g. 1 or 0, or even a string). In the case of this attribute above, the boolean is translated as 1 for true, empty for false.
Below is a snippet of the XML workflow that creates the checkbox attribute and associate it with a tool pane. The critical parts to understand are the <configVarId> and the <rm:widget> tags. The other XML tags are explained later in this document.
<execTool tool-name="TAU Runtime"> <global> <toolPanes virtual="false" embedded="false"> <configId>TAU Runtime.performance.options.configuration_id_</configId> <configVarId>TAU Runtime.performance.options.environmentvariables.configuration_id_</configVarId> <optionPane> <rm:title>Tau Runtime</rm:title> <rm:layout> <rm:grid-layout /> </rm:layout> <rm:composite> <rm:layout> <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" /> </rm:layout> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> </rm:layout-data> <rm:widget type="checkbox" title="Synchronize Clocks" style="SWT.LEFT" attribute="TAU Runtime.performance.options.environmentvariables.configuration_id_TAU_SYNCHRONIZE_CLOCKS"> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="3" /> </rm:layout-data> </rm:widget> </rm:composite> </optionPane> </toolPanes> </global> </execTool>
Program Argument Attributes
This section discusses how UI options get translated into program arguments using the above control data as an example. In the Control Data, the option -optVerbose should get passed as a program argument based on a boolean translation (similar to the environment variable). As with the environment variable, the main parts of the attribute are:
- name
- Tau Compiler.performance.options.configuration_id_ is the key and should match the option panes <configId /> tag to which it belongs. This lets the system know that it is a program argument for this tools option pane and the value should be passed to the tool.
- -OPTVERBOSE_ARGUMENT_DEFAULT - Unlike the environment variable, this string can be anything since it doesn't have any significance.
- type
- boolean
- string
- choice
- integer
- translateBooleanAs - Similar to environment variables, attributes containing program arguments are primarily tied to checkbox UI widgets that returns a boolean that needs to be translated to something else (e.g. a string value). In the case of this attribute above, the boolean is translated as -optVerbose for true, empty for false.
Below is a snippet of the XML workflow that creates the checkbox widget for this program argument and associate it with the specified tool pane. The critical parts to understand are the <configId> and the <rm:widget> tags. The other XML tags are explained later in this document.
<toolPanes virtual="false" embedded="false" pane-name="Tau Compiler" prepend-with="-tau_options=" enclose-with="'" separate-with=" "> <configId>Tau Compiler.performance.options.configuration_id_</configId> <configVarId>Tau Compiler.performance.options.environmentvariables.configuration_id_</configVarId> <optionPane> <rm:title>Tau Compiler</rm:title> <rm:layout> <rm:grid-layout /> </rm:layout> <rm:composite> <rm:layout> <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" /> </rm:layout> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> </rm:layout-data> <rm:widget type="checkbox" title="Verbose" style="SWT.LEFT" attribute="Tau Compiler.performance.options.configuration_id_-OPTVERBOSE_ARGUMENT_DEFAULT"> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="3" /> </rm:layout-data> </rm:widget> </rm:composite> </optionPane> </toolPanes>
Paired Program Argument Attributes
This section discusses the other type of program arguments, paired program arguments. That is, when you have something similar to the previous discussion about program arguments, but you want to pass a value for that argument. For example, looking at the control data, we want to pass a value for the program argument -optPdtDir= where one UI widget contains the program argument and another contains the value to pass. The last two attributes in the control data above represent paired program arguments and the details about how they are paired are highlighted below.
First attribute:
- name
- Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT
Second attribute:
- name
- Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED
As with normal program arguments, the first part of the name must match the value found in the tool pane's <configId /> field so that the system knows that the program argument is for the tool that the pane is associated with. The difference is that the second key that has the value must end with _SAVED. When parsing program arguments, the system looks at the launch configuration to see if there is another attribute that matches the original key value, but ends with _SAVED. This way it knows that -optPdtDir= should be paired with whatever value is in the second attribute. Below is a snippet of the XML workflow that creates the checkbox widget for this program argument and a browse widget that allows the user to either browse for the location of PDT or enter it. The critical parts to understand are the <configId> and the pair of <rm:widget> and <rm:browse> tags. The first is for the checkbox and the other for a special widget for the browse button / Text field. The other XML tags are explained later in this document.
<rm:widget type="checkbox" title="PdtDir" buttonId="PdtDir" style="SWT.LEFT" attribute="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT"> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="1" /> </rm:layout-data> </rm:widget> <rm:browse title="Browse..." localOnly="true" directory="true" textStyle="SWT.BORDER" attribute="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED"> <rm:text-layout-data> <rm:grid-data horizontalSpan="1" horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> </rm:text-layout-data> <rm:button-layout-data> <rm:grid-data horizontalSpan="1" horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="false" /> </rm:button-layout-data> <rm:text-control-state> <rm:enable-if button="PdtDir" selected="true" /> </rm:text-control-state> <rm:button-control-state> <rm:enable-if button="PdtDir" selected="true" /> </rm:button-control-state> </rm:browse>
ETFw Tag Reference
- <etfwTool> - Top level tag for enclosing an ETFw workflow.
- Attributes:
- xmlns:rm "http://eclipse.org/ptp/schemas" - resource manager (rm) namespace
- name - string - the workflow name
- prepend-execution - boolean - If true the actual executable is an argument passed to one or more additional utilities.
- recompile - boolean - If true the program is recompiled with performance-analysis specific modifications.
- explicit-execution - boolean - If true there is no automatic assumptions about when execute steps must be performed. Automatic execution does not take place after build steps!
- Attributes:
- <controlData> - Contains all of the attributes associated with the workflow. These are tied to UI widgets to save information based on user selections.
- <attribute name="" type="" translateBooleanAs="">
- <buildTool> - Represents a compilation step in the workflow.
- Attributes:
- tool-id - string - a unique tag for this application. Optional.
- tool-name - string - name of the tool
- tool-type - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file.
-
require-true - string - a launch configuration attribute name which causes this tool step execute if it is defined.Deprecated - use <tool-state> instead - replace-compiler - boolean - specify true if the compiler command is entirely replaced rather than prepended.
- set-success-attribute - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution.
- <global> - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the <execTool> tag.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most likely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes.
- <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
- <optionPane> - this is where the User Interface is defined by adding widgets to control what options are available for the tool. It represents a UI tab from the RM JAXB schema.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <cc-compiler>, <cxx-compiler>, <f90-compiler>, upc-compiler, <all-compilers> - Special cases representing the different compiler types that can either replace or be prepended to the default compilers for those languages. If the individual compiler tags are not defined and a command is specified for allcompilers it replaces or prepends the command for every language. If the individual compilers are defined along with allcompilers the individual compilers are used and each is given arguments defined by allcompilers. Since these are all represented by the same data type, this can probably be simplified.
- tool-id - string - a unique tag for this application. Optional.
- tool-name - string - name of the tool
- tool-command - string - command used to invoke the tool
- tool-group - string - tools in the same group are assumed to share the same binary location
- out-to-file - string - the file to which the standard out of this tool must be written
- visualizer - boolean - if true, the command is launched and the output is not handled. Otherwise, output is manged for printing on the console.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1.
- <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
- <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
- <tool-state> - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's set-success-attribute.
- <execute-if attribute="" [value=""]> - execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
- <do not execute-if> - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
- <execute-if> - execute this tool step if the contained conditional expression is true.
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <do not execute-if> - do not execute this tool step if the contained conditional expression is true.
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- Attributes:
- <execTool> - Represents a execution step in the workflow.
- Attributes:
- tool-id - string - a unique tag for this application. Optional.
- tool-name - string - name of the tool
- tool-type - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file.
-
require-true - string - a launch configuration attribute name which causes this tool step execute if it is defined.Deprecated - use <tool-state> instead - prepend-execution - boolean - if true, the actual executable is an argument passed to one or more utilities
- replace-execution - boolean - if true, the executable and arguments in the launch configuration are ignored and the utilities are run instead
- set-success-attribute - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution.
- <global> - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the <execTool> tag.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most liklely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes.
- <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
- <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <execUtils>
- tool-id - string - a unique tag for this application. Optional.
- tool-name - string - name of the tool
- tool-command - string - command used to invoke the tool
- tool-group - string - tools in the same group are assumed to share the same binary location
- out-to-file - string - the file to which the standard out of this tool must be written
- visualizer - boolean - if true, the command is launched and the output is not handled. Otherwise, output is printed on the console.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1.
- <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
- <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
- <tool-state> - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's set-success-attribute.
- <execute-if attribute="" [value=""]> - execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
- <do not execute-if> - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
- <execute-if> - execute this tool step if the contained conditional expression is true.
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <do not execute-if> - do not execute this tool step if the contained conditional expression is true.
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- Attributes:
- <analysisTool> - Represents a analysis step in the workflow.
- Attributes:
- tool-id - string - a unique tag for this application. Optional.
- tool-name - string - name of the tool
- tool-type - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file.
-
require-true - string - a launch configuration attribute name which causes this tool step execute if it is defined.Deprecated - use <tool-state> instead - depth - integer -
- useDefaultLocation - boolean -
- useLatestFileOnly - boolean -
- set-success-attribute - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution.
- <global> - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the <execTool> tag.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most likely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes.
- <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
- <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <analysis-commands>
- tool-id - string - a unique tag for this application. Optional.
- tool-name - string - name of the tool
- tool-command - string - command used to invoke the tool
- tool-group - string - tools in the same group are assumed to share the same binary location
- out-to-file - string - the file to which the standard out of this tool must be written
- visualizer - boolean - if true, the command is launched and the output is not handled. Otherwise, output is manged for printing on the console.
- <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
- <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1.
- <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
- <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
- <for-all-like> - TBD
- <tool-state> - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's set-success-attribute.
- <execute-if attribute="" [value=""]> - execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
- <do not execute-if> - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
- <execute-if> - execute this tool step if the contained conditional expression is true.
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <do not execute-if> - do not execute this tool step if the contained conditional expression is true.
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
- <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
- Attributes:
Appendix 1: PerfSuite Example
This section provides detailed steps for creating an ETFw XML workflow for the PerfSuite profiling tool. This example assumes that PerfSuite is compiled and running on your machine with PAPI support. Most of PerfSuite's options can either be passed to the psrun executable at the command line or set as environment variables. For this example, most are passed at the command line and one is set as an environment variable to illustrate how the ETFw JAXB system works.
The profiling tool from PerfSuite we want to run is psrun. The configurable commands are listed below under three categories, environment variables, program arguments and paired program arguments:
- Environment Variables
- File Format - output the results in XML or plain text.
- Program Arguments
- MD5 checksum - include MD5 checksums in output
- Paired Program Arguments
- Configuration - specify the configuration file to use.
- Domain - select the counting domain (user, kernel, all)
- POSIX - enable POSIX thread support
- Resource Usage - include resource usage statistics
- Resource Usage Only - include only resource usage statistics
- Write Signal Numbers - Specify signal numbers to write before process exits.
- Overflow Threshold - specify overflow threshold to use for profiling
The environment variables is set in the environment prior to launch, program arguments and paired program arguments are passed to the psrun executable at the command line. For example, to specify that we include md5 checksums and set the domain to kernel the command is:
psrun --md5 -d kernel shallow
where shallow is the name of the program executable to profile. Now that we know the inputs we need to tie to the User Interface (UI), we can start building the XML workflow that ties the UI selections to program arguments or environment variables.
The extension point for PerfSuite is shown below:
<extension point="org.eclipse.ptp.etfw.jaxb.workflows"> <workflowDefinitionXML name="PerfSuite" file="perfsuite.xml"> </workflowDefinitionXML> </extension>
Since PerfSuite is run with the program executable as input, we don't need to concern ourselves with the buildTool and analysisTool tags. We only need the execTool tag. The basic workflow is something similar to the one below:
<etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas" xsi:schemaLocation="etfw_tool_type.xsd" name="perfsuite" prepend-execution="false" recompile="false" explicit-execution="false"> <!-- attributes are stored in the control data --> <controlData> </controlData> <!-- This is the tool to execute --> <execTool tool-name="PerfSuite"> </execTool> </etfwTool>
For simplicity, we just add the necessary pieces to perform the previous example (e.g. psrun --md5 -d kernel shallow) and specify that we want to have the output in XML (by specifying the environment variable PS_HWPC_FORMAT.
<etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas" xsi:schemaLocation="etfw_tool_type.xsd" name="perfsuite" prepend-execution="false" recompile="false" explicit-execution="false"> <!-- attributes are stored in the control data ---> <controlData> <attribute name="PERFSUITE_psrun.environmentvariables.configuration_id_PS_HWPC_FORMAT" type="choice"> <rm:description>Specify the output format (XML or plain text)</rm:description> <rm:choice>xml,text</rm:choice> <rm:default>xml</rm:default> </attribute> <attribute name="PERFSUITE_psrun.configuration_id_-MD5" type="boolean" translateBooleanAs="--md5, "> <rm:description>Include MD5 checksums in output</rm:description> <rm:default> </rm:default> </attribute> <attribute name="PERFSUITE_psrun.configuration_id_-DOMAIN" type="boolean" translateBooleanAs="-d, "> <rm:description>Specify domain</rm:description> <rm:default> </rm:default> </attribute> <attribute name="PERFSUITE_psrun.configuration_id_-DOMAIN_SAVED" type="choice"> <rm:description>Specified domain</rm:description> <rm:choice>user,kernel,all</rm:choice> <rm:default>user</rm:default> </attribute> </controlData> <execTool tool-name="PerfSuite"> <!-- This is the set of tools to execute, in this case just one tool is defined --> <execUtils tool-command="psrun"> <!-- A single tool could have multiple panes, in this case there is just one --> <toolPanes virtual="false" embedded="false"> <configId>PERFSUITE_psrun.configuration_id_</configId> <configVarId>PERFSUITE_psrun.environmentvariables.configuration_id_</configVarId> <!-- This is the actual UI tab that is displayed with the defined UI widgets --> <optionPane> <rm:title>PerfSuite</rm:title> <rm:layout> <rm:grid-layout /> </rm:layout> <rm:composite> <rm:layout> <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" /> </rm:layout> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> </rm:layout-data> <rm:widget type="combo" title="File Format" readOnly="true" style="SWT.LEFT" attribute="PERFSUITE_psrun.environmentvariables.configuration_id_PS_HWPC_FORMAT"> <rm:layout-data> <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="2" /> </rm:layout-data> <rm:tooltip>Output format, either XML or text</rm:tooltip> </rm:widget> <rm:widget type="checkbox" title="Domain" buttonId="domain-button" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-DOMAIN"> <rm:layout-data> <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="1" /> </rm:layout-data> <rm:tooltip>Select counting domain (user, kernel, all)</rm:tooltip> </rm:widget> <rm:widget type="combo" readOnly="true" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-DOMAIN_SAVED"> <rm:layout-data> <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="2" /> </rm:layout-data> <rm:control-state> <rm:enable-if button="domain-button" selected="true" /> </rm:control-state> </rm:widget> <rm:widget type="checkbox" title="MD5 checksum" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-MD5"> <rm:layout-data> <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="3" /> </rm:layout-data> <rm:tooltip>Include MD5 checksums in output</rm:tooltip> </rm:widget> </rm:composite> </optionPane> </toolPanes> </execUtils> </execTool> </etfwTool>
Using the above XML workflow as a reference, let's break down where the pieces of the command psrun --md5 -d kernel shallow are in the workflow. If you find the execUtils tag, you see that it contains the tool-command we want to run, 'psrun. The rest of what is contained between the tags allows the user to select the additional input flags. For example, looking at the checkbox widget with title MD5 checksum, you see that it is tied to the attribute PERFSUITE_psrun.configuration_id_-MD5. If you find that attribute in the controlData section, it translates to --md5 when it is selected and the empty string when it is not selected. In addition, notice that the first part of the attribute, PERFSUITE_psrun.configuration_id_ corresponds to the configId for that tool's pane. This is how the system understands which attributes belong to which tools so the correct tool gets the --md5 input flag.
The rest of the inputs, including the environment variable for specifying text or XML output can be deduced by reviewing the sections above about setting environment variables and pairing attributes and then locating the UI widgets in the XML workflow.
Appendix 2: Converting ETFw XML to ETFw Resource Manager (RM) JAXB XML
This appendix is to aid developers in converting existing ETFw XML to the new ETFw Resource Manager (RM) JAXB XML.
1. The existing "org.eclipse.ptp.etfw.workflows" extension point with <workflowDefinitionXML> containing XMLFile in plugin.xml file from:
<extension point="org.eclipse.ptp.etfw.workflows"> <workflowDefinitionXML XMLFile="HPCTOptions.xml"> </workflowDefinitionXML> </extension>
to new "org.eclipse.ptp.etfw.jaxb.workflows" extension point with <workflowDefinitionXML> containing file and name in plugin.xml file :
<extension point="org.eclipse.ptp.etfw.jaxb.workflows"> <workflowDefinitionXML file="HPCTOptions.xml" name="HPC Toolkit"> </workflowDefinitionXML> </extension>
2. Change outermost XML definition in HPCTOptions.xml file from <toolset.01><tool>:
<?xml version="1.0" encoding="UTF-8"?> <toolset.01> <tool name="HPC Toolkit" explicitexecution="true"> ... </tool> </toolset.01>
to <etfwTool> with matching explicit-execution and a <controlData> section in HPCTOptions.xml file:
<etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas" xsi:schemaLocation="etfw_tool_type.xsd" name="hpctoolkit" prepend-execution="false" recompile="false" explicit-execution="true"> <controlData> ... </controlData> ... </etfwTool>
3. Change each execute/global from <execute><global> in <toolset.01><tool>:
... <execute> <global name="HPC Toolkit"> ... </global> </execute> ...
to <execTool><global><toolPanes> with <configId> and <configVarId> in <etfwTool>:
... <execTool tool-name="HPC Toolkit"> <global> <toolPanes virtual="false" embedded="false"> <configId>HPCTOOLKIT_global.configuration_id_</configId> <configVarId>HPCTOOLKIT_global.environmentvariables.configuration_id_</configVarId> ... </toolPanes> <!-- ************************************************************************************** --> </global> </execTool> ...
4. Change each option pane from <optionpane> in <execute><global>:
... <optionpane title="Data Collection" virtual="true" displayoptions="false"> ... </optionpane> ...
to <optionPane><rm:composite> with <rm:title>, <rm:layout>, and <rm:composite> in <execTool><global><toolPanes>:
... <optionPane> <rm:title>Data Collection</rm:title> <rm:layout> <rm:grid-layout /> </rm:layout> <rm:composite> <rm:layout> <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" /> </rm:layout> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" /> </rm:layout-data> ... </rm:composite> </optionPane> ...
5a. Checkbox: Change each checkbox environment variable from type=toggle <togoption> in <optionpane>:
... <togoption label="Generate unique filenames:" optname="HPC_UNIQUE_FILE_NAME" envvar="true" tooltip="Generate unique filenames for each MPI task's output (HPC_UNIQUE_FILE_NAME)"> <optvalue type="toggle" seton="yes" /> </togoption> ...
to a type=boolean attribute in <controlData> and type=checkbox RM widget definition in <optionPane><rm:composite>:
... <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_UNIQUE_FILE_NAME" type="boolean" translateBooleanAs="yes,no"> </attribute> ... <rm:widget type="checkbox" title="Generate unique filenames:" style="SWT.LEFT" attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_UNIQUE_FILE_NAME"> <rm:layout-data> <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="3" /> </rm:layout-data> <rm:tooltip>Generate unique filenames for each MPI task's output (HPC_UNIQUE_FILE_NAME)</rm:tooltip> </rm:widget> ...
5b. Text Field: Change each text field environment variable from type=text <togoption> in <optionpane>:
... <togoption label="Output file name:" optname="HPC_OUTPUT_NAME" envvar="true" required="true" tooltip="Specify output file name (HPC_OUTPUT_NAME)"> <optvalue type="text" fieldrequired="true" /> </togoption> ...
to a type=string attribute in <controlData> and type=label & type=text RM widget definitions in <optionPane><rm:composite>:
... <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_OUTPUT_NAME" type="string"> </attribute> ... <rm:widget type="label" style="SWT.LEFT"> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.BEGINNING" verticalAlign="SWT.CENTER" grabExcessHorizontal="false" /> </rm:layout-data> <rm:fixed-text>Output file name: </rm:fixed-text> </rm:widget> <rm:widget type="text" style="SWT.BORDER" attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_OUTPUT_NAME"> <rm:layout-data> <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="2" /> </rm:layout-data> <rm:tooltip>Specify output file name (HPC_OUTPUT_NAME)</rm:tooltip> </rm:widget> ...
5c. Choice: Change each choice environment variable from type=combo <togoption> in <optionpane>:
... <togoption label="Application time criteria: " optname="HPC_EXCEPTION_METRIC" envvar="true" required="true" tooltip="Select run time criteria: wall clock or elapsed time (HPC_EXCEPTION_METRIC)"> <optvalue type="combo" items="ELAPSED_TIME:::CPU_TIME" /> </togoption> ...
to a type=choice attribute in <controlData> and type=combo RM widget definition in <optionPane><rm:composite>:
... <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_EXCEPTION_METRIC" type="choice"> <rm:choice>ELAPSED_TIME,CPU_TIME</rm:choice> <rm:default>ELAPSED_TIME</rm:default> </attribute> ... <rm:widget type="combo" title="Application time criteria: " readOnly="true" style="SWT.LEFT" attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_EXCEPTION_METRIC"> <rm:layout-data> <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="2" /> </rm:layout-data> <rm:tooltip>Select run time criteria: wall clock or elapsed time (HPC_EXCEPTION_METRIC)</rm:tooltip> </rm:widget> ...
Appendix 3: Temporary XML Schema Modification until Officially Committed
The ETFw schema file "etfw_tool_type.xsd", which can be found in project org.eclipse.ptp.etfw.jaxb needs to be modified. It is presently pointing at where the RM schema was located in a local development environment workspace (/home/cnavarro/workspaces/ptp-dev/git/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd). If you open this ETFw schema file, near the top you'll see a few comments about the resource manager schema and why it points at a local one instead of the existing remote one. In short, the ETFw schema file was modified because the resource manager schema needed to be changed to support the additional TAU widgets. Otherwise, TAU wouldn't work since it would always fail to load those widgets.
If you apply all the patches (for both bug reports: Bug 397684 - ETFw using JAXB framework, and Bug 397685 - TAU JAXB workflow for ETFw), then you have to update the ETFw schema to point at the resource_manager_type.xsd in your local org.eclipse.ptp.rm.jaxb.core project. If you apply only the framework itself (for bug report: Bug 397684 - ETFw using JAXB framework) , then you can safely point at the RM schema at http://eclipse.org/ptp/schemas/rm.xsd. In other word, if you patch for the TAU support then you need the modified RM schema.
Here is what you do for the time being until these changes are formally released:
Changed in project org.eclipse.ptp.etfw.jaxb in data/etfw_tool_type.xsd from
<!-- Point this schema to the location of the resource manager schema. This is required until the new widgets are added for TAU --> <xs:import schemaLocation="file:/home/cnavarro/workspaces/ptp-dev/git/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd" namespace="org.eclipse.ptp" />
to
<!-- Point this schema to the location of the resource manager schema. This is required until the new widgets are added for TAU --> <xs:import schemaLocation="file:User_Development_Environment_Directory/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd" namespace="org.eclipse.ptp" />
Appendix 4: Conditional Workflow Processing Examples
The first workflow, workflow1.xml, is patterned after an existing workflow, that is, one that does not contain any <tool-state><execute-if> elements. This workflow has three steps. The first is a pre-processing analysis step which invokes the Java class BeforeStep. The second is the execution step which launches the application specified within the launch configuration. The third step is a post-processing analysis step which invokes the Java class AfterStep. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the host Eclipse output for both a successful execution and an unsuccessful one.
<?xml version="1.0" encoding="UTF-8"?> <etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd" name="SAMPLE1" prepend-execution="false" recompile="false" explicit-execution="true"> <analysisTool> <analysis-commands tool-command="BeforeStep" tool-group="internal" /> </analysisTool> <execTool/> <analysisTool> <analysis-commands tool-command="AfterStep" tool-group="internal" /> </analysisTool> </etfwTool>
For the first workflow the console output of a successful execution is as follows. First the BeforeStep writes its output, next the execution step runs successfully, and finally the AfterStep writes its output.
@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 1 Pass projectLocation=/u/bwatt !ENTRY org.eclipse.ptp.rm.lml.monitor.core 4 4 2013-03-22 14:50:03.892 !MESSAGE /home/bwatt/runtime-Eclipse/.metadata/.plugins/org.eclipse.ptp.rm.lml.monitor.core/monitors.xml (No such file or directory) @@@ In AfterStep.process projname=shallow_Linux configuration=Sample 1 Pass projectLocation=/u/bwatt
For the first workflow the console output of a failed execution is as follows. First the BeforeStep writes its output, next the execution step fails, which causes the AfterStep step to NOT run. Internally a global state variable is used. Initially is is set to true. Before each step is run this variable is checked if it is true the step is run if it is false the step is not run. After each step is run the step's success is 'anded' into the global state. Therefore following along with this workflow's execution, the global state is true and the BeforeStep is runs and completes successfully, next because the global state is still true the execution step runs, but it fails which sets the global state to false, which causes the AfterStep to NOT run. In other words, once the global state is set to false then all of the follow-on steps are not executed, that is, failure cascades unless a step uses the new <tool-state><execute-if> elements. which this workflow does not.
@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 1 Fail projectLocation=/u/bwatt !ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:50:17.313 !MESSAGE Execution Error !STACK 1 org.eclipse.core.runtime.CoreException: d956bfa5-5b7b-458b-ba67-cbcc9e665cc0: FAILED ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. must have at least 2 processes, not 1 ::::PoePid=2286:::: argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160) at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591) at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233) at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61) at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308) at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95) at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53) !SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:50:17.314 !MESSAGE d956bfa5-5b7b-458b-ba67-cbcc9e665cc0: FAILED ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. must have at least 2 processes, not 1 ::::PoePid=2286:::: argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow
The second workflow, workflow2.xml, contains a simple example of the new workflow conditional processing support. This workflow has now four steps. The first is a pre-processing analysis step which invokes the Java class BeforeStep. The second is the execution step which launches the application specified within the launch configuration, but it now sets the attribute "x". The third step is a post-processing analysis step which invokes the Java class AfterStep. The second step should only runs when the execution step succeeds. The fourth step is another post-processing analysis step which invokes the Java class CleanupStep. This new step should only runs when the execution step fails. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the host Eclipse output for both a successful execution and an unsuccessful one.
<?xml version="1.0" encoding="UTF-8"?> <etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd" name="SAMPLE2" prepend-execution="false" recompile="false" explicit-execution="true"> <analysisTool> <analysis-commands tool-command="BeforeStep" tool-group="internal" /> </analysisTool> <execTool set-success-attribute="x"/> <analysisTool> <analysis-commands tool-command="AfterStep" tool-group="internal" /> </analysisTool> <analysisTool> <analysis-commands tool-command="CleanupStep" tool-group="internal" /> <tool-state> <execute-if attribute="x" value="false"/> </tool-state> </analysisTool> </etfwTool>
For the second workflow the console output of a successful execution is as follows. First the BeforeStep writes its output. Next the execution step runs successfully. Afterwards since it includes a 'set-success-attribute' at sets the specified launch configuration attribute "x" to the string "true" and updates the global state to still be true. Next the AfterStep writes its output. The AfterStep runs because it does not contain any <tool-state><execute-if> elements which means it checks the global state which is true so it runs. However CleanupStep is different. It contains some <tool-state><execute-if> elements and global state is ignored and instead the conditional expression is evaluated. The expression specified that step 4 only runs if the value of the "x" attribute is "false" and since it is actually "true" the CleanupStep does NOT run.
@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 2 Pass projectLocation=/u/bwatt @@@ In AfterStep.process projname=shallow_Linux configuration=Sample 2 Pass projectLocation=/u/bwatt
For the second workflow the console output of a failed execution is as follows. As before first the BeforeStep writes its output. But then the execution step fails. Afterwards since it includes a 'set-success-attribute' at sets the specified launch configuration attribute "x" to the string "false" and updates the global state to false. The AfterStep does not runs because it does not contain any <tool-state><execute-if> elements which means it checks the global state which is false so it is NOT run. However CleanupStep evaluates its conditional expression which causes it to runs because the value of the "x" attribute is actually "false".
@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 2 Fail projectLocation=/u/bwatt !ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:50:57.876 !MESSAGE Execution Error !STACK 1 org.eclipse.core.runtime.CoreException: 2cb4d5ff-8c36-448d-9bda-de295ea4a45c: FAILED ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. must have at least 2 processes, not 1 ::::PoePid=2512:::: argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160) at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591) at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233) at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61) at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308) at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95) at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53) !SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:50:57.876 !MESSAGE 2cb4d5ff-8c36-448d-9bda-de295ea4a45c: FAILED ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. must have at least 2 processes, not 1 ::::PoePid=2512:::: argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow @@@ In CleanupStep.process projname=shallow_Linux configuration=Sample 2 Fail projectLocation=/u/bwatt
The third workflow, workflow3.xml, contains a more complex example of the new workflow conditional processing support. This workflow still has four steps. The first still invokes the Java class BeforeStep, but it also now sets the attribute "x". The second is the execution step, and now it sets the attribute "y". The third step invokes the Java class AfterStep. The second step should only runs when both the BeforeStep and the execution step succeeds. The fourth step invokes the Java class CleanupStep. This step only runs when either the BeforeStrep or execution step fails. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the host Eclipse output for both a successful execution and an unsuccessful one.
<?xml version="1.0" encoding="UTF-8"?> <etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd" name="SAMPLE3" prepend-execution="false" recompile="false" explicit-execution="true"> <analysisTool set-success-attribute="x"> <analysis-commands tool-command="BeforeStep" tool-group="internal" /> </analysisTool> <execTool set-success-attribute="y"> </execTool> <analysisTool> <analysis-commands tool-command="AfterStep" tool-group="internal" /> <tool-state> <do-not-execute-if> <or> <rule attribute="x" value="false"/> <rule attribute="y" value="false"/> </or> </do-not-execute-if> </tool-state> </analysisTool> <analysisTool> <analysis-commands tool-command="CleanupStep" tool-group="internal" /> <tool-state> <execute-if> <or> <rule attribute="x" value="false"/> <rule attribute="y" value="false"/> </or> </execute-if> </tool-state> </analysisTool> </etfwTool>
For the third workflow the console output of a successful execution is as follows. First the BeforeStep writes its output and sets the specified attribute "x" to the string "true". Next the execution step runs successfully and sets the attribute "y" to the string "true". Next the AfterStep conditional expression is evaluated. This step "does not execute" if either attribute "x" or attribute "y" are "false". Both are "true" so it does run and writes its output. Next the CleanupStep conditional expression is evaluated. This step "does execute" if either attribute "x" or attribute "y" are "false". Both are "true" so it does NOT run.
@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 3 Pass projectLocation=/u/bwatt @@@ In AfterStep.process projname=shallow_Linux configuration=Sample 3 Pass projectLocation=/u/bwatt
For the third workflow the console output of a failed execution is as follows. First the BeforeStep writes its output and sets the specified attribute "x" to the string "true". Next the execution step fails and sets the attribute "y" to the string "false". Next the AfterStep conditional expression is evaluated. This step "does not execute" if either attribute "x" or attribute "y" are "false". One of them is "false" so it does NOT run. Next the CleanupStep conditional expression is evaluated. This step "does execute" if either attribute "x" or attribute "y" are "false". One of them is "false" so it does run and writes its output.
@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 3 Fail projectLocation=/u/bwatt !ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:51:16.469 !MESSAGE Execution Error !STACK 1 org.eclipse.core.runtime.CoreException: 343bf3cf-520e-4fca-94b0-f9673d08fae3: FAILED ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. must have at least 2 processes, not 1 ::::PoePid=2679:::: argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329) at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160) at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591) at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233) at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61) at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308) at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95) at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53) !SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:51:16.469 !MESSAGE 343bf3cf-520e-4fca-94b0-f9673d08fae3: FAILED ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. must have at least 2 processes, not 1 ::::PoePid=2679:::: argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow @@@ In CleanupStep.process projname=shallow_Linux configuration=Sample 3 Fail projectLocation=/u/bwatt
The sample plugin XML contains references to the previous three workflows as "Sample 1" file workflow1.xml. "Sample 2" file workflow2.xml, and "Sample 3" file workflow3.xml. It also defines three analysis tools as Java classes BeforeStep, AfterStep and CleanupStep. Each of these tools output a single line of output when their process method is executed, for example, "@@@ In [BeforeStep|AfterStep|CleanupStep].process ...".
<?xml version="1.0" encoding="UTF-8"?> <?eclipse version="3.2"?> <plugin> <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> <workflowDefinitionXML file="workflow1.xml" name="Sample 1"> </workflowDefinitionXML> </extension> <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> <workflowDefinitionXML file="workflow2.xml" name="Sample 2"> </workflowDefinitionXML> </extension> <extension point="org.eclipse.ptp.etfw.jaxb.workflows"> <workflowDefinitionXML file="workflow3.xml" name="Sample 3"> </workflowDefinitionXML> </extension> <extension point="org.eclipse.ptp.etfw.dataManagers"> <PerformanceDataManager class="com.sample.workflow.BeforeStep"> </PerformanceDataManager> </extension> <extension point="org.eclipse.ptp.etfw.dataManagers"> <PerformanceDataManager class="com.sample.workflow.AfterStep"> </PerformanceDataManager> </extension> <extension point="org.eclipse.ptp.etfw.dataManagers"> <PerformanceDataManager class="com.sample.workflow.CleanupStep"> </PerformanceDataManager> </extension> </plugin>
Below is the BeforeStep.java Java file. The BeforeStep.java, AfterStep.java and CleanupStep.java files are copies of one another with only their names and internal strings changed. Therefore only the BeforeStep.java file is provided.
package com.sample.workflow; import org.eclipse.core.runtime.CoreException; import org.eclipse.debug.core.ILaunchConfiguration; import org.eclipse.ptp.etfw.AbstractToolDataManager; public class BeforeStep extends AbstractToolDataManager { @Override public String getName() { String result = "BeforeStep"; return result; } @Override public void cleanup() { } @Override public void process(String projname, ILaunchConfiguration configuration, String projectLocation) throws CoreException { System.out.println("@@@ In BeforeStep.process projname="+projname+" configuration="+configuration+" projectLocation="+projectLocation); } @Override public void view() { } @Override public void setExternalTarget(boolean external) { } }
FAQ
- What happens to attributes that are prefixed with the <configId>? Answer: They become program arguments at launch.
- What happens to attributes that are prefixed with the <configVarId>? Answer They become environment variables at launch.
- What happens to attributes that are not prefixed with either <configId> or <configVarId>? Answer: ETFw with JAXB parsing won't know what those attributes are and wouldn't do anything with them except put them in the launch config.
References
- The ETFw documentation at: http://wiki.eclipse.org/PTP/ETFw/PTP_External_Tools_Framework
- The rm (resource manager) documentation is located at: http://wiki.eclipse.org/PTP/designs/Resource_Manager_Configuration
- The rm (resource manager) schema is located at: http://eclipse.org/ptp/schemas/rm.xsd