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
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).
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 ./test.sh
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
-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
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.
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.
-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
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.
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'
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 -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.