From: Sergey Matveev Date: Tue, 22 Feb 2022 15:13:45 +0000 (+0300) Subject: Various info indices X-Git-Tag: v1.23.0~4 X-Git-Url: http://www.git.cypherpunks.ru/?p=goredo.git;a=commitdiff_plain;h=240e970cd64ca6465469af669e6b6333550ff520 Various info indices --- diff --git a/doc/cmds.texi b/doc/cmds.texi index de8d374..b3e19d7 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 @@ won't continue and will exit with failure message. 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 @@ There are other commands that could be found in other implementations too: 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.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 e494e88..7fc12a0 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 4d0364b..dd11399 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 6bb2fd1..c1d5218 100644 --- a/doc/index.texi +++ b/doc/index.texi @@ -9,7 +9,8 @@ Copyright @copyright{} 2020-2022 @email{stargrave@@stargrave.org, Sergey Matveev @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 @@ If you are not familiar with the redo, here are advisable links to read: @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. @@ -58,4 +62,19 @@ maillist. Announcements also go to this mailing list. @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 1032143..ba0f0cc 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 a7e640a..db795fe 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 b68b88e..e827a6c 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 @@ kept, previous one is overwritten. $ 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 035acdc..b1487f7 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 fa36869..b7e09e7 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 7f00696..e4d5555 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 @@ output for that purpose. 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 @@ by @env{$REDO_INODE_TRUST} environment variable value: 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 @@ file's content is updated. But unfortunately there are @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 dedcf5b..786921c 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 4c84b41..db32628 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 e190a0f..677b054 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: