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.
When you select Clean in the Project Workbook menu of the IDE, VisualAge C++ attempts to reset the build environment to the state it was in before the first build of the current project. However, VisualAge C++ cannot react to actions performed as a result of run directives or actions taken of the build process. Use this option to issue commands to complete the cleanup. For example, if your configuration file contains a run directive that creates a file, you can use run cleanup to delete that file.
Commands in a run cleanup directive are not run during a build that creates the targets specified in the configuration file. They run only when you select Clean. During cleanup, target, source and option directives are ignored and no compile or link steps are performed.
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
