doc/cmds.texi | 31 +++++++++++++++++++++++++++++++ doc/faq.texi | 3 +++ doc/features.texi | 1 + doc/index.texi | 25 ++++++++++++++++++++++--- doc/install.texi | 8 ++++++++ doc/jobserver.texi | 4 ++++ doc/logs.texi | 10 ++++++++-- doc/news.texi | 1 + doc/notes.texi | 2 ++ doc/ood.texi | 5 +++++ doc/rules.texi | 1 + doc/state.texi | 2 ++ doc/thanks.texi | 1 + diff --git a/doc/cmds.texi b/doc/cmds.texi index 1c0b27369b00421769892dece37dc6c1529edcf0b1336839ed0421fbaaeef4c8..709d88c6f3d0c8b92d267f346fc1c4c792ae142a1b942a814660ee030fd1c827 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -5,14 +5,19 @@ There are three basic main commands, originally suggested by DJB in his articles: @table @command +@pindex redo @item redo Forcefully and sequentially build specified targets. This is the main command you will explicitly use from the command line. If no targets are given, then @file{all} target will be used by default. + +@pindex redo-ifchange @item redo-ifchange Rebuild specified targets if they are out-of-date and record them as a dependency for the currently run target. This is the main command you will use in @file{.do} files. + +@pindex redo-ifcreate @item redo-ifcreate Record the non-existent file dependency for the currently run target. Target will be rebuilt if any of the given files appear. Can @@ -23,29 +28,41 @@ Pay attention that @command{redo-ifchange} enables parallel builds of the given targets, but ordinary @command{redo} is not: it builds specified targets sequentially and stops when error happens. +@cindex tracing @option{-x} option can be used to enable tracing (@code{set -x}) of the currently run shell script @file{.do} file. @option{-xx} option enables tracing for all invoked @file{.do} files further. +@cindex parallel build With @option{-j} option you can enable parallel builds, probably with an infinite number of workers (@code{=0}). Also you can set @env{$REDO_JOBS} to automatically apply that setting globally. Read about @ref{Logs, log storage capabilities}. +@cindex debug +@vindex REDO_LOG_PID +@vindex REDO_DEBUG @option{-log-pid} (@env{$REDO_LOG_PID=1}) can be used to prefix job's @code{stderr} with the PID, that could be useful during parallel builds. @option{-d} (@env{$REDO_DEBUG=1}) enables debug messages. +@cindex progress +@vindex REDO_NO_PROGRESS +@vindex REDO_NO_STATUS +@vindex NO_COLOR @option{-no-progress} (@env{$REDO_NO_PROGRESS=1}) and @option{-no-status} (@env{$REDO_NO_STATUS=1}) disable statusline and progress display. @env{$NO_COLOR=1} disables progress/debug messages colouring. +@cindex fsync +@vindex REDO_NO_SYNC By default all build commands use @code{fsync} to assure data is reached the disk. You can disable its usage with @env{$REDO_NO_SYNC=1} environment variable, for speeding up the build process. +@vindex REDO_STOP_IF_MODIFIED If redo sees some target modified externally, then by default it warns user about that, does not build that target, but continues the build process further. That is convenient in most cases: you can build your @@ -56,20 +73,30 @@ There are other commands that could be found in other implementations too: @table @command +@pindex redo-always @item redo-always Record current target as an always-do dependency. By definition it should be always build. @command{goredo} tries to build it once per @strong{run}. + +@pindex redo-stamp @item redo-stamp Record "stamp" dependency. It reads @code{stdin} and stores its hash in the dependency database. It is not used anyhow, it is dummy. Read about @ref{Stamping, stamping} in the FAQ. It is left only for compatibility with some other implementations. + +@pindex redo-targets +@pindex redo-ood @item redo-targets, redo-ood Show all known targets, possibly limited by specified directories. @command{redo-ood} shows only the out-of-date ones. + +@pindex redo-sources @item redo-sources Recursively show all source files the given targets depend on. + +@pindex redo-affects @item redo-affects It is not in other distributions, but it is some kind of opposite of @command{redo-sources} -- shows the targets that will be affected by @@ -79,10 +106,12 @@ And there are some maintenance and debug commands: @table @command +@pindex redo-cleanup @item redo-cleanup Removes either temporary (@option{tmp}), log files (@option{log}), or everything related to @command{goredo} (@option{full}). +@pindex redo-whichdo @item redo-whichdo Display @file{.do} search paths for specified target (similar to @command{apenwarr/redo}): @@ -103,6 +132,7 @@ ../default.o.do ../default.do @end example +@pindex redo-dot @item redo-dot Dependency @url{https://en.wikipedia.org/wiki/DOT_(graph_description_language), DOT} @@ -113,6 +143,7 @@ $ redo-dot target [...] > whatever.dot $ dot -Tpng whatever.dot > whatever.png # possibly add -Gsplines=ortho @end example +@pindex redo-depfix @item redo-depfix When you copy your worktree to different place, then copied files ctime will change. And because recorded dependency information diff --git a/doc/faq.texi b/doc/faq.texi index f01e48ceb44b592172c6a2d0bd4d735ec78cc8b008469350ebb0bed02416fb51..46f1f335ade8504d0a7e2130850f7d75203dbd669c347eee9d016c5fe296949a 100644 --- a/doc/faq.texi +++ b/doc/faq.texi @@ -1,7 +1,10 @@ @node FAQ +@cindex FAQ @unnumbered FAQ @anchor{Stamping} +@cindex hashing +@cindex stamping @section Hashing and stamping All targets are checksummed if target's size, @code{ctime}/@code{mtime} diff --git a/doc/features.texi b/doc/features.texi index 1c96936ed15eb6a62688de2540ab365d7c7bcad20cae587324088c30566f477c..1cbfa15fa0b2de3325561d8982107ffcc5248626a5f3fb2cdcdaae87d80c529a 100644 --- a/doc/features.texi +++ b/doc/features.texi @@ -1,4 +1,5 @@ @node Features +@cindex features @unnumbered Features Notable features that differentiate @command{goredo} from many other diff --git a/doc/index.texi b/doc/index.texi index d3feeb286216aa38c89a364030881c7a97aa70b4b3432113bac2cf2e24f5ae6b..43018c492adeeb66bf6367f2ce7598ac8ae2576ec5d7e9cfee195d4a8bbd4eff 100644 --- a/doc/index.texi +++ b/doc/index.texi @@ -9,7 +9,8 @@ @node Top @top goredo -Go implementation of @url{http://cr.yp.to/redo.html, djb's redo}, +@url{https://go.dev/, Go} implementation of +@url{http://cr.yp.to/redo.html, djb's redo}, Makefile replacement that @url{https://suckless.org/philosophy/, sucks less}. Originally it was just a rewrite of @@ -36,9 +37,12 @@ @command{goredo} is @url{https://www.gnu.org/philosophy/pragmatic.html, copylefted} @url{https://www.gnu.org/philosophy/free-sw.html, free software} licenced under @url{https://www.gnu.org/licenses/gpl-3.0.html, GNU GPLv3}. -It should work on all @url{https://en.wikipedia.org/wiki/POSIX, -POSIX}-compatible systems. +It should work on all +@url{https://en.wikipedia.org/wiki/POSIX, POSIX}-compatible systems. +@cindex contacts +@cindex bugs +@cindex patches Please send questions, bug reports and patches to @url{http://lists.cypherpunks.ru/goredo_002ddevel.html, goredo-devel} maillist. Announcements also go to this mailing list. @@ -57,5 +61,20 @@ @include faq.texi @include state.texi @include jobserver.texi @include thanks.texi + +@node Indices +@unnumbered Indices + +@node Concepts Index +@section Concepts Index +@printindex cp + +@node Programs Index +@section Programs Index +@printindex pg + +@node Variables Index +@section Variables Index +@printindex vr @bye diff --git a/doc/install.texi b/doc/install.texi index fd49cde3a01f424ffb68725432d915967520c0a2921d3c4f27f7f3899d5b9316..bc0d72aa781ff05ccb0072f8174faa46e0ca795bcd171baf533ad0673eec0053 100644 --- a/doc/install.texi +++ b/doc/install.texi @@ -1,4 +1,10 @@ @node Install +@cindex install +@cindex packages +@cindex ports +@cindex tarball +@cindex download +@cindex PGP @unnumbered Install Possibly @command{goredo} package already exists for your distribution: @@ -61,12 +67,14 @@ $ go get go.cypherpunks.ru/goredo $ goredo -symlinks @end example +@vindex GOPRIVATE If you have problems with @code{*.golang.org}'s inability to verify authenticity of @code{go.cypherpunks.ru} TLS connection, then you can disable their usage by setting @env{$GOPRIVATE=go.cypherpunks.ru}. You can override CA certificate file path with @env{$SSL_CERT_FILE} and @env{$GIT_SSL_CAINFO} environment variables. +@cindex git You can obtain development source code with @command{git clone git://git.cypherpunks.ru/goredo.git} (also you can use @url{https://git.cypherpunks.ru/goredo.git}). diff --git a/doc/jobserver.texi b/doc/jobserver.texi index b6e3979d7964daba734f513aa559091b90c1545db114ae49965c7869829574f7..311583e6e2b5d51eab489fc7b49b4f4d310e1bf32f33b64ad498b8cc8f23e07e 100644 --- a/doc/jobserver.texi +++ b/doc/jobserver.texi @@ -1,4 +1,5 @@ @node Jobserver +@cindex jobserver @unnumbered Jobserver Parallel builds are made by utilizing the jobserver protocol. Each job @@ -8,6 +9,8 @@ to each @command{goredo} instance. Job takes the token by reading the single byte from that pipe, writing it back for returning. Pipe is pre-filled with required number of tokens. +@pindex bmake +@pindex gmake @command{goredo} can be integrated with @url{http://www.crufty.net/help/sjg/bmake.htm, bmake} and @url{https://www.gnu.org/software/make/, GNU Make} (@command{gmake}) @@ -15,6 +18,7 @@ jobserver protocol. All three of them use the same principle of jobserver, but different ways of passing pipe's file descriptors numbers to child process. +@vindex REDO_MAKE @env{$REDO_MAKE} environment variable controls the compatibility behaviour: @table @command diff --git a/doc/logs.texi b/doc/logs.texi index fe7e2f0455ca1f2e8276975ee1d30680821dab617922c85a72027626a0adc465..07c49682a74abfe70433ba946f1281c88e9b6ac978472fb3aaf86c1cf251cca1 100644 --- a/doc/logs.texi +++ b/doc/logs.texi @@ -1,6 +1,9 @@ @node Logs +@cindex logging @unnumbered Logs +@vindex REDO_LOGS +@vindex REDO_SILENT @code{stderr} of the running targets can be kept on the disk by specifying @option{-k} option (or by setting @env{$REDO_LOGS=1} environment variable) to @command{redo}. You can simultaneously @@ -13,6 +16,9 @@ @example $ redo -xx -k -s build-the-whole-huge-project @end example +@cindex TAI64 +@cindex TAI64N +@pindex tai64nlocal Logs are stored in corresponding @file{.redo/tgt.log} file. Each line of it is prefixed with @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamp, that you can decode with @command{tai64nlocal} utility from @@ -34,8 +40,8 @@ you run @command{redo} in parallel, then all @code{stderr} (if no @option{-s}ilence was enabled) is printed as it appears, mixing output from all commands, that is hard to read and investigate. Serialized @command{redo-log} output rearranges output. I will take example from -original apenwarr's idea @url{https://apenwarr.ca/log/20181106, -article}. Serialized output will look like this: +original apenwarr's idea @url{https://apenwarr.ca/log/20181106, article}. +Serialized output will look like this: @verbatim $ redo-log -r A diff --git a/doc/news.texi b/doc/news.texi index a0e9d38d05b7fa6ae6547577723a5d7191ca24b23b21646e7b3d48d8fe463e13..bf3800de92480432342d4e91297d2b62a77877866e1f0bda250bf5096ac35dca 100644 --- a/doc/news.texi +++ b/doc/news.texi @@ -1,4 +1,5 @@ @node News +@cindex news @unnumbered News @anchor{Release 1_23_0} diff --git a/doc/notes.texi b/doc/notes.texi index d4ac6c9503c0752f19e62f64a3087638c6ad53ed87bcf4e1a6390a60e3a45d68..bd33c31464a586f424c5830635923633489a3262bbfe30df21fe105ee425e225 100644 --- a/doc/notes.texi +++ b/doc/notes.texi @@ -1,4 +1,6 @@ @node Notes +@cindex implementation notes +@cindex implementation differences @unnumbered Implementation notes Since there are no strict rules about redo behaviour, here are some diff --git a/doc/ood.texi b/doc/ood.texi index affa14843805ed6fe6af56a86e191b86400d0cc6962dc94a687d9c5cd797c500..a9ab4ad9e048bc23837163994fc8ea44d8a8cfa9872e30da5a15a60b4a021dc4 100644 --- a/doc/ood.texi +++ b/doc/ood.texi @@ -1,4 +1,6 @@ @node OOD +@cindex OOD +@cindex checksum @unnumbered Out-of-date determination The main task for build system is deciding if the target is out-of-date @@ -14,6 +16,7 @@ Also it stores file's size. Obviously if size differs, then file's content too and there is no need to read and hash it. +@vindex REDO_INODE_TRUST But still it could be relatively expensive. So there are additional possible checks that can skip need of hash checking, based on some trust to the underlying filesystem and operating system behaviour, controlled @@ -25,6 +28,7 @@ @item $REDO_INODE_TRUST=none Do not trust filesystem at all, except for file's size knowledge. Most reliable mode. +@cindex time @item $REDO_INODE_TRUST=ctime Trust @code{ctime} value of file's inode. It should change every time inode is updated. If nothing is touched and @code{ctime} is the same, @@ -40,6 +44,7 @@ @url{https://apenwarr.ca/log/20181113, many reasons} it won't. @end table +@cindex mtime Pay attention that although @code{mtime} is considered harmful (link above), and is hardly acceptable in build system like Make, because it compares timestamps of two files, redo is satisfied only with the fact diff --git a/doc/rules.texi b/doc/rules.texi index 3df9752232922cc6d1c3b5228e3e11030b6c2eb6a2bb0c38c7e7093823268630..0bc1fc37bb25ff0d51547df24e75c47dbefe60db231c68b63c39373e1eee3a1b 100644 --- a/doc/rules.texi +++ b/doc/rules.texi @@ -1,4 +1,5 @@ @node Usage rules +@cindex usage rules @unnumbered Usage rules @itemize diff --git a/doc/state.texi b/doc/state.texi index 22aef6c2a8381a7e9c45acea1d08175b4ba346ecf7c9b3e34f5b0e3ef41e64d9..4a76847b7da472555babd1ea9a9dca21170175274e37cc94140998d9a06cc674 100644 --- a/doc/state.texi +++ b/doc/state.texi @@ -1,4 +1,6 @@ @node State +@cindex storage +@cindex state @unnumbered State Dependency and build state is kept inside @file{.redo} subdirectory in diff --git a/doc/thanks.texi b/doc/thanks.texi index 176a4afb2e1d798d00cd57e71abebd9b70387cb1df8900b89250de97c30e474a..c223bfc32d04687f6f12e9f4a4abe0e716b33704639c1ff13046d1ebb258c75d 100644 --- a/doc/thanks.texi +++ b/doc/thanks.texi @@ -1,4 +1,5 @@ @node Thanks +@cindex thanks @unnumbered Thanks There are people deserving to be thanked for helping this project: