Bruno Haible <br...@clisp.org> writes:
> Thanks for the work on this. Looks quite good, nearly ready to commit.
>
> Just three small remarks:
>
>> +``foobar'' needs a modified version of, say, @file{stdint_.h}, it
>
> Nowadays this file is called @file{stdint.in.h}.
Thanks, I've fixed that now.
>> ... or it has to use the
>> +...@samp{--avoid=stdint} option and provide the modified @code{stdint}
>> +module in a different directory and use libtool convenience libraries.
>
> I don't understand the part "and use libtool convenience libraries". The
> user can provide a modified module, and gnulib-tool will use the
> modified module just like it would use the original gnulib module. There
> is no need to create a .a library that includes another .a library.
> Additionally, the 'stdint' module does not provide a .o file, making
> this sentence even more confusing. [Yes I know it was me who wrote this
> sentence 4 years ago ;-)]
I didn't understand that part either, but I assumed that you did ;-)
I fixed this by just deleting the "and use libtool convenience
libraries" part of the sentence.
>> +...@item
>> +You can also add unstructured amounts of code to the library, by grouping
>> +the non-Gnulib files of the library in a single kitchen-sink ``module.''
>
> Here one could add a remark that this kind of kitchen-sink module is not
> needed when you use the gnulib-tool option @samp{--makefile-name}.
I haven't used that option and don't see any documentation
(besides --help), so I'm not certain how it helps. I could
guess, but I decided to just add this to the bullet: "(This kind
of kitchen-sink module is not needed when you use the
@command{gnulib-tool} option @samp{--makefile-name}.)" If you
want to edit it to explain better, that is probably a good idea.
> You are then welcome to commit and push this. Many thanks!
And thank you for your helpful comments.
I pushed it out, as follows:
--8<--------------------------cut here-------------------------->8--
>From 47e899ad11a04647942b39dd501bfc2381e9b2f0 Mon Sep 17 00:00:00 2001
From: Ben Pfaff <b...@cs.stanford.edu>
Date: Wed, 9 Jun 2010 20:53:13 -0700
Subject: [PATCH] Add "Extending Gnulib" chapter to manual.
* doc/gnulib.texi (Writing Modules): Add cross-reference to new chapter.
(Extending Gnulib): New chapter.
* doc/gnulib-intro.texi (Openness): Add cross-reference to new chapter.
---
ChangeLog | 10 ++++++
doc/gnulib-intro.texi | 4 +-
doc/gnulib.texi | 83 +++++++++++++++++++++++++++++++++++++++++++++++-
3 files changed, 93 insertions(+), 4 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 57d9e2c..71803c7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2010-06-09 Ben Pfaff <b...@cs.stanford.edu>
+ Bruno Haible <br...@clisp.org>
+
+ Add "Extending Gnulib" chapter to manual.
+ * doc/gnulib.texi (Writing Modules): Add cross-reference to new
+ chapter.
+ (Extending Gnulib): New chapter.
+ * doc/gnulib-intro.texi (Openness): Add cross-reference to new
+ chapter.
+
2010-06-09 Bruno Haible <br...@clisp.org>
Avoid relocwrapper link errors due to gnulib replacement functions.
diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index 4cb86b8..52191ec 100644
--- a/doc/gnulib-intro.texi
+++ b/doc/gnulib-intro.texi
@@ -346,5 +346,5 @@ locally add modules that are treated like Gnulib modules by
@code{gnulib-tool}.
@end enumerate
-This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}.
-
+This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}
+(@pxref{Extending Gnulib}).
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 4cbc9e7..a1f5446 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -54,6 +54,7 @@ Documentation License''.
* Introduction::
* Invoking gnulib-tool::
* Writing modules::
+* Extending Gnulib::
* Miscellaneous Notes::
* POSIX Substitutes Library:: Building as a separate substitutes library.
* Header File Substitutes:: Overriding system headers.
@@ -117,8 +118,8 @@ Resources:
@node Writing modules
@chapter Writing modules
-This chapter explains how to write modules of your own, either for your own
-package (to be used with gnulib-tool's @samp{--local-dir} option), or for
+This chapter explains how to write modules of your own, either to
+extend Gnulib for your own package (@pxref{Extending Gnulib}), or for
inclusion in gnulib proper.
The guidelines in this chapter do not necessarily need to be followed for
@@ -608,6 +609,84 @@ before every release.
@end enumerate
+...@node Extending Gnulib
+...@chapter Extending Gnulib
+
+Gnulib modules are intended to be suitable for widespread use. Most
+problems with Gnulib can and should be fixed in a generic way, so that
+all of Gnulib's users can benefit from the change. But occasionally a
+problem arises that is difficult or undesirable to fix generically, or
+a project that uses Gnulib may need to work around an issue before the
+Gnulib maintainers commit a final fix. Maintainers may also want to
+add their own pools of modules to projects as Gnulib ``staging
+areas.''
+
+The obvious way to make local changes to Gnulib modules is to use
+...@command{gnulib-tool} to check out pristine modules, then to modify
+the results in-place. This works well enough for short-lived
+experiments. It is harder to keep modified versions of Gnulib modules
+for a long time, even though Git (or another distributed version
+control systems) can help out a lot with this during the development
+process.
+
+Git, however, doesn't address the distribution issue. When a package
+``foobar'' needs a modified version of, say, @file{stdint.in.h}, it
+either has to put a comment into @file{foobar/autogen.sh} saying
+``Attention! This doesn't work with a pristine Gnulib, you need this
+and that patch after checking out Gnulib,'' or it has to use the
+...@samp{--avoid=stdint} option and provide the modified @code{stdint}
+module in a different directory.
+
+The @option{--local-dir} option to @command{gnulib-tool} solves this
+problem. It allows the package to override or augment Gnulib. This
+means:
+
+...@itemize @bullet
+...@item
+You can store files that are to override Gnulib files or modules.
+
+...@item
+You can store context diffs to be applied to Gnulib files.
+
+...@item
+You can add modules of your own, that are not (yet) in Gnulib.
+
+...@item
+You can also add unstructured amounts of code to the library, by
+grouping the non-Gnulib files of the library in a single kitchen-sink
+``module.'' (This kind of kitchen-sink module is not needed when you
+use the @command{gnulib-tool} option @samp{--makefile-name}.)
+...@end itemize
+
+In a release tarball, you can distribute the contents of this
+...@option{--local-dir} directory that will be combinable with newer
+versions of Gnulib, barring incompatible changes to Gnulib.
+
+If the @samp{--local-d...@var{directory}} option is specified, then
+...@command{gnulib-tool} looks in @fi...@var{directory}} whenever it
+reads a file from the Gnulib directory. Suppose @command{gnulib-tool}
+is looking for @var{file}. Then:
+
+...@itemize @bullet
+...@item
+If @fi...@var{directory}/@var{file}} exists, then @samp{gnulib-tool} uses
+it instead of the file included in Gnulib.
+
+...@item
+Otherwise, if @fi...@var{directory}/@var{file}.diff} exists, then
+...@command{gnulib-tool} uses the file from Gnulib after applying the diff
+using the @command{patch} program.
+
+...@item
+Otherwise, @command{gnulib-tool} uses the file included in Gnulib.
+...@end itemize
+
+Please make wise use of this option. It also allows you to easily
+hold back modifications you make to Gnulib macros in cases it may be
+better to share them.
+
+
+
@node Miscellaneous Notes
@chapter Miscellaneous Notes
--
1.7.1
--
"Sanity is not statistical."
--George Orwell
