From 04cf7c6351f0802899d2cb5d8552b2a4b1c08acf Mon Sep 17 00:00:00 2001 From: Tharre Date: Sat, 4 Apr 2015 01:52:14 +0200 Subject: Add basic man pages for documentation --- docs/redo-always.1.ronn | 31 +++++++++++++++++ docs/redo-ifchange.1.ronn | 34 +++++++++++++++++++ docs/redo-ifcreate.1.ronn | 35 ++++++++++++++++++++ docs/redo.1.ronn | 84 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 184 insertions(+) create mode 100644 docs/redo-always.1.ronn create mode 100644 docs/redo-ifchange.1.ronn create mode 100644 docs/redo-ifcreate.1.ronn create mode 100644 docs/redo.1.ronn (limited to 'docs') diff --git a/docs/redo-always.1.ronn b/docs/redo-always.1.ronn new file mode 100644 index 0000000..164877f --- /dev/null +++ b/docs/redo-always.1.ronn @@ -0,0 +1,31 @@ +redo-always(1) -- rebuild always +================================ + +## SYNOPSIS + +`redo-always` + +## DESCRIPTION + +`redo-always` creates a 'always' dependency on `REDO_PARENT_TARGET` - it will be +rebuilt every time. However, should multiple files depend on the same target +it will only be rebuild once. + +This command should usually be called from within a .do script. See redo(1). + +## EXAMPLES + +(none yet) + +## ENVIRONMENT + +Requires `REDO_PARENT_TARGET` and `REDO_ROOT` to be defined. See redo(1) for a +description of these variables. + +## SEE ALSO + +redo-ifchange(1), redo-ifcreate(1) + +## REDO + +Part of the redo(1) suite. diff --git a/docs/redo-ifchange.1.ronn b/docs/redo-ifchange.1.ronn new file mode 100644 index 0000000..6b9bcb6 --- /dev/null +++ b/docs/redo-ifchange.1.ronn @@ -0,0 +1,34 @@ +redo-ifchange(1) -- rebuild if target changes +============================================= + +## SYNOPSIS + +`redo-ifchange` [...] + +## DESCRIPTION + +`redo-ifchange` creates a 'on change' dependency on the given . Should +any of those change in the future, then `REDO_PARENT_TARGET` (usually the target +that is being built by the .do script) is flagged out-of-date. + +All that are out-of-date will be rebuild **in random order** by the +equivalent of _redo target_. + +This command should usually be called from within a .do script. See redo(1). + +## EXAMPLES + +(none yet) + +## ENVIRONMENT + +Requires `REDO_PARENT_TARGET` and `REDO_ROOT` to be defined. See redo(1) for a +description of these variables. + +## SEE ALSO + +redo-ifcreate(1), redo-always(1) + +## REDO + +Part of the redo(1) suite. diff --git a/docs/redo-ifcreate.1.ronn b/docs/redo-ifcreate.1.ronn new file mode 100644 index 0000000..365feae --- /dev/null +++ b/docs/redo-ifcreate.1.ronn @@ -0,0 +1,35 @@ +redo-ifcreate(1) -- rebuild if target is created +================================================ + +## SYNOPSIS + +`redo-ifcreate` [...] + +## DESCRIPTION + +`redo-ifcreate` creates a 'on create' dependency on the given (nonexistent) +. Should any of those be created in the future, then +`REDO_PARENT_TARGET` (usually the target that is being built by the .do script) +is flagged out-of-date. + +If any of the already exist `redo-ifcreate` will return a nonzero exit +code. + +This command should usually be called from within a .do script. See redo(1). + +## EXAMPLES + +(none yet) + +## ENVIRONMENT + +Requires `REDO_PARENT_TARGET` and `REDO_ROOT` to be defined. See redo(1) for a +description of these variables. + +## SEE ALSO + +redo-ifchange(1), redo-always(1) + +## REDO + +Part of the redo(1) suite. diff --git a/docs/redo.1.ronn b/docs/redo.1.ronn new file mode 100644 index 0000000..1138507 --- /dev/null +++ b/docs/redo.1.ronn @@ -0,0 +1,84 @@ +redo(1) -- an elegant and minimal build tool +============================================ + +## SYNOPSIS + +`redo` [...] [...] + +## DESCRIPTION + +`redo` is a powerful yet minimalistic tool for rebuilding files and their +dependencies from source, based on rules specified in .do scripts. These +scripts have the unique property of being language independent - they only +require a valid shebang-like line. + +`redo` is inherently recursive, it works by executing .do scripts which call +redo-ifchange(1) or other redo subcommands which in turn again execute .do +scripts. This enables `redo` to be clean, modular and extremely fast. + +`redo` is also atomic, at no point in the build process exists a state in which +a truncated file is left in place. Any changes to .do files immediately result +in depending targets getting flagged out-of-date. This means the user doesn't +have to care about the state his build is in anymore, it's all handled by `redo` + +## FILES + +The `redo` command expects to find a suitable .do script for the specified +. If none is given, 'all' is assumed instead. + +Suitable .do script pathnames are determined using the following pattern in +descending order: + + * target filename + '.do' + * default.ext.do + * repeat for ../, except if we are already in REDO_ROOT + +Where '.ext' is everything following the last dot (.) that could be found in the +target filename. `redo` will return an nonzero exit code should no suitable .do +script exist. + +## ARGUMENTS + +If a suitable .do script was found then it will be executed with the following +arguments: + + * $1 - The filename of the target file. + * $2 - The target filename minus extension + * $3 - A temporary file that will be renamed to the target filename if the .do + script returns an nonzero exit code. + +For `redo` to function correctly the target that is being built by the .do +script must be saved as $3. + +## SHEBANG + +(not documented yet) + +## OPTIONS + + * `-j`[], `--jobs`[=]: + Execute no more than .do scripts at any point in parallel. If + this option was given without an argument, then `redo` will not limit the + number of jobs. By default this equals the number of threads of the target + machine or 1 if this couldn't be determined. + +## EXAMPLES + +(none yet) + +## ENVIRONMENT + + * `REDO_PARENT_TARGET`: + The target that shall be build by the .do script. + + * `REDO_ROOT`: + The canonicalized absolute pathname corresponding to the 'root' directory + of `redo`, which contains the _.redo/_ directory. + +## SEE ALSO + +redo-ifchange(1), redo-ifcreate(1), redo-always(1) + +## REDO + +Part of the redo(1) suite. -- cgit v1.2.3-70-g09d2