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 \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$