| pathopt2 - utility used to aid in tuning the PathScale compiler for higher performance with specific codes. |
| Basic usage |
| pathopt2 [-options] <build-command> [-arg1] ... |
| The pathopt2 tool iteratively tests different compiler options and option combinations with a set of files, tracks the results, selects the best option(s) within a subgroup, and then elevates those options within the test hierarchy. |
| pathopt2 runs the build-command using a set of options specified in a supplied configuration file. build-command is either a PathScale compiler invocation command (pathcc, pathf95, pathCC), a make command, or a script which eventually invokes the compiler, perhaps via a make command. The character @ is replaced in the command with the option from configfile being considered. |
| pathopt2 options are as follows: |
| -D |
| Don't redirect I/O to /dev/null. |
| -f <configfile> [ "pathopt2.xml" ] |
| The -f option is used to specify the filename of the pathopt2 XML configuration file. If it is not specified, the tool will first check for a file called pathopt2.xml in the current working directory and use it if present, otherwise the tool will use the file <install_path>/pathscale/share/pathopt2/pathopt2.xml provided with the compiler suite. |
| -g <external_configfile> |
| Loads in additional user-defined configfile(s). This allows a user to extend the pathopt2.xml file without having to modify it. |
| -j <number of jobs> [ 1 ] |
| Number of jobs to run with this command. The default is 1. |
| -M <directory name> [ `pwd` ] |
| Directory in which to run the pathopt2 tool. The default is the current working directory. |
| -n iterations [1] |
| Number of iterations to run on each option. The default is 1. |
| -r <test script> [ same as command ] |
| Test script. The default is the same as the script listed as the build-command argument. |
| -S <real|user|system|timing-file|rate-file> [ real ] |
| Specifies the performance metric to be used by pathopt2: |
| real: |
| the elapsed real time (this is the default) |
| user: |
| the CPU time spent executing in user mode |
| system: |
| the CPU time spent executing in system mode |
| timing-file: |
| to use a file containing a timing value |
| rate-file: |
| to use a file containing a rate value |
| The chosen metric is used to guide the choices made by the pathopt2 algorithms when selecting options for the best performance, and is used to sort the final output. |
| The interpretation of real, user, and system time is the same as the time(1) command. All three times will be displayed in the output. |
| Additionally, pathopt2 allows arbitrary performance metrics to be used to guide option selection using the timing-file and rate-file choices. When either of these options is used, pathopt2 sets an environment variable called PSC_METRIC_FILE with the name of a temporary file before running the command. The run command is required to write the performance metric into this file before it terminates. |
| pathopt2 then opens this file, reads a value from the file interpreted as a double-precision floating-point number, and deletes the temporary file. The only interpretation placed on these values is that smaller is better for timing, and that larger is better for rate. The actual units of the values do not matter as far as pathopt2 is concerned as it just performs relative comparisons. |
| -t <execution target> [ first in file ] |
| Use execution target, which corresponds to an <execute> tag found in configfile. The default is the first target in configfile. |
| -T |
| Run script in temporary directory. |
| -v |
| Generate more verbose output. |
| -w <columns for flags> [ 40 ] |
| Number of columns to use in formatting output. The default is 40. |
| -X |
| Don't print out a summary table. |
| Pathopt2 example |
| For example, to build the program `factorial' using the options in the file |
| `pathopt2.xml' use this command: |
| $ pathopt2 -f pathopt2.xml -r ./factorial pathcc @ -o factorial factorial.c |
| The pathopt2.xml configuration file is in <install_path>/pathscale/share/pathopt2. |
| Copyright (C) 2006 QLogic Corp. All Rights Reserved. |
| Copyright (C) 2006 PathScale, Inc. All Rights Reserved. |
| pathcc(1) pathf95(1) eko(7) |
| QLogic PathScale Compiler Suite User Guide |