From d9d70c4c44479fd480f5d0fb1860ad330d53149f Mon Sep 17 00:00:00 2001 From: Avery Pennarun Date: Mon, 26 Nov 2018 17:32:19 -0500 Subject: [PATCH] Even more doc cleanups. --- Documentation/Contributing.md | 9 +++-- Documentation/FAQBasics.md | 35 ++++++++++++++++--- .../{defaults.md => defaults/index.md} | 0 .../cookbook/{hello.md => hello/index.md} | 0 Documentation/index.md | 22 +++++++++--- mkdocs.yml | 8 +++-- 6 files changed, 59 insertions(+), 15 deletions(-) rename Documentation/cookbook/{defaults.md => defaults/index.md} (100%) rename Documentation/cookbook/{hello.md => hello/index.md} (100%) diff --git a/Documentation/Contributing.md b/Documentation/Contributing.md index 54bf315..38615fd 100644 --- a/Documentation/Contributing.md +++ b/Documentation/Contributing.md @@ -9,7 +9,7 @@ versions of redo were distributed under the GNU LGPL, but this [changed in 2018](https://groups.google.com/forum/#!topic/redo-list/wLMZMxtn4wo).) minimal/do is in the public domain so that it's as easy as possible -to include inside your own projects for people who don't +to include inside your own projects, to help end users who don't have a copy of redo. @@ -42,6 +42,11 @@ The best things you can do for redo are: - Convince your favourite OS distro to build and include (up to date!) redo packages. +- Help proofreading this documentation, and send patches or pull requests + with improvements. + +- Join the mailing list (below) to discuss design changes or bugs. + - Tell your friends! @@ -60,5 +65,3 @@ It's okay to send a message directly to the mailing list without subscribing first. If you reply to someone who writes to the list, please leave them in the cc: list, since if they haven't subscribed, they won't get your reply otherwise. - - diff --git a/Documentation/FAQBasics.md b/Documentation/FAQBasics.md index 68e391d..8fd4b7e 100644 --- a/Documentation/FAQBasics.md +++ b/Documentation/FAQBasics.md @@ -1,4 +1,30 @@ -# Does redo make cross-platform builds easy? +# Help! redo rebuilds every time, even if dependencies are clean! + +Many people are confused by this at first. The `redo` command *always* +rebuilds the target you requested. If you want to only conditionally +rebuild the target, use `redo-ifchange`. + +The same rule applies inside .do scripts. If a .do script calls `redo dep`, +then it will always redo the target called dep. If it called `redo-ifchange +dep`, it will only redo dep if its dependencies have changed. + +Typically, you want your toplevel `all.do` script to use `redo-ifchange`. +But a `clean.do` script probably should use `redo`, because you want it to +always clean up your extra files. A `test.do` probably also uses `redo` for +its testing sub-tasks, because you might want to run your tests repeatedly. + +For rationale, see [Why does 'redo target' redo even unchanged +targets?](../FAQSemantics/#why-does-redo-target-redo-even-unchanged-targets) + + +# I'm using redo-ifchange. How does redo decide my target is clean/dirty? + +You can see (recursively) which dependencies checked by redo, and whether +they are clean or dirty, by using `redo -d` (which is short for +"dependencies" or "debug", whichever you prefer). + + +# Does redo make cross-platform or multi-platform builds easy? A lot of build systems that try to replace make do it by trying to provide a lot of predefined rules. For example, one build system I know includes @@ -46,13 +72,14 @@ To activate it, you can add a line like this to your .bashrc: # Do end users have to have redo installed in order to build my project? No. We include a very short and simple shell script -called `do` in the `minimal/` subdirectory of the redo project. `do` is like +called `do` in the `minimal/` subdirectory of the redo project. +`minimal/do` is like `redo` (and it works with the same `*.do` scripts), except it doesn't understand dependencies; it just always rebuilds everything from the top. -You can include `do` with your program to make it so non-users of redo can +You can include `do` with your program so that non-users of redo can still build your program. Someone who wants to hack on your program will -probably go crazy unless they have a copy of `redo` though. +probably go crazy unless they install a copy of `redo` though. Actually, `redo` itself isn't so big, so for large projects where it matters, you could just include it with your project. diff --git a/Documentation/cookbook/defaults.md b/Documentation/cookbook/defaults/index.md similarity index 100% rename from Documentation/cookbook/defaults.md rename to Documentation/cookbook/defaults/index.md diff --git a/Documentation/cookbook/hello.md b/Documentation/cookbook/hello/index.md similarity index 100% rename from Documentation/cookbook/hello.md rename to Documentation/cookbook/hello/index.md diff --git a/Documentation/index.md b/Documentation/index.md index 97c371a..0efc45d 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -169,8 +169,8 @@ easily be linked from this document. Here are a few open source examples: Buildroot](https://github.com/apenwarr/buildroot/tree/redo) that uses redo in order to clean up its dependency logic. -* You can also find some limited examples in the - [`t/111-example/`](t/111-example) subdir of the redo project itself. +* You can also find some curated examples in the + [Documentation/cookbook/](https://github.com/apenwarr/redo/tree/master/Documentation/cookbook/) subdir of the redo project itself. * A [github search for all.do](https://github.com/search?p=9&q=path%3A%2F+extension%3Ado+filename%3A%2Fall.do&type=Code) shows an ever-growing number of projects using redo. @@ -234,7 +234,8 @@ of these links): - catenate's [credo](https://github.com/catenate/credo), a (very rearchitected) variant written for the Inferno Shell. -The redo design is so simple and elegant that many individuals have been +The original redo design is so simple and elegant that many individuals +have been inspired to (and able to) write their own version of it. In the honoured tradition of Unix's `make`, they (almost) all just use the same name, `redo`. Unfortunately, many of these @@ -242,5 +243,16 @@ implementations are unmaintained, slightly incompatible with the "standard" redo semantics, and/or have few or no automated tests. At the time of this writing, none of them except apenwarr/redo (ie. this -project) support parallel builds (`redo -j`). For large projects, -parallel builds are usually considered essential. +project) support parallel builds (`redo -j`) or log linearization +(`redo-log`). For large projects, parallel builds are usually considered +essential. + +The [automated tests](https://github.com/apenwarr/redo/tree/master/t) in +this version of redo are almost, but not quite, appropriate for testing any +redo implementation. If you really must write a new version of redo, we +invite you to thoroughly test it against the existing test suite to ensure +compatibility. You can also steal our tests (with attribution, of course) +and include them in your own source package. We'd also love it it you +contribute more automated tests when you find a bug, or send us patches if +you find a test which is accidentally incompatible (as opposed to finding a +real bug) with other redo implementations. diff --git a/mkdocs.yml b/mkdocs.yml index 8e54a49..46f76c1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,22 +3,24 @@ theme: readthedocs docs_dir: Documentation site_dir: website strict: true +repo_url: https://github.com/apenwarr/redo +edit_uri: edit/master/Documentation extra_javascript: - fetchcode.js pages: - Introduction: index.md - Getting Started: GettingStarted.md + - Contributing.md - Cookbook: - - Hello World: cookbook/hello.md - - Using default.do (text processing): cookbook/defaults.md + - Hello World (hello.do, redo-ifchange): cookbook/hello/index.md + - Text processing example (default.do, redo-whichdo, redo-always, redo-stamp): cookbook/defaults/index.md - FAQ: - Basics: FAQBasics.md - Semantics: FAQSemantics.md - Interop with make: FAQInterop.md - Parallel Builds: FAQParallel.md - Implementation Details: FAQImpl.md - - Contributing.md - Reference Manual: - redo(1): redo.md - redo-ifchange(1): redo-ifchange.md