Re: a saner bootstrap script

[Gary V. Vaughan]

Hi Stefano,

Thanks again for taking the time to review these files.

As before, I've accepted the changes into my copy wherever I haven't
commented otherwise below.  Since there is no other natural home for
the texi file, since I wrote it specifically for gnulib, so I'm
attaching the latest version here again so that it doesn't get lost.

On 26 Sep 2011, at 00:28, Stefano Lattarini wrote:
> And this is a quick review about the new documentation ...
> 
> On Thursday 22 September 2011, Gary V wrote:
>> needs to be extremely @strong{customisable} and extendable,
>> 
> My syntax checker highlight the word `extendable'; maybe we should
> use `extensible' instead?

'extendable' is a legitimate word (as google will testify), but I think
'extensible' is more popular in computing circles, so I've changed it.

>> 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).

Either sounds fine to me.  Perhaps 'fall-back upon' is more strictly correct.
I've taken your 'fall back to' suggestion in any case.

>> 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.

Changed to "upstream git repository for gnulib".

>> 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.

It is nothing irreversible, as only copies of files added by autopoint
are removed.  cf doc-comment for `func_clean_unused_macros':

# Autopoint can result in over-zealously adding macros into $macro_dir
# even though they are not actually used, for example tests to help   
# build the `intl' directory even though you have specified           
# `AM_GNU_GETTEXT([external])' in your configure.ac.  This function   
# looks removes any macro files that can be found in gnulib,  but     
# are not `m4_include'd by `aclocal.m4'.                              

>> @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?

Well formed in what respect?  Certainly that's a peculiarly finicky bit
of code that you don't want to screw up, so there's definitely scope for
saving hair-pulling if there's a way to catch obviously broken command
specifications here.  I don't have any po using projects though, so I
didn't work as hard on making this part fool proof as I did on plenty of
the other features of bootstrap.

Suggestions are always welcome if you have a specific idea on how to
implement an improvement.

>> @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.

Agreed.  I added a short paragraph to each.

>> @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"?

Other bootstrap-time commands: libtoolize, autopoint, autoconf as
appropriate to the project being bootstrapped.  But I take your point,
and made it more explicit.

>> 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).

I thought that too for a long time, and avoided managing gnulib-tool
invocations by this method for that reason.  Bruno was patient enough
to explain in a couple of different ways that it actually doesn't save
any bootstrap time at all to treat gnulib-cache.m4 as truth, so I now
use the default method for all my new projects.

Thanks again for the review!

Cheers,
-- 
Gary V. Vaughan (gary AT gnu DOT org)

bootstrap.tar.bz2
Description: BZip2 compressed data