doc/redo.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <meta name="author" content="Gyepi Sam" />
  <meta name="date" content="2018-10-03" />
  <title>redo(1) Redux User Manual</title>
  <style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<div id="header">
<h1 class="title">redo(1) Redux User Manual</h1>
<h2 class="author">Gyepi Sam</h2>
<h3 class="date">October 03, 2018</h3>
</div>
<!-- DO NOT EDIT -- Autogenerated file. See default.md.do instead. -->
<h1 id="name">NAME</h1>
<p>redo - Builds files atomically.</p>
<h1 id="synopsis">SYNOPSIS</h1>
<p>redux redo [OPTION]... [TARGET]...</p>
<h1 id="options">OPTIONS</h1>
<p>-? Show help</p>
<p>-d Alias for debug</p>
<p>-debug</p>
<pre><code>    Print debugging output.</code></pre>
<p>-h Show help</p>
<p>-help</p>
<pre><code>    Show help</code></pre>
<p>-sh string</p>
<pre><code>    Extra arguments for /bin/sh.</code></pre>
<p>-task</p>
<pre><code>    Run .do script for side effects and ignore output.</code></pre>
<p>-v Alias for verbose</p>
<p>-verbose</p>
<pre><code>    Be verbose. Repeat for intensity.</code></pre>
<h1 id="notes">NOTES</h1>
<p>The redo command builds files atomically by running a do script asssociated with the target.</p>
<p>redo normally requires one or more target arguments. If no target arguments are provided, redo runs the default target <span class="citation">@all</span> in the current directory if its do script <span class="citation">@all.do</span> exists.</p>
<h1 id="description">DESCRIPTION</h1>
<p>This command can be invoked as <code>redux redo</code> or, through a link, as <code>redo</code>.</p>
<p>A redo target is produced by an sh script whose name has a '.do' file extension and, as such, is called a do script.</p>
<p>For a given target named <code>target</code>, the corresponding do file may be named, in order of decreasing specificity, <code>target.do</code> or <code>default.do</code>.</p>
<p>For a given target named <code>target.ext</code>, the corresponding do file may be named, in order of decreasing specificity, <code>target.ext.do</code>, <code>default.ext.do</code> or, finally, <code>default.do</code>.</p>
<p>For targets with multiple extensions, the corresponding do files may be named, in order of decreasing specificity, <code>target.ext.do</code> where <code>ext</code> is the full extension, followed by default do files with shorter and shorter suffixes of the extension, finally ending in <code>default.do</code>. For example, the target <code>file.x.y.z</code> results in a search for the following do scripts:</p>
<p>file.x.y.z.do default.x.y.z.do default.y.z.do default.z.do default.do</p>
<p>Jumping ahead slightly, note that in the case of multiple extensions, the $2 argument to the do script contains all but one extension. In the example above, $2 would be <code>file.x.y</code> for all do files. Doing otherwise causes the $2 argument to depend on the do file used.</p>
<p>Redo searches for each of these script files, in order of specificity, starting in the target's directory and moving into parent directories. The search stops when a script is found or when the project root directory has been unsuccessfully searched.</p>
<p>In the latter case, if the target file exists on disk, it is taken to be a source file, not generated by script and its metadata is stored in the database. The file will be subsequently watched for changes.</p>
<p>In the former case, where the script is found, it is assumed to be an sh script and executed with three arguments:</p>
<p>$1 = path to target, relative to do script directory $2 = same as $1, with a single file extension, if any, removed $3 = temporary file name</p>
<p>The script is executed by /bin/sh with the current working directory (cwd) set to its directory and with stdout opened to a temporary file (which is unnamed and different from $3). It is normally expected to produce output on stdout or write to the file specified by its $3 parameter. It is an error for a script to write to both outputs.</p>
<p>If the script completes successfully, redo chooses the correct output, renames the temporary file to the target file and updates its database with the new file's metadata record. Since only one of the two temporary files can have content, redo has no trouble selecting the correct one. Conversely, if neither file has content, then either is a valid candidate.</p>
<p>In the do file, which is an sh script, the line</p>
<pre><code>redo-ifchange A B C</code></pre>
<p>specifies the files A, B, and C as prerequisites for the target file.</p>
<p>Similarly, a call to</p>
<pre><code>redo-ifcreate A</code></pre>
<p>specifies that the target should be rebuilt when the non-existent file A appears or is deleted.</p>
<p>As a special case, a do file whose name is prefixed with '@' is run for side effect. redux does not create a temporary file when running such a file and uses '/dev/stdout' as the output file name so its output is visible but is otherwise not saved. While the $3 parameter is provided for consistency, it is an error for a task script to write to it since its output is discarded.</p>
<p>A call to redo without an argument will search for a file named <code>@all.do</code> in the current directory.</p>
<p>A '@' prefixed task is analogous to a <code>.PHONY</code> target in make. Any do file can also be run as a task by invoking 'redo' with the '-task' flag.</p>
<h1 id="environment-variables">ENVIRONMENT VARIABLES</h1>
<p>The -verbose variable can be set with the environment variable <code>REDO_VERBOSE</code>. The value of the variable is not relevant, but its length corresponds to the intensity of verbosity. For example, <code>REDO_VERBOSE=xx</code> is comparable to invoking redo with the arguments '-verbose -verbose'.</p>
<p>The -sh variable can be set with the environment variable <code>REDO_SHELL_ARGS</code>. This can be used to pass the '-v' or '-x' options, among others, to the shell (/bin/sh). redo prepends a '-' to the variable if necessary, so '-xv' could also be specified as 'xv'</p>
<p>The -debug option can be set with the environment variable <code>REDO_DEBUG</code>. The value is not relevant, merely its presence. <code>REDO_DEBUG=true</code> works fine.</p>
<p>The <code>REDO_TMP_DIR</code> environment variable, which does not have a corresponding flag, can be set to control where redo creates temporary output files. The specified directory must exist and be writable to the redo process. This may be useful if /tmp is mounted on a fast device such as a ram disk or solid state drive (SSD).</p>
</body>
</html>