bug-gnulib
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: a saner bootstrap script [Was Re: I fixed this once already]


From: Stefano Lattarini
Subject: Re: a saner bootstrap script [Was Re: I fixed this once already]
Date: Sun, 25 Sep 2011 19:28:38 +0200
User-agent: KMail/1.13.7 (Linux/2.6.30-2-686; KDE/4.6.5; i686; ; )

And this is a quick review about the new documentation ...

On Thursday 22 September 2011, Gary V wrote:
>
> @node Bootstrap
> @chapter Bootstrap
> 
> The process of executing the various tools required to bring all the
> generated files up to date in a directory freshly checked out from
> source control can be quite involved.  Many @sc{gnu} project
>
I believe that gnulib/autotools documentation doesn't use the @sc macro
anymore; you should just use "many GNU projects" here.  More instances
below.

> use @samp{bootstrap}
>
Wouldn't one among address@hidden' or address@hidden' be
preferable?

> script to execute some or all of the following in the correct
> order: @command{gnulib-tool}, @command{autopoint},
> @command{libtoolize}, @command{autoreconf}. Often there's also
> additional file-wrangling and assorted book-keeping that also falls
> under the behest of @samp{bootstrap},
>
IMVHO, a simpler language here might help developers whose native
language is not English.  Something like this maybe:

  Often there's also additional file-processing and assorted book-keeping
  that also falls under the control of @samp{bootstrap},

> but it's wasteful for the maintainers of all these projects to
> manually reinvent a custom script on a case-by-case basis.
>
> Gnulib is designed to provide a central library of exemplar
> implementations to promote the sharing of useful common code among
> @sc{gnu} project maintainers. However, the bootstrapping needs of these
> projects vary enormously, so Gnulib's @samp{boottrap}
>
Typo: s/boottrap/bootstrap/

> needs to be extremely @strong{customisable} and extendable,
>
My syntax checker highlight the word `extendable'; maybe we should
use `extensible' instead?

> with less effort than would be otherwise required to invent an adhoc
>
Typo: s/adhoc/ad-hoc/

> solution.

> @menu
> * Customisation::
> * Usage Patterns::
> * Known Bugs::
> @end menu
>
> @node Customisation
> @section Customisation
>
> There are four distinct ways to customize the functionality of
> @command{bootstrap}, all requiring creation of a @file{bootstrap.conf}
> file in the same directory as this @command{bootstrap} script proper.
>
I personally find the following formulation slightly clearer:
"in the same directory of the @command{bootstrap} script itself"

> @menu
> * Configuration Variables::
> * Require Variables::
> * Hook Functions::
> * Function Replacement::
> @end menu
>
> @node Configuration Variables
> @subsection Configuration Variables
>
> For all but the more complex customisations, you need only change
> the value of a selection of the following shell variables in
> @file{bootstrap.conf}, to reflect whatever is appropriate to your
> package.
>
> @example
>    vc_ignore=".gitignore"
> @end example

> @table @code
>
> @cnindex buildreq
> @item buildreq
> A newline delimited
s/newline delimited/newline-delimited/?

> list of triples of @strong{programs} (which must not exit with non-zero
> status in response to @option{--version}), the
>
The double negation is unclear; I suggest to use this instead:

 "which must accept the option `--version' without hanging on failing"

> @strong{minimum version required} (or just `-' in the version field if
> any version will be sufficient) and @strong{homepage @acronym{url} (to
> help users locate missing packages)

> @smallexample
> buildreq='      
>        git        1.5.5   http://git-scm.com
>        help2man   1.29    http://www.gnu.org/s/help2man
>'
> @end smallexample     

[SNIP]

> ...
> @itemx source_base
> @itemx tests_base
> These are normally extracted from @file{gnulib-cache.m4}, regardless of
> their values in @file{bootstrap.conf}.

> When that file is not yet created, then @command{bootsrap}
Typo: s/bootsrap/bootstrap/

> will fall-back automatically on
>
Is "fall back on" grammatically correct?  I've always thought that one could
only say "fall back to" ...  (of course I'll defer to the judgement of the
native speakers on this, that should be crystal-clear).

> the gnulib defaults; unless you set
> alternative values here in @file{bootstrap.conf}.

> @cnindex gnulib_path
> @cnindex gnulib_url
> @item gnulib_path
> @itemx gnulib_url
> Relative path to the local gnulib submodule, and url to the upstream
> git repository.
>
"upstream gir repository" of what exactly?  It's not completely clear
IMHO.

> These are only used if a new gnulib submodule needs to
> be created, otherwise they are ignored and the values stored in
> @file{.gitmodules} are used instead.
>
> Normally, you can leave these untouched, and @file{bootstrap}
>
s/@file/@command/, for consitency with previous usages?

> will correctly check out a gnulib submodule from the directory passed
> with @option{--gnulib-srcdir}, or else the
>
s/elser the/else from the/?  It seems slighlty clearer to me.

> upstream repository at @sc{gnu} savannah.
>
> @cnindex gnulib_tool_options
> @item gnulib_tool_options
> Additional options to pass to @command{gnulib-tool} when it is called.
>
> @smallexample
> gnulib_tool_options='
>        --no-changelog
>        --libtool
> '
> @end smallexample

> @cnindex gnulib_precious
> @item gnulib_precious
> Normally, @command{bootstrap} removes any macro-files that are not
> included by @file{aclocal.m4} before it returns, except for files
> listed in this variable which are always kept.
>
Are you sure it is a good idea to do so by default?  The potential for
disruption seems pretty high to me.  Note that this is an OBJECTION TO
THE BEHAVIOUR, not the documentation.

> @smallexample
> gnulib_precious='
>        gnulib-cache.m4
> '
> @end smallexample

> @cnindex min_cmd_len
> @item min_cmd_len
> When truncating long commands for display at runtime, always allow at
> least this many characters before truncating.

> @cnindex po_download_command_format
> @item po_download_command_format
> The command to download all @samp{.po} files for a specified domain
> into a specified directory, where the first %s is filled in with the
> @emph{domain name}, and the second with the @emph{destination
> directory}.  Use @command{rsync}'s @option{-L} and @option{-r} options
> because the latest @samp{/%s} directory and the @samp{.po} files within
> are all symlinks.
>
> @smallexample
> po_download_command_format=\
> "rsync --delete --exclude '*.s1' -Lrtvz \
> 'translationproject.org::tp/latest/%s/' '%s'"
> @end smallexample
>
Could a runtime check be added to bootstap, to ensure that an
user-overridden `$po_download_command_format' is well formed?
Or would the ratio burdens/benefits be too high?

> @cnindex extra_locale_categories
> @item extra_locale_categories
> Other locale categories that need message catalogs.
>
> @cnindex xgettext_options
> @item xgettext_options
> Additional @command{xgettext} options to use.  Gnulib might provide you
>
> [SNIP]
>
I'd like to have it explicitly stated that a project that is not
interested in NLS support should not worry about these laster three
variables (`$po_download_command_format', `$extra_locale_categories'
and `$xgettext_options') at all.

> @node Hook Functions
> @subsection Hook Functions
>
> Many of the key functions in @file{bootsrap}
>
Typo: s/bootsrap/bootstrap/.  Also, shouldn't you use address@hidden'
instead of address@hidden' here, for consistency with the previous usages?

> will run one or more hook
> functions before they return.  Essentially, all that the entire script
> does is to define a lot of functions (some of which will run hooks),
> then source the contents of your @file{bootstrap.conf} customisations,
> and then run the @code{func_bootstrap} function.
>
Nice and clear explanation, I like it :-)

> @node Configuration all kept in @file{bootstrap.conf}
> @subsection Configuration all kept in @file{bootstrap.conf}
> All the parameters for running @command{gnulib-tool} and others
>
Who/what are these "others"?

> are maintained in @command{bootstrap.conf}. This is the default
> usage pattern.
>
> In order for this to work, when you wish to add or remove a gnulib
> module from your package, amend the value of @var{gnulib_modules} in
> @file{bootstrap.conf} (and similarly for any other parameters) and
> rerun @command{bootstrap} to import everything anew.
>
Doesn't this worsen performance too much?  (Sorry if it's a dumb question,
but my knowledge of gnulib-tool importation/updating process is shaky at
best).

> To avoid things getting out of sync, you should never run
> @command{gnulib-tool} directly.
>

Thanks,
  Stefano



reply via email to

[Prev in Thread] Current Thread [Next in Thread]