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