mdw@git.distorted.org.uk Git - sgt/utils/blob - buildrun/buildrun.but

   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$