Re: [patch 14/19] 298-gary-document-libltdl-build-modes.diff Queue

[Ralf Wildenhues]

Hi Gary,

Reading the documentation is easier than checking its implementation. :)

* Gary V. Vaughan wrote on Mon, Oct 10, 2005 at 12:26:38PM CEST:
>  doc/libtool.texi |   92 
> +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 files changed, 90 insertions(+), 2 deletions(-)

OK when nits and comments below addressed and requirements committed.  :-)

By the way, I'm pretty sure the documentation will hopelessly ask to
much of a newbie (or non-Autotools expert FWIW).  But improving on that
(without backwards incompatibility) after the alpha release should be
easily possible, including some other outstanding doc patches.

Cheers,
Ralf

> Index: libtool--devo--1.0/ChangeLog
> from  Gary V. Vaughan  <address@hidden>
>       * tests/testsuite.at (_LTDL_PROJECT_FILES): Factored out from
>       common code to build a basic libltdl using project.
>       * tests/old-m4-iface.at, tests/standalone.at, tests/subproject.at:
>       Use it.

This ChangeLog part belongs to a different patch (and is missing there).

>       * doc/libtool.texi (Distributing libltdl): Document correct use of
>       LT_CONFIG_LTDL_DIR mode argument with Autoconf and Automake.
> 
> Index: libtool--devo--1.0/doc/libtool.texi
> ===================================================================
> --- libtool--devo--1.0.orig/doc/libtool.texi
> +++ libtool--devo--1.0/doc/libtool.texi
> @@ -4186,10 +4186,98 @@ or against both a local convenience libr
>  is bad.  Ensuring that only one copy of the libltdl sources are linked
>  into any program is left as an exercise for the reader.
>  
> address@hidden LT_CONFIG_LTDL_DIR (@var{DIRECTORY})
> address@hidden LT_CONFIG_LTDL_DIR (@var{DIRECTORY}. @var{LTDL-MODE})
>  Declare @var{DIRECTORY} to be the location of the @code{libltdl}
>  source files, for @command{libtoolize --ltdl} to place
> -them. @xref{Invoking libtoolize}, for more details.
> +them. @xref{Invoking libtoolize}, for more details.  Providing that you

better(?): Provided

> +add an appropriate @code{LT_CONFIG_LTDL} call in your
> address@hidden before calling @command{libtoolize}, then the

s/then // would be better, IMVHO.

> +appropriate @code{libltdl} files will be installed automatically without
> +manually specifying the mode to @command{libtoolize} explicitly.
> +
> address@hidden can be either @samp{nonrecursive}, @samp{recursive}, or
> address@hidden depending on how you wish for your project to build
> address@hidden:
> +
> address@hidden @samp
> address@hidden nonrecursive
> +This is how the Libtool project distribution builds the @code{libltdl}
> +we ship and install.  If you wish to use Automake to build
> address@hidden without invoking a recursive make to descend into the
> address@hidden subdirectory, then use this option.  You will need to set
> +your configuration up carefully to make this work properly, and you will
> +need a release of Automake that supports @code{subdir-objects}.  In your
> address@hidden, add:

Isn't the following more correct?

  .. you will need releases of Autoconf and Automake that support
  @code{subdir-objects} and @code{LIBOBJDIR} properly.

> +
> address@hidden
> +LT_CONFIG_LTDL_DIR([libltdl], [nonrecursive])
> +AM_PROG_CC_C_O
> +AM_INIT_AUTOMAKE([subdir-objects])
> +LT_WITH_LTDL
> address@hidden example

For safety, we should add `AC_PROG_CC' before `AM_PROG_CC_C_O'.
Is it necessary to add LT_CONFIG_LTDL_DIR before AM_INIT_AUTOMAKE
(if yes, then the former should have an AC_BEFORE warning to this end).
If not (which I think), then we should not do so.  So then we would end
up like this:

AM_INIT_AUTOMAKE([subdir-objects])
AC_PROG_CC
AM_PROG_CC_C_O
LT_CONFIG_LTDL_DIR([libltdl], [nonrecursive])
LT_WITH_LTDL

Rationale: people just _love_ to keep macros corresponding to different
packages separated.  We even do this ourseleves, in toplevel configure.ac
(except for the `LT_CONFIG_LTDL_DIR' call you added).

People will have a hard time understanding that LT_CONFIG_LTDL_DIR
should be separated from the rest of all the Libtool/libltdl related
macros.  Any requirements should be diagnosed if possible, or an endless
stream of bug reports is predictable..

> +
> address@hidden
> +And add the following near the top of your @file{Makefile.am}:
> +
> address@hidden
> +BUILT_SOURCES =
> +EXTRA_DIST =
> +CLEANFILES =
> +MOSTLYCLEANFILES =
> +
> +include libltdl/Makefile.inc
> address@hidden example
> +
> address@hidden
> +Unless you don't build any other libraries from this @file{Makefile.am},
> +you will also need to change @code{lib_LTLIBRARIES} to assign with
> address@hidden so that the @code{libltdl} targets declared in
> address@hidden are not overwritten.

Hmm.  Why not have the user add
  noinst_LTLIBRARIES =
  lib_LTLIBRARIES =
  EXTRA_LTLIBRARIES =
as well?  Extensibility-wise, this is saner -- think of several
packages like `libltdl', put together.

Come to think of, I'm not sure whether we should change these:
  DEFS
  AM_CPPFLAGS
  AM_LDFLAGS
to per-target flags -- if not, the user should add default settings of
these as well, same reasoning as above.  What do you think?
(Except for the loaders/ convenience archives and their objects, and the
libobjs, all have per-target flags already anyway, so I have a slight
preference for leaving them in, and only changing to `+=' with user
default, as with *_LTLIBRARIES.)

Definitely we should change VERSION_INFO to LTDL_VERSION_INFO for
namespace preservation.

If you agree, please consider a patch to this extent (both documentation
and implementation; with above question at your discretion) preapproved.
I'm bringing this up here and now, because if we fix this before the
release, there is no backward incompatibility involved.  :-)

> +
> address@hidden recursive
> +This build mode still requires that you use Automake, but (in contrast
> +with @samp{nonrecursive}) uses the more usual device of starting another
> address@hidden process in the @file{libltdl} subdirectory.  To use this
> +mode, you should add to your @file{configure.ac}:
> +
> address@hidden
> +LT_CONFIG_LTDL_DIR([libltdl], [recursive])
> +AM_INIT_AUTOMAKE
> +LT_WITH_LTDL
> +AC_CONFIG_FILES([libltdl/Makefile])
> address@hidden example

See above wrt. LT_CONFIG_LTDL_DIR/AM_INIT_AUTOMAKE ordering.

> +
> address@hidden
> +and to your @file{Makefile.am}:
> +
> address@hidden
> +SUBDIRS = libltdl
> address@hidden example
> +
> address@hidden subproject
> +This mode is the default unless you declare otherwise with
> address@hidden, and is the only mode supported by previous
> +releases of Libtool.  If you do not use Autoconf in the parent project,

s/Libtool/libltdl/, I believe.

> +then @samp{subproject} mode @code{libltdl} contains all the necessary
> +files to configure and build itself -- you just need to arrange for your
> +build system to call @file{libltdl/configure} with appropriate options,
> +and then run @code{make} in the @code{libltdl} subdirectory.

I would s/then //, but not sure.

> +
> +If you @emph{are} using Autoconf and Automake, then you will need to add
> +the following to your @file{configure.ac}:
> +
> address@hidden
> +LT_CONFIG_LTDL_DIR([libltdl], [subproject])
> +LT_WITH_LTDL
> address@hidden example
> +
> address@hidden
> +and to @file{Makefile.am}:
> +
> address@hidden
> +SUBDIRS = libltdl
> address@hidden example
> address@hidden table
>  @end defmac
>  
>  @defmac LT_WITH_LTDL