From: Karl Berry Date: Tue, 18 Jun 2024 15:54:27 +0000 (-0700) Subject: doc: preserve old node name. X-Git-Tag: v1.16.92~10 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fbf571f34e65bf3de4461410965e83a387f75c68;p=thirdparty%2Fautomake.git doc: preserve old node name. Following 4981e5997 (doc: modernize version control doc). * doc/automake.texi (CVS): insert @anchor{CVS} so this (prior) node name will still work, e.g., in HTML. Reflow surrounding source. --- diff --git a/doc/automake.texi b/doc/automake.texi index 9d1d7ea8a..0ae2d4f33 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -12415,6 +12415,7 @@ lists. @node Version Control @section Version control and generated files +@anchor{CVS}@c old name of node, keep for compatibility @subheading Background: distributed generated Files @cindex generated files, distributed @cindex rebuild rules @@ -12426,33 +12427,33 @@ end-users do not have to install the maintainer tools required to rebuild them. Other generated files like Lex scanners, Yacc parsers, or Info documentation are usually distributed on similar grounds. -Automake output generates rules in @file{Makefile}s to rebuild these files. -For instance, @command{make} will run @command{autoconf} to rebuild -@file{configure} whenever @file{configure.ac} is changed. This makes -development safer by ensuring a @file{configure} is never out-of-date -with respect to @file{configure.ac}. +Automake output generates rules in @file{Makefile}s to rebuild these +files. For instance, @command{make} will run @command{autoconf} to +rebuild @file{configure} whenever @file{configure.ac} is changed. +This makes development safer by ensuring a @file{configure} is never +out-of-date with respect to @file{configure.ac}. As generated files shipped in packages are up-to-date, and because -@command{tar} preserves times-tamps, these rebuild rules are not +@command{tar} preserves timestamps, these rebuild rules are not triggered when a user unpacks and builds a package. @subheading Background: Version Control and Timestamps @cindex timestamps and version control @cindex version control and timestamps -Typically when you update files with version control commands, -working files will have the timestamp of your update, -not the original timestamp of the commit. This is meant to -make sure that @command{make} notices that sources files have been updated. +Typically when you update files with version control commands, working +files will have the timestamp of your update, not the original +timestamp of the commit. This is meant to make sure that +@command{make} notices that source files have been updated. This timestamp shift is troublesome when both sources and generated files are kept under version control. Because version control -commands often process files in lexical -order, @file{configure.ac} will appear newer than @file{configure} -after a version control command that updates both files, even if -@file{configure} was newer than @file{configure.ac} when it was -committed. Calling @command{make} will then trigger a spurious rebuild -of @file{configure}. +commands often process files in lexical order, @file{configure.ac} +will appear newer than @file{configure} after a version control +command that updates both files, even if @file{configure} was newer +than @file{configure.ac} when it was committed. Calling +@command{make} will then trigger a spurious rebuild of +@file{configure}. @subheading Living with Version Control in Autoconfiscated Projects @cindex version control and generated files @@ -12518,22 +12519,21 @@ touch $(git ls-files '*/Makefile.in' '*.info') @item In distributed development, developers are likely to have different versions of the maintainer tools installed. In this case rebuilds -triggered by clock skew can lead to spurious changes -to generated files. There are several solutions to this: +triggered by clock skew can lead to spurious changes to generated +files. There are several solutions to this: @itemize @item All developers should use the same versions, so that the rebuilt files -are identical to files in the repository. -(This starts to be difficult when each -project you work on uses different versions.) +are identical to files in the repository. (This becomes difficult +when different projects on which you are working use different versions.) @item Or people use a script to fix the timestamp after a checkout (the GCC folks have such a script). @item -Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will -disable all of these rebuild rules by default. This is further discussed -in @ref{maintainer-mode}. +Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which disables +all of these rebuild rules by default. This is further discussed in +@ref{maintainer-mode}. @end itemize @item @@ -12547,19 +12547,20 @@ change to @file{Makefile.am} right before checking in both files (without rebuilding @file{Makefile.in} to account for the change). This last change to @file{Makefile.am} makes the copy of -@file{Makefile.in} out-of-date. Assuming version control processes files -alphabetically, when another developer updates their -tree, @file{Makefile.in} will happen to be newer than -@file{Makefile.am}. This other developer will not see that -@file{Makefile.in} is out-of-date. +@file{Makefile.in} out-of-date. Assuming version control processes +files alphabetically, when another developer updates their tree, +@file{Makefile.in} will happen to be newer than @file{Makefile.am}. +This other developer will not see that @file{Makefile.in} is +out-of-date. @end itemize @subsubheading Generated Files out of Version Control -One way to get version control and @command{make} working peacefully is to never -store generated files in version control, i.e., do not version-control -files that are @file{Makefile} targets (also called @emph{derived} files). +One way to get version control and @command{make} working peacefully +is to never store generated files in version control, i.e., do not +version-control files that are @file{Makefile} targets (also called +@emph{derived} files). This way developers are not annoyed by changes to generated files. It does not matter if they all have different versions (assuming they are @@ -12567,10 +12568,11 @@ compatible, of course). And finally, timestamps are not lost; changes to source files can't be missed as in the @file{Makefile.am}/@file{Makefile.in} example discussed earlier. -The drawback is that the repository does not contain some files that are -is distributed, so builders now need to install various development -tools (maybe even specific versions) before they can build a checkout. -But, after all, the job of version control is versioning, not distribution. +The drawback is that the repository does not contain some files that +are is distributed, so builders now need to install various +development tools (maybe even specific versions) before they can build +a checkout. But, after all, the job of version control is versioning, +not distribution. Allowing developers to use different versions of their tools can also hide bugs during distributed development. Indeed, developers will be @@ -12591,10 +12593,11 @@ maintained elsewhere. For instance, tools like @command{gettextize} and @command{autopoint} (from Gettext) or @command{libtoolize} (from Libtool), will install or update files in your package. -These files, whether they are kept under version control or not, raise similar -concerns about version mismatch between developers' tools. The -Gettext manual has a section about this; see @ref{Version Control Issues,, -Integrating with Version Control Systems, gettext, GNU gettext tools}. +These files, whether they are kept under version control or not, raise +similar concerns about version mismatch between developers' tools. +The Gettext manual has a section about this; see @ref{Version Control +Issues,, Integrating with Version Control Systems, gettext, GNU +gettext tools}. @node maintainer-mode @section @command{missing} and @code{AM_MAINTAINER_MODE}