Re: documentation comments

[Ralf Wildenhues]

Hi Ross,

First, thanks for your reports (and also your long reply to my deplibs
RFC; I'm afraid I won't have too much time working on that for a while,
but eventually someone will get to it).

* Ross Boylan wrote on Thu, Dec 09, 2004 at 11:02:06PM CET:
> It would be good if the documentation (I'm looking at 1.5.6.) were
> clearer on the setup of libtool and its requirements.  In previous
> discussion on this list, I've learned that autoconf is required.  I've
> just discovered a little more is necessary too (at least install-sh,
> which can be produced by automake).

automake should not be required.  This is a bug, I think.
I don't know if I can attack this right away, please don't hesitate
to ping us again in a couple of weeks on this issue if we forget to look
at it.

> Also, it could be clearer that you don't actually distribute a libtool
> with your package, but have it generated on the build machine by
> configure.  In particular, I found this confusing:
> ----------------------------------------------------
> 5.3 Configuring libtool
> =======================
> 
*snip quoted content*
> -------------------------------------------------------------

> "when you distribute libtool with your own packages" meant, to me, that
> the file libtool would be part of my package.  The line 'libtool must be
> "configured" before it can be used' also suggested there was some file
> that configure acted upon, rather than one that it created.  The
> statement that "Libtool adds its own tests to your 'configure' script"
> similarly suggests that libtool exists before configure (I realize this
> is sort of true, though it applies to the maintainer machine).  

Good point!  How do you like this instead:

5.3 Configuring libtool
=======================

Libtool requires intimate knowledge of your compiler suite and operating
system in order to be able to create shared libraries and link against
them properly.  When you install the libtool distribution, a
system-specific libtool script is installed into your binary directory.

   However, it is also possible to set up your software package in such
a way that everything required for libtool to work is distributed along
with it (*note Distributing::).  In this case, it is not the `libtool'
script which is distributed along with your package, but the machinery
to generate this script for the operating system and compiler used to
compile your package eventually, since now the knowledge for all
compiler suites and all operating systems needs to be wrapped up.

   This machinery reuses the GNU "configure" approach: `configure' runs
a number of tests for system features, then generates the `Makefile's
(and possibly a `config.h' header file), after which you can run `make'
and build the package.  For libtool, a few more tests are added to your
`configure' script in order to generate a libtool script for the
installer's host machine.  The generation of the `libtool' script then
happens as well at the end of the `configure' run.


Is that any clearer?

> Now, back to the issue of required programs and packages.....
> 
> Documentation section 5.4, Including libtool in your package,
> lists a bunch of required files, and recommends running libtoolize.  (It
> also does say not to include libtool itself).  Having done all this, I
> put the project on a new system and ran configure.  It failed because
> install-sh was absent.

We need a testcase for this.  And a fix.

> So at least that file is necessary.  I did 
>    automake --foreign --add-missing
> which added 3 files (though I did get some complaints from it).  Things
> then worked.

This should not be necessary.  I think.

> Finally, section 5.1, Writing `Makefile' rules for libtool, does say "If
> you want to use libtool in a regular `Makefile' (or `Makefile.in'), you
> are on your own."  Since I am trying to use libtool without automake,
> this could be taken as a general warning and disclaimer.  Even if that
> was the intent, it would be nice to add the information mentioned above
> for those who aren't using automake.

I would like to address this in a separate mail, sometime later, ok?
Maybe together with the other bug you mentioned above.

Regards,
Ralf