run Configuration File Directive

The run directive starts a sequence of commands that run in a child process of the build. Typically you use run for command line programs that are required as part of the build and that are not performed implicitly by processing directives in the configuration file. Because the commands run in a child process, they inherit the environment, including all environment variables, of the build. However, environment variable settings made by the commands are not retained after the run directive processing is complete.

This diagram shows the syntax of the run directive:

The run directive has the following parameters:

before
after
cleanup
This optional parameter controls when the commands run in relation to the C++ compile and link.

sources (file_list)
This optional parameter specifies files that are input to the commands. The string list consists of file names, separated by commas. The file names are not passed to the commands that are run. They tell the build process what files must be available before issuing the commands. You can specify this parameter in addition to before, after or cleanup.

targets (file_list)
This optional parameter specifies files that are output by the commands to be run. The string list consists of file names, separated by commas. The file names are not passed to the commands that are run. They tell the build process what files will be available after the commands are completed. You can specify this parameter in addition to before, after and cleanup.

command_string_list
This list contains commands. In each string, specify what you would enter on the command line to run a program. Each command string can be a string literal or a string expression. For example, you can substitute variables for command line arguments of the programs, as in the following run directive, which sets the environment variable LC_ALL to the value of a configuration file variable named MyLocale and then runs the program setclock.

run "SET LC_ALL=" MyLocale, "setclock"

Each string in the command list is treated as a separate command and the commands run sequentially.  Be careful of using interactive commands; a system command that is waiting for user input will hang your build. Use the "force" or "noprompt" version of these commands.

By default the processing of commands ends as soon as one of the commands fails. To override this behavior, insert a dash before the first character in the command string. When a command starts with a dash, the dash is trimmed off and the return code is ignored. For example, the first two commands in the directive below are always run, but the third runs only if the first cp command is successful.

run "-rm baz.C", "cp foo.C bar.C", "cp bar.C baz.C"

If the child process that performs the commands terminates with a non-zero return code, the build ends.

When the Commands are Run
By default, commands in run directives are run in the order that the directives appear in the configuration file. Use the following optional clauses to influence when the build process runs the commands.

The table below summarizes the effect of these clauses.

Clause Description
before Run the commands represented by the list of strings.

Schedule the run before C++ compile and link.

after Run the commands represented by the list of strings.

Schedule the run after C++ compile and link.

cleanup Run the commands represented by the list of strings

Run only during cleanup, in which case the C++ compile and link is not performed.

sources(file_list)
Run the commands if any files in the list have timestamps later than the last build, or later than the timestamps of any files listed as targets of the run directive.

Schedule the run after all other run directives that create at least one of the files in the list as a target.

If one of the files is the target of C++ compile and link, schedule the run after compile and link. The before clause overrides this condition.

targets(file_list) Run the commands if any files in the list are not already available or have timestamps that are later than the last build.

Schedule the run before all other run directives that require at least one of the files in the list as a source.

If one of the files is a source of C++ compile and link, schedule the run before compile and link. The after clause overrides this condition.

You can combine the clauses in one run directive. It is possible to combine clauses and run directives in such a way that conditions conflict. For example, if one run directive has a source that is a target of a second run directive, and the second directive has a source that is a target of the first run directive, the build process cannot decide which run to perform first. In such situations, the run directives are processed in the order in which they appear in the configuration file.



Configuration Files
How Configuration Files Are Processed
Cleaning Up After Builds


Run Command Line Programs During Builds
Change a Build Setup
Build
Clean Up the Build Environment


Configuration File Directives
Build Options