| 1 | \cfg{man-identity}{buildrun}{1}{2012-08-01}{Simon Tatham}{Simon Tatham} |
| 2 | |
| 3 | \define{dash} \u2013{-} |
| 4 | |
| 5 | \title Man page for \cw{buildrun} |
| 6 | |
| 7 | \U NAME |
| 8 | |
| 9 | \cw{buildrun} \dash run one program after another has completed successfully |
| 10 | |
| 11 | \U SYNOPSIS |
| 12 | |
| 13 | \c buildrun -w control-directory command1 [ argument... ] |
| 14 | \e bbbbbbbb bb iiiiiiiiiiiiiiiii iiiiiiii iiiiiiii |
| 15 | \c buildrun -r control-directory [ command2 [ argument... ] ] |
| 16 | \e bbbbbbbb bb iiiiiiiiiiiiiiiii iiiiiiii iiiiiiii |
| 17 | |
| 18 | \U DESCRIPTION |
| 19 | |
| 20 | \cw{buildrun} is a utility which you can use to wrap two separate |
| 21 | commands, and it will wait to run the second command until the first |
| 22 | command is not currently running and its last run completed |
| 23 | successfully. This includes waiting while the first one runs several |
| 24 | times (if the first few runs fail), and also includes not waiting at |
| 25 | all if it's \e{already} true that the most recent run of the first |
| 26 | command was successful. |
| 27 | |
| 28 | You might use \cw{buildrun} in situations where you want to run two |
| 29 | commands in succession, but (for one reason or another) you'd rather |
| 30 | have them run in separate shell sessions and therefore you don't want |
| 31 | to take the obvious approach of simply issuing a compound command |
| 32 | using the shell's \cw{&&} operator. |
| 33 | |
| 34 | A typical scenario involves the first command being a software build |
| 35 | process (a compile command, or \cw{make}, or similar), and the second |
| 36 | being some attempt to run the resulting program or its test suite or a |
| 37 | debugger. You might want to run your build and test commands in |
| 38 | separate shell sessions for several reasons: if it's convenient to |
| 39 | give them different working directories, or in order to separate the |
| 40 | shell command-recall histories (so that the build terminal has all the |
| 41 | commands related to editing and searching source files, and the test |
| 42 | terminal has the ones related to adjusting the test environment), or |
| 43 | in order to separate their output (so that successive test runs appear |
| 44 | adjacent to each other in the test terminal and can be easily |
| 45 | compared, while the output from build commands is available for |
| 46 | checking if it's needed but doesn't keep scrolling the test output off |
| 47 | the screen). |
| 48 | |
| 49 | To use \cw{buildrun}, you must first decide on a location for a |
| 50 | \e{control directory} which the two \cw{buildrun} processes can use to |
| 51 | communicate between themselves. Then, in one window, you run the |
| 52 | command you want to run first (e.g. the compile operation), prefixed |
| 53 | with a \cw{buildrun -w} command giving the pathname of the control |
| 54 | directory. For instance, you might run |
| 55 | |
| 56 | \c buildrun -w /tmp/controldir make |
| 57 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
| 58 | |
| 59 | Then, in another window, run the second command (e.g. a test or |
| 60 | debugging command) prefixed with a similar \cw{buildrun -r} command, |
| 61 | for example |
| 62 | |
| 63 | \c buildrun -r /tmp/controldir ./test.sh |
| 64 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
| 65 | |
| 66 | The instance of \cw{buildrun} run with \cw{-w} will immediately run |
| 67 | its command; the instance run with \cw{-r} will wait for the \cw{-w} |
| 68 | command to complete, and then run its own command. If the first |
| 69 | command fails, the \cw{buildrun -r} process will continue to sleep; |
| 70 | you can then correct the problem and re-run the compile, and |
| 71 | \cw{buildrun -r} will only wake up once an instance of \cw{buildrun |
| 72 | -w}'s command completes successfully. |
| 73 | |
| 74 | If you then immediately re-run \cw{buildrun -r} without starting |
| 75 | another build, it will run its command instantly without waiting. So |
| 76 | you can repeat your testing or debugging, or run several different |
| 77 | test runs, by simply recalling the same test command \e{including} the |
| 78 | \cw{buildrun -r} prefix. |
| 79 | |
| 80 | (The option names \cw{-w} and \cw{-r} are intended to imply that the |
| 81 | first command is writing some kind of resource, such as a compiled |
| 82 | program or data file, and that the second command intends to read that |
| 83 | resource and hence needs the first command to have written it |
| 84 | correctly.) |
| 85 | |
| 86 | \U OPTIONS |
| 87 | |
| 88 | You must specify one of \cw{-w} and \cw{-r}. |
| 89 | |
| 90 | \dt \cw{-w} |
| 91 | |
| 92 | \dd Runs \cw{buildrun} in write mode. You must provide a command line; |
| 93 | \cw{buildrun -w} will run that command, and use the control directory |
| 94 | to signal to any waiting \cw{buildrun -r} instances when it has |
| 95 | completed successfully. |
| 96 | |
| 97 | \dt \cw{-r} |
| 98 | |
| 99 | \dd Runs \cw{buildrun} in read mode. If a command wrapped by |
| 100 | \cw{buildrun -w} is currently in progress, or if the last such command |
| 101 | failed, then \cw{buildrun -r} will wait until one succeeds before |
| 102 | doing anything. However, if no \cw{buildrun -w} is currently running |
| 103 | and the last one completed successfully, \cw{buildrun -r} will not |
| 104 | wait at all. |
| 105 | |
| 106 | \lcont{ |
| 107 | |
| 108 | If a command line is provided, \cw{buildrun -r} will run that command |
| 109 | after it finishes waiting. If no command line is provided, |
| 110 | \cw{buildrun -r} will simply return success when it finishes waiting. |
| 111 | |
| 112 | } |
| 113 | |
| 114 | \U ARGUMENTS |
| 115 | |
| 116 | \dt \e{control-directory} |
| 117 | |
| 118 | \dd This argument is mandatory in both \cw{-w} and \cw{-r} modes. It |
| 119 | must give the pathname of a directory which the two instances of |
| 120 | \cw{buildrun} will use to communicate with each other. |
| 121 | |
| 122 | \lcont{ |
| 123 | |
| 124 | You need not create the control directory; \cw{buildrun -w} will |
| 125 | create it the first time it runs. It will also be deleted every time |
| 126 | \cw{buildrun -w}'s command completes successfully, because that's how |
| 127 | success is communicated to \cw{buildrun -r}. (A side effect of that is |
| 128 | that if \cw{buildrun -r} is run before \e{ever} running \cw{buildrun |
| 129 | -w}, it will behave as if there had been a successful \cw{-w} run.) |
| 130 | |
| 131 | The control directory should not be on a network-mounted filesystem, |
| 132 | since network filesystems sometimes diverge from the normal Unix |
| 133 | behaviour which \cw{buildrun} relies on. Using a directory in |
| 134 | \cw{/tmp} is recommended. |
| 135 | |
| 136 | Of course, instances of \cw{buildrun} using different control |
| 137 | directories will be completely independent of each other. So you can |
| 138 | simultaneously run two or more pairs of commands each linked by their |
| 139 | own pair of \cw{buildrun}s, and as long as each pair has a separate |
| 140 | control directory, they won't interfere with each other. |
| 141 | |
| 142 | } |
| 143 | |
| 144 | \dt \e{command} (and optional arguments) |
| 145 | |
| 146 | \dd The first word on \cw{buildrun}'s command line which is not an |
| 147 | option or the control directory name will be treated as a command to |
| 148 | be run by \cw{buildrun}, and anything following that word will be |
| 149 | treated as arguments to that command. The command will be run directly |
| 150 | using the \cw{execvp}(\e{3}) function, so shell syntax (pipes, |
| 151 | redirections etc) is not supported. If you need your command to |
| 152 | contain things like that, you can achieve it by explicitly invoking a |
| 153 | shell, e.g. |
| 154 | |
| 155 | \lcont{ |
| 156 | |
| 157 | \c buildrun -w /tmp/ctldir sh -c '(cmd1; cmd2 | cmd3) > outfile' |
| 158 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
| 159 | |
| 160 | In \cw{buildrun -r} mode, an alternative to doing that is simply not |
| 161 | to provide a command at all, and instead tell your shell to run a |
| 162 | complex command \e{after} \cw{buildrun}, e.g. |
| 163 | |
| 164 | \c buildrun -r /tmp/ctldir && (cmd1; cmd2 | cmd3) > outfile |
| 165 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
| 166 | |
| 167 | (This alternative is not available with \cw{buildrun -w}, since that |
| 168 | has to run its command as a subprocess so that it can wait for it to |
| 169 | finish and see whether it worked.) |
| 170 | |
| 171 | } |
| 172 | |
| 173 | \U LICENCE |
| 174 | |
| 175 | \cw{buildrun} is free software, distributed under the MIT licence. |
| 176 | Type \cw{buildrun --licence} to see the full licence text. |
| 177 | |
| 178 | \versionid $Id$ |