1## **************************************************************************
2## For copyright and licensing terms, see the file named COPYING.
3## **************************************************************************
4
5=pod
6
7=head1 NAME
8
9redo -- rebuild utility
10
11=head1 SYNOPSIS
12
13B<redo> [S<--silent>] [S<--debug>] [S<--keep-going>] [S<--verbose>] [S<--jobs I<number>>] [S<--directory I<dirname>>] {S<I<filenames>>...}
14
15=head1 DESCRIPTION
16
17B<redo> unconditionally attempts to rebuild the list of targets given as I<filenames>.
18It does this by executing a "do" program, that is expected both to build each target, and at the same time record what dependencies should cause the target to be rebuilt if given as a target to L<redo-ifchange>.
19
20"do" programs can invoke L<redo-ifchange>, which may recursively cause dependencies to have their "do" programs invoked.
21
22=head2 PARALLEL PROCESSING
23
24B<redo> uses the same jobserver mechanism as used by the GNU and BSD L<make> programs, whereby multiple parts of a build can run in parallel.
25If the S<--jobs> command-line option is used, and if there is not already a jobserver set up by a parent process, it sets up a jobserver pipe with I<number> job slots.
26
27It then attempts to execute as many "do" programs in parallel as it can procure job slots for.
28The distribution of jobs, down the build tree, is thus determined by whether "do" programs recursively invoke L<redo-ifchange> with one dependency or many.
29
30If there is a jobserver already set up, B<redo> assumes that a job slot has already been procured for it, given that it is running.
31Similarly, if there is no jobserver and it is not told to set up a jobserver, it acts as if there is a single, implicit, slot; behaving largely as if there were a 1-slot jobserver.
32
33It re-uses this implicit slot for the first "do" program that it spawns, only procuring slots for additional parallel child processes.
34Thus if no additional slots are actually available, it devolves from the parallel down to the serial case.
35Importantly, it does not release its own implicit job slot back to the jobserver, and never devolves beyond the serial case to not being able to run jobs at all.
36
37=head2 OPTIONS
38
39The S<--directory> command-line option causes B<redo> to change directory to I<dirname> before doing anything.
40The S<--keep-going> command-line option causes it to attempt to build all targets, even if building one of them fails.
41
42The S<--verbose> command-line option causes it to print more information about its processing.
43The S<--debug> command-line option causes it to print debugging information about its internal operation.
44And the S<--silent> command-line option causes it to print less information about its processing.
45
46=head2 FINDING "do" PROGRAMS
47
48B<redo> has a two factor search for "do" programs.
49
50Firstly, it searches for "do" programs in a succession of directories, starting with the directory of the target and (if it does not have an absolute pathname) then checking each successively shorter path prefix until it ends with the current working directory.
51So if the target is F<a/b/c/d/e>, it will check F<a/b/c/d/>, then F<a/b/c/>, then F<a/b/>, then F<a/>, and then finally F<.> the current directory.
52For a target F</a/b/c/d/e>, on the other hand, it will only check F</a/b/c/d/>.
53
54Secondly, within each directory it searches for the "do" program by looking for successively shorter extension suffixes taken from the target.
55To these it prepends the word F<default> and the suffix F<.do>.
56It also, before doing that, checks for the full target filename with F<.do> appended.
57
58So if the target is F<dir/base.a.b>, it will look for F<dir/base.a.b.do>, F<dir/default.a.b.do>, F<dir/default.b.do>, F<dir/default.do>, F<base.a.b.do>, F<default.a.b.do>, F<default.b.do>, and F<default.do>.
59
60=head2 RUNNING "do" PROGRAMS
61
62A "do" program can be any kind of executable, although conventionally it is a script.
63(B<redo> does not force a choice of shell, and the script must therefore begin with a C<#!> line that names the shell that the script is written for.)
64
65B<redo> invokes the program with a C<REDOFLAGS> environment variable, which it uses to pass option and target information to recursively executed instances of B<redo> (possibly invoked indirectly via L<redo-ifchange>).
66"do" programs should not alter, or inspect, the value of this variable.
67
68B<redo> also invokes it with open file descriptors, indicating the jobserver pipe and where to record dependencies for the current target.
69"do" programs should not close these file descriptors, and should not perform I/O on them other than with L<redo-ifchange> and L<redo-ifcreate>.
70
71It sets the C<MAKELEVEL> environment variable, which is used in messages to indicate the recursion depth.
72
73It invokes the program with three arguments:
74
75=over
76
77=item
78
79the directory prefix and base name of the target (e.g. F<dir/base.a>)
80
81=item
82
83the extension part of the target that matched the F<default> file (e.g. F<.b>)
84
85=item
86
87the name of a temporary file where the target is to be built
88
89=back
90
91B<redo> performs atomic builds of individual targets.
92A target is built to a temporary filename (in the same directory), and if and only if the "do" program exits with a success status is that temporary filename atomically renamed to the actual target.
93
94=head1 AUTHOR
95
96Jonathan de Boyne Pollard
97
98=cut
99