1## **************************************************************************
2## For copyright and licensing terms, see the file named COPYING.
3## **************************************************************************
4
5=pod
6
7=head1 NAME
8
9redo-ifchange -- record and rebuild dependencies
10
11=head1 SYNOPSIS
12
13B<redo-ifchange> {S<I<filenames>>...}
14
15=head1 DESCRIPTION
16
17B<redo-ifchange> is a dependency redcording and rebuilding utility that is run by a "do" script that is in turn invoked by L<redo>.
18
19B<redo-ifchange> records that the current target (whose "do" script is being run) depends from the dependencies named I<filenames>.
20The dependency recorded is that the current target should be built if I<filenames> have changed.
21
22It also determines, using previously saved dependency information if available, which of the dependencies is itself out of date, and recursively attempts to re-build them, as if by invoking L<redo>.
23It delays processing of every dependency that is locked by a concurrent invocation of L<redo> or L<redo-ifchange>.
24
25=head2 OPTIONS
26
27B<redo-ifchange> of necessity recognizes a few of the command-line options supported by L<redo>, that apply to all redo processes in the tree.
28However, they are not part of its command-line usage and they are not intended to be used on its command line.
29
30Instead, they are passed to it via the C<REDOFLAGS> environment variable which is set up by the ultimate L<redo> parent process.
31This is also how B<redo-ifchange> is informed about where to record dependency information and where the open file descriptors for the jobserver pipe are.
32Do not, therefore, clear the environment or close arbitrary file descriptors when invoking B<redo-ifchange>.
33
34For compatibility, B<redo-ifchange> also understands the C<MAKEFLAGS>, C<MFLAGS>, C<MAKELEVEL>, and C<__MKLVL__> environment variables.
35The latter two are used to track recursion depth, by redo and by the GNU and BSD L<make> programs.
36The former two contain command-line options passed down from an ultimake L<make> process, similar to C<REDOFLAGS>.
37
38Only a few of the options passed via C<MAKEFLAGS> and C<MFLAGS> are acted upon, namely S<-s>, S<-k>, S<-d>, S<-p>, and the undocumented options used to pass along jobserver pipe file descriptor information.
39All other options used in these environment variables are ignored.
40
41=head2 CHANGES
42
43If a I<filename> denotes a (character or block) device file, a socket, a FIFO, or a directory, it is considered "changed" based solely upon its last modification timestamp.
44B<redo-ifchange> does not attempt to open or to read the contents of such files.
45
46If I<filename> denotes an ordinary file, it is considered "changed" based upon a combination of its last modification timestamp and the CubeHash hash of its contents.
47To prevent re-calculating the hash value of a file repeatedly, B<redo-ifchange> assumes that if a file's last modification timestamp has not changed, it has not been written to, and therefore the hash of its contents cannot have changed.
48
49In both cases, B<redo-ifchange> records the timestamp and hash information in the F<.redo> database.
50
51=head1 AUTHOR
52
53Jonathan de Boyne Pollard
54
55=cut
56