## **************************************************************************
## For copyright and licensing terms, see the file named COPYING.
## **************************************************************************

=pod

=head1 NAME

redo-ifchange -- record and rebuild dependencies

=head1 SYNOPSIS

B<redo-ifchange> {S<I<filenames>>...}

=head1 DESCRIPTION

B<redo-ifchange> is a dependency redcording and rebuilding utility that is run by a "do" script that is in turn invoked by L<redo>.

B<redo-ifchange> records that the current target (whose "do" script is being run) depends from the dependencies named I<filenames>.
The dependency recorded is that the current target should be built if I<filenames> have changed.

It 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>.
It delays processing of every dependency that is locked by a concurrent invocation of L<redo> or L<redo-ifchange>.

=head2 OPTIONS

B<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.
However, they are not part of its command-line usage and they are not intended to be used on its command line.

Instead, they are passed to it via the C<REDOFLAGS> environment variable which is set up by the ultimate L<redo> parent process.
This 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.
Do not, therefore, clear the environment or close arbitrary file descriptors when invoking B<redo-ifchange>.

For compatibility, B<redo-ifchange> also understands the C<MAKEFLAGS>, C<MFLAGS>, C<MAKELEVEL>, and C<__MKLVL__> environment variables.
The latter two are used to track recursion depth, by redo and by the GNU and BSD L<make> programs.
The former two contain command-line options passed down from an ultimake L<make> process, similar to C<REDOFLAGS>.

Only 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.
All other options used in these environment variables are ignored.

=head2 CHANGES

If 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.
B<redo-ifchange> does not attempt to open or to read the contents of such files.

If 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.
To 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.

In both cases, B<redo-ifchange> records the timestamp and hash information in the F<.redo> database.

=head1 AUTHOR

Jonathan de Boyne Pollard

=cut