Hi Reuben, I wrote: > The trick to use --makefile-name in order to add some tweaks is > currently undocumented. It would deserve to be documented
I've now added this documentation. Also a doc tweak: The opposite term for "library" is "program", not "binary". Libraries exist as source as a binaries (.a and .so files), like programs. Bruno
>From c35197077531646016d9c2dd3f3050dbfd765ef0 Mon Sep 17 00:00:00 2001 From: Bruno Haible <[email protected]> Date: Sun, 10 Dec 2017 14:00:43 +0100 Subject: [PATCH 1/2] doc: Tweak wording. * doc/gnulib-tool.texi (Multiple instances): Talk about "programs", not "binaries". --- ChangeLog | 6 ++++++ doc/gnulib-tool.texi | 15 ++++++++------- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3a7ddc1..99e98dc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2017-12-10 Bruno Haible <[email protected]> + + doc: Tweak wording. + * doc/gnulib-tool.texi (Multiple instances): Talk about "programs", not + "binaries". + 2017-12-05 Sam Steingold <[email protected]> Bruno Haible <[email protected]> diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index 9614c9f..7f43d4a 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -44,7 +44,7 @@ a real run without changing anything. * Modified imports:: Changing the import specification. * Simple update:: Tracking Gnulib development. * Source changes:: Impact of Gnulib on your source files. -* Multiple instances:: Using Gnulib for both a library and a binary +* Multiple instances:: Using Gnulib for both a library and a program * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users! * Localization:: Handling Gnulib's own message translations. * VCS Issues:: Integration with Version Control Systems. @@ -452,18 +452,18 @@ and these flags have no effect after any system header file has been included. @node Multiple instances -@section Using Gnulib for both a library and a binary +@section Using Gnulib for both a library and a program -Your project might build both a library and some accompanying binaries +Your project might build both a library and some accompanying programs in the same source tree. In that case you might want to use different -modules for the library than for the binaries. Typically the binaries +modules for the library than for the programs. Typically the programs might want to make use of @code{getopt-posix} or @code{version-etc}, while the library wants to stay clear of these modules for technical or licensing reasons. Let's assume that your project contains a @file{lib} directory where the source of the library resides and a @file{src} directory for the -sources of the binaries as follows. +sources of the programs as follows. @example . @@ -544,8 +544,8 @@ libfoo_la_LIBADD = $(top_builddir)/gnulib/libgnu.la ... @end example -Correspondingly for the binary you will have to add something along -the lines of to the following: +Correspondingly for the programs you will have to add something like +this: @example ... @@ -559,6 +559,7 @@ The name of the library that you have pass in the linker option depends on the @option{--lib} option in @command{gnulib-tool} invocation. + @node gettextize and autopoint @section Caveat: @code{gettextize} and @code{autopoint} users -- 2.7.4
>From 66a7f1c706907612a260565cec36b1740caf8a48 Mon Sep 17 00:00:00 2001 From: Bruno Haible <[email protected]> Date: Sun, 10 Dec 2017 16:28:43 +0100 Subject: [PATCH 2/2] doc: New section "Modifying the build rules of a Gnulib import directory". * doc/gnulib-tool.texi (Modified build rules): New node. --- ChangeLog | 5 ++++ doc/gnulib-tool.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) diff --git a/ChangeLog b/ChangeLog index 99e98dc..96ba6d0 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2017-12-10 Bruno Haible <[email protected]> + doc: New sect. "Modifying the build rules of a Gnulib import directory". + * doc/gnulib-tool.texi (Modified build rules): New node. + +2017-12-10 Bruno Haible <[email protected]> + doc: Tweak wording. * doc/gnulib-tool.texi (Multiple instances): Talk about "programs", not "binaries". diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index 7f43d4a..b4d548d 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -44,6 +44,7 @@ a real run without changing anything. * Modified imports:: Changing the import specification. * Simple update:: Tracking Gnulib development. * Source changes:: Impact of Gnulib on your source files. +* Modified build rules:: Modifying the build rules of a Gnulib import * Multiple instances:: Using Gnulib for both a library and a program * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users! * Localization:: Handling Gnulib's own message translations. @@ -451,6 +452,74 @@ used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems), and these flags have no effect after any system header file has been included. +@node Modified build rules +@section Modifying the build rules of a Gnulib import directory + +In some cases, you may want to set additional compiler options for +use within the Gnulib import directory. For example, the +@samp{relocatable} module operates better if you define the C macros +@code{ENABLE_COSTLY_RELOCATABLE} and @code{INSTALLDIR} during its +compilation. + +There are two ways to do so: Use of the @code{gnulib-tool} option +@code{--makefile-name}, and a kitchen-sink module. + +With the @code{gnulib-tool} option @code{--makefile-name}, you are +telling @code{gnulib-tool} to generate an includable @code{Makefile.am} +portion, rather than a self-contained @code{Makefile.am}. For example, +when you use @code{--makefile-name=Makefile.gnulib}, @code{gnulib-tool} +will generate @code{Makefile.gnulib}, and you will provide a +hand-written @code{Makefile.am} that includes @code{Makefile.gnulib} +through a line such as +@smallexample +include Makefile.gnulib +@end smallexample +Before this include, you need to initialize this set of @code{Makefile.am} +variables: +@itemize @bullet +@item +@code{AUTOMAKE_OPTIONS} +@item +@code{SUBDIRS} +@item +@code{noinst_HEADERS} +@item +@code{noinst_LIBRARIES} +@item +@code{noinst_LTLIBRARIES} +@item +@code{pkgdata_DATA} (only with Automake @geq{} 1.11.4) +@item +@code{EXTRA_DIST} +@item +@code{BUILT_SOURCES} +@item +@code{SUFFIXES} +@item +@code{MOSTLYCLEANFILES} +@item +@code{MOSTLYCLEANDIRS} +@item +@code{CLEANFILES} +@item +@code{DISTCLEANFILES} +@item +@code{MAINTAINERCLEANFILES} +@item +@code{AM_CPPFLAGS} +@item +@code{AM_CFLAGS} +@end itemize +@code{AUTOMAKE_OPTIONS} should be initialized as described in +@ref{Options,,Changing Automake's Behavior,automake,GNU Automake}. +The other variables can be initialized to empty. However, you will most +likely want to initialize some of them with non-empty values, in order +to achieve the desired customization. + +The other approach, the kitchen-sink module, is more advanced. See +chapter @ref{Extending Gnulib}. + + @node Multiple instances @section Using Gnulib for both a library and a program -- 2.7.4
