Re: Using gnulib for both a library and programs

[Christian Egli]

Eric Blake <address@hidden> writes:

> On 06/05/2015 04:31 AM, Christian Egli wrote:
>
>> Would this make for a section in the manual or is this use case to
>> niche, in other words should I write something up?
>
> Yes, please write up what worked for you.  It's complicated enough that
> having a documentation page to point to will help the next client (in
> the past I've wanted to do it myself for the M4 package, but haven't
> done the research on what it would require), and having it public might
> make it easier to spot improvements to the process and/or ideas for
> improving the tools to make the process easier.

Here's a first attempt:

Changes from HEAD to working tree
1 file changed, 109 insertions(+)
 doc/gnulib-tool.texi | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++

        Modified   doc/gnulib-tool.texi
diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index f749abb..93b269a 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.
+* Multiple instances::          Using Gnulib for both a library and a binary
 * gettextize and autopoint::    Caveat: @code{gettextize} and @code{autopoint} 
users!
 * Localization::                Handling Gnulib's own message translations.
 * VCS Issues::                  Integration with Version Control Systems.
@@ -448,6 +449,114 @@ 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.
 
 
address@hidden Multiple instances
address@hidden Using Gnulib for both a library and a binary
+
+Your project might build both a library and some accompanying binaries
+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
+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.
+
address@hidden
+.
+|-- configure.ac
+|-- lib
+|   |-- foo.c
+|   `-- Makefile.am
+|-- Makefile.am
+`-- src
+    |-- bar.c
+    `-- Makefile.am
address@hidden example
+
+You can now add two instances of Gnulib to your project in separate
+source trees:
+
address@hidden
+~/src/libfoo$ gnulib-tool --import --lib=libgnu --source-base=gnulib \
+              --m4-base=gnulib/m4 --macro-prefix=gl strndup
+~/src/libfoo$ gnulib-tool --import --lib=libgnutools \
+              --source-base=src/gnulib --m4-base=src/gnulib/m4 \
+              --macro-prefix=gl_tools getopt-gnu
address@hidden example
+
+The first one will import the module @code{strndup} in @file{gnulib}
+and the second one will import @code{getopt-gnu} in @file{src/gnulib}
+and you will end up with the following source tree (many files omitted
+in the interest of brevity):
+
address@hidden
+.
+|-- configure.ac
+|-- gnulib
+|   |-- m4
+|   |-- strndup.c
+|-- lib
+|   |-- foo.c
+|   `-- Makefile.am
+|-- Makefile.am
+`-- src
+    |-- bar.c
+    |-- gnulib
+    |   |-- getopt.c
+    |   |-- getopt.in.h
+    |   |-- m4
+    `-- Makefile.am
address@hidden example
+
+Integration with your code is basically the same as outlined in
address@hidden import} with the one exception that you have to add both
+the macro @code{gl_EARLY} and the macro @code{gl_tools_EARLY} to your
address@hidden (and of course also both macros @code{gl_INIT} and
address@hidden). Obviously the name of the second macro is
+dependent on the value of the @option{--macro-prefix} option in your
address@hidden invocation.
+
address@hidden
+...
+AC_PROG_CC
+gl_EARLY
+gl_tools_EARLY
+...
+# For gnulib.
+gl_INIT
+gl_tools_INIT
+...
address@hidden example
+
+Also as outlined in @ref{Initial import} you will have to add compiler
+and linker flags. For the library you might have to add something
+along the line of the following to your @file{Makefile.am}:
+
address@hidden
+...
+AM_CPPFLAGS = -I$(top_srcdir)/gnulib -I$(top_builddir)/gnulib
+...
+libfoo_la_LIBADD = $(top_builddir)/gnulib/libgnu.la
+...
address@hidden example
+
+Correspondingly for the binary you will have to add something along
+the lines of to the following:
+
address@hidden
+...
+AM_CPPFLAGS = -I$(top_srcdir)/src/gnulib -I$(top_builddir)/src/gnulib
+...
+LIBADD = $(top_builddir)/src/gnulib/libgnutools.la
+...
address@hidden example
+
+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
 

Thanks
Christian

-- 
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland