@node Usage rules
@unnumbered Usage rules

@itemize

@item Target is the single file.
Target's result probably won't create file at all.

@item Build rules for the target @file{target} are placed in
@file{target.do} file.

@item By default @file{.do} file is run as @code{/bin/sh -e} script.
If @command{redo} is run with an @option{-x} argument, then
@code{/bin/sh -ex} is used instead.

@item Executable @file{.do} file is run as is, by direct execution.

@item Targets can be placed in other directories, probably with
relatives paths.

@item Following @file{.do} files are searched for @file{dir/base.a.b} target:

@example
dir/base.a.b.do
dir/default.a.b.do
dir/default.b.do
dir/default.do
default.a.b.do
default.b.do
default.do
@end example

and for @file{../a/b/xtarget.y} target:

@example
./../a/b/xtarget.y.do
./../a/b/default.y.do
./../a/b/default.do
./../a/default.y.do
./../a/default.do
./../default.y.do
./../default.do
@end example

@item @file{.do} file search goes up to @file{/} by default, but can be
    limited with either @env{$REDO_TOP_DIR} environment variable, or by
    having @file{.redo/top} file in it.

@item @file{.do} runs in the same directory where it is placed.

@item @file{.do} runs with the three arguments:
    @itemize
    @item @code{$1} -- name of the target.
    @item @code{$2} -- base name of the target. Equals to @code{$1} if
        it is not @file{default.*} file. Otherwise it lacks the extension.
@example
a.b.c.do       -> $2=a.b.c
default.do     -> $2=a.b.c
default.c.do   -> $2=a.b
default.b.c.do -> $2=a
@end example
    @item @code{$3} -- path to the temporary file, that will be renamed
        to the target itself. It is relative to the file in the target
        directory.
    @end itemize

@item @file{.do}'s @code{stdout} is captured and written to the
    @code{$3} file. You have to produce either @code{stdout} output, or
    use @code{$3} directly, but not both.

@item If there was no @code{stdout} output and no @code{$3} file is
    explicitly created, then no output file is created at all. Target
    does not produce anything, it is "empty".

@item @code{stderr} is not captured at all and can be seen by default.

@item Empty targets are considered always out-of-date.

@item Dependency information is recorded by @command{redo-ifchange}
    command invocation. It takes list of dependencies (targets), on
    whose the currently build target is dependant. Current @file{.do}
    file is implicitly added as a dependency.

@item If no @command{redo-ifchange}'s dependency target exists, then it
    is build (according to build rules in corresponding @file{.do}). If
    dependency has not been changed, then it is not rebuilt.

@item Non-existent files dependencies are created with
    @command{redo-ifcreate} command. If specified dependency target file
    appears, then current target will be rebuilt. Intermediate higher
    priority @file{.do} files dependency is implicitly recorded. For
    example, if you @file{foo} target currently uses @file{default.do}
    script, then @file{foo.do} is automatically recorded as a
    non-existent dependency, forcing @file{foo} to be rebuilt if
    @file{foo.do} appears.

@end itemize