doc/rules.texi

   1 @node Usage rules
   2 @cindex usage rules
   3 @unnumbered Usage rules
   4
   5 @itemize
   6
   7 @item Target is the single file.
   8 Target's result probably won't create file at all.
   9
  10 @item Build rules for the target @file{target} are placed in
  11 @file{target.do} file.
  12
  13 @item By default @file{.do} file is run as @code{/bin/sh -e} script.
  14 If @command{redo} is run with an @option{-x} argument, then
  15 @code{/bin/sh -ex} is used instead.
  16
  17 @item Executable @file{.do} file is run as is, by direct execution.
  18
  19 @item Targets can be placed in other directories, probably with
  20 relatives paths.
  21
  22 @item Following @file{.do} files are searched for @file{dir/base.a.b} target:
  23
  24 @example
  25 dir/base.a.b.do
  26 dir/default.a.b.do
  27 dir/default.b.do
  28 dir/default.do
  29 default.a.b.do
  30 default.b.do
  31 default.do
  32 @end example
  33
  34 and for @file{../a/b/xtarget.y} target:
  35
  36 @example
  37 ./../a/b/xtarget.y.do
  38 ./../a/b/default.y.do
  39 ./../a/b/default.do
  40 ./../a/default.y.do
  41 ./../a/default.do
  42 ./../default.y.do
  43 ./../default.do
  44 @end example
  45
  46 @item @file{.do} file search goes up to @file{/} by default, but can be
  47     limited with either @env{$REDO_TOP_DIR} environment variable, or by
  48     having @file{.redo/top} file in it.
  49
  50 @item @file{.do} runs in the same directory where it is placed.
  51
  52 @item @file{.do} runs with the three arguments:
  53     @itemize
  54     @item @code{$1} -- name of the target.
  55     @item @code{$2} -- base name of the target. Equals to @code{$1} if
  56         it is not @file{default.*} file. Otherwise it lacks the extension.
  57 @example
  58 a.b.c.do       -> $2=a.b.c
  59 default.do     -> $2=a.b.c
  60 default.c.do   -> $2=a.b
  61 default.b.c.do -> $2=a
  62 @end example
  63     @item @code{$3} -- path to the temporary file, that will be renamed
  64         to the target itself. It is relative to the file in the target
  65         directory.
  66     @end itemize
  67
  68 @item @file{.do}'s @code{stdout} is captured and written to the
  69     @code{$3} file. You have to produce either @code{stdout} output, or
  70     use @code{$3} directly, but not both.
  71
  72 @item If neither @code{stdout} output nor @code{$3} file were
  73     explicitly created, then no output file is created at all.
  74     Target does not produce anything, it is "non-existent".
  75
  76 @item @code{stderr} is not captured at all and can be seen by default.
  77
  78 @item Non-existent targets are considered always out-of-date.
  79
  80 @item Dependency information is recorded by @command{redo-ifchange}
  81     command invocation. It takes list of dependencies (targets), on
  82     whose the currently build target is dependant. Current @file{.do}
  83     file is implicitly added as a dependency.
  84
  85 @item If no @command{redo-ifchange}'s dependency target exists, then it
  86     is build (according to build rules in corresponding @file{.do}). If
  87     dependency has not been changed, then it is not rebuilt.
  88
  89 @item Non-existent files dependencies are created with
  90     @command{redo-ifcreate} command. If specified dependency target file
  91     appears, then current target will be rebuilt. Intermediate higher
  92     priority @file{.do} files dependency is implicitly recorded. For
  93     example, if you @file{foo} target currently uses @file{default.do}
  94     script, then @file{foo.do} is automatically recorded as a
  95     non-existent dependency, forcing @file{foo} to be rebuilt if
  96     @file{foo.do} appears.
  97
  98 @end itemize