Man page for buildrun


buildrun – run one program after another has completed successfully


buildrun -w control-directory   command1 [ argument... ]
buildrun -r control-directory [ command2 [ argument... ] ]


buildrun is a utility which you can use to wrap two separate commands, and it will wait to run the second command until the first command is not currently running and its last run completed successfully. This includes waiting while the first one runs several times (if the first few runs fail), and also includes not waiting at all if it's already true that the most recent run of the first command was successful.

You might use buildrun in situations where you want to run two commands in succession, but (for one reason or another) you'd rather have them run in separate shell sessions and therefore you don't want to take the obvious approach of simply issuing a compound command using the shell's && operator.

A typical scenario involves the first command being a software build process (a compile command, or make, or similar), and the second being some attempt to run the resulting program or its test suite or a debugger. You might want to run your build and test commands in separate shell sessions for several reasons: if it's convenient to give them different working directories, or in order to separate the shell command-recall histories (so that the build terminal has all the commands related to editing and searching source files, and the test terminal has the ones related to adjusting the test environment), or in order to separate their output (so that successive test runs appear adjacent to each other in the test terminal and can be easily compared, while the output from build commands is available for checking if it's needed but doesn't keep scrolling the test output off the screen).

To use buildrun, you must first decide on a location for a control directory which the two buildrun processes can use to communicate between themselves. Then, in one window, you run the command you want to run first (e.g. the compile operation), prefixed with a buildrun -w command giving the pathname of the control directory. For instance, you might run

buildrun -w /tmp/controldir make

Then, in another window, run the second command (e.g. a test or debugging command) prefixed with a similar buildrun -r command, for example

buildrun -r /tmp/controldir ./

The instance of buildrun run with -w will immediately run its command; the instance run with -r will wait for the -w command to complete, and then run its own command. If the first command fails, the buildrun -r process will continue to sleep; you can then correct the problem and re-run the compile, and buildrun -r will only wake up once an instance of buildrun -w's command completes successfully.

If you then immediately re-run buildrun -r without starting another build, it will run its command instantly without waiting. So you can repeat your testing or debugging, or run several different test runs, by simply recalling the same test command including the buildrun -r prefix.

(The option names -w and -r are intended to imply that the first command is writing some kind of resource, such as a compiled program or data file, and that the second command intends to read that resource and hence needs the first command to have written it correctly.)


You must specify one of -w and -r.

Runs buildrun in write mode. You must provide a command line; buildrun -w will run that command, and use the control directory to signal to any waiting buildrun -r instances when it has completed successfully.
Runs buildrun in read mode. If a command wrapped by buildrun -w is currently in progress, or if the last such command failed, then buildrun -r will wait until one succeeds before doing anything. However, if no buildrun -w is currently running and the last one completed successfully, buildrun -r will not wait at all.

If a command line is provided, buildrun -r will run that command after it finishes waiting. If no command line is provided, buildrun -r will simply return success when it finishes waiting.


This argument is mandatory in both -w and -r modes. It must give the pathname of a directory which the two instances of buildrun will use to communicate with each other.

You need not create the control directory; buildrun -w will create it the first time it runs. It will also be deleted every time buildrun -w's command completes successfully, because that's how success is communicated to buildrun -r. (A side effect of that is that if buildrun -r is run before ever running buildrun -w, it will behave as if there had been a successful -w run.)

The control directory should not be on a network-mounted filesystem, since network filesystems sometimes diverge from the normal Unix behaviour which buildrun relies on. Using a directory in /tmp is recommended.

Of course, instances of buildrun using different control directories will be completely independent of each other. So you can simultaneously run two or more pairs of commands each linked by their own pair of buildruns, and as long as each pair has a separate control directory, they won't interfere with each other.

command (and optional arguments)
The first word on buildrun's command line which is not an option or the control directory name will be treated as a command to be run by buildrun, and anything following that word will be treated as arguments to that command. The command will be run directly using the execvp(3) function, so shell syntax (pipes, redirections etc) is not supported. If you need your command to contain things like that, you can achieve it by explicitly invoking a shell, e.g.
buildrun -w /tmp/ctldir sh -c '(cmd1; cmd2 | cmd3) > outfile'

In buildrun -r mode, an alternative to doing that is simply not to provide a command at all, and instead tell your shell to run a complex command after buildrun, e.g.

buildrun -r /tmp/ctldir && (cmd1; cmd2 | cmd3) > outfile

(This alternative is not available with buildrun -w, since that has to run its command as a subprocess so that it can wait for it to finish and see whether it worked.)


buildrun is free software, distributed under the MIT licence. Type buildrun --licence to see the full licence text.

[buildrun version 20171014.cd9f6e3]