Re: static lib with libtool 1.5

[Ralf Wildenhues]

Hi Jeremie,

* Jeremie LE HEN wrote on Thu, Aug 11, 2005 at 01:45:39PM CEST:
> 
> I made the changes we talked about in our previous mails.  Here are a
> few notes :
> 
>       - I wanted to install the freshly checked-out branch-2-0 from
>         CVS, in order to give real examples of the libtool output.
>         This was really a pain.  I've ran into several obscure issues
>         that finally prevented me from having it installed.  Thus the
>         given examples come from libtool-1.5.18.
>
>         Neverthless, I strongly advice you to make this simpler,
>         because I think this may discourage number of peoples who
>         are willing to work on libtool.

Sorry.  There are a couple of open issues w.r.t installation of
branch-2-0 and (less) with HEAD.  I hope to be able to work on at least
some of them very soon.

>       - Since I have no access to a box which doesn't support shared
>         libraries.  Thus to emulate such a behaviour, I compiled
>         libtool-1.5.18 with --disabled-shared.

OK.  When you can get either of branch-2-0 and HEAD working, you can try
*-linux-dietlibc with the "diet" wrapper (my pet static-only system).
There is also a group of Cray fans that offer access to an old Y-MP
(should work with 1.5 as well) if you feel nostalgic .  :)

>       - The attached patches are against the documentation in HEAD.

Cool.

*snip*
> > >     Do you give me your approval to try to reformulate and correct this
> > >     part ?
> > 
> > Surely.  I'll happily take a patch to a better formulation.
> 
> The ``libtool_part3.1.diff'' patch corrects this part.  There is one
> point that I'm not sure about : when compiling on a system which doesn't
> support shared libraries, it seems there is only one object file
> createdi (for what I observed).

ACK.  

> My confusion comes from the fact that
> before my patch it was stated that the same object file file should be
> created twice.

You are right, the old documentation was wrong.  It described
libtool's behavior as of ages ago.

> This patch also replaces the obsolete syntax "libtool compile" with the
> new one "libtool --mode==compile" in section 3.1 examples.

Great!

*snip*
> I corrected the the section 3.2 to avoid some ambiguities in
> ``libtool_part3.2.diff''.  I also explained the consequences of
> using ``libhello.a'' instead of ``libhello.la'' when building
> a static library only.

Good!

> This patch also replaces the obsolete syntax in section 3.2.

OK.

> > >     In section 3.1, it's explicitely explained that .lo files are
> > >     control files for objects (see above), modulo some confusion in
> > >     documentation (see above, again ;-).  In the manner of this, I think
> > >     it would be worth to tell that .la files are control files for
> > >     libraries too.  In this case, I would precise that .lo and .la
> > >     files help to recall things such as -rpath and -llib accross libtool
> > >     calls.
> > 
> > I agree as well.  However, as over time the contents of the files may be
> > extended, we should not limit ourselves to what they contain.
> > Otherwise, good idea.
> 
> The previous patch adds a small paragraph at the end of section 3.2
> explaining the role of the `.la' file.

Let's see.

> I didn't take care of other section, but those clearly need the be
> changed from the obsolete syntaxe (libtool <mode>) to the new one
> (libtool --mode=<mode>).  I can't do it blindly because I don't know
> libtool well enough, but I guess a more experienced user or even a
> developper could do this in a couple of minutes.

Yep.  Will prepare a patch.

> Please feel free to make comments on my documentation patches, I will be
> glad to correct them if needed.

Only very minor issues (most of my writing are comments, not change
requests).  See below inline.

Cheers,
Ralf

> ? .libtool.texi.swp
> ? <
   ^^^

Hehe, vim user, right?  (me too)

> ? cvs.diff
> ? libtool.html
> Index: libtool.texi
> ===================================================================
> RCS file: /cvsroot/libtool/libtool/doc/libtool.texi,v
> retrieving revision 1.192
> diff -u -p -u -r1.192 libtool.texi
> --- libtool.texi      30 Apr 2005 09:30:14 -0000      1.192
> +++ libtool.texi      11 Aug 2005 11:09:22 -0000
> @@ -497,29 +497,29 @@ position-dependent code.
>  @cindex @samp{.lo} files
>  @cindex object files, library
>  Since this is a library implementation detail, libtool hides the
> -complexity of PIC compiler flags by using separate library object files
> -(that end in @samp{.lo} instead of @samp{.o}).  On systems without shared
> -libraries (or without special PIC compiler flags), these library object
> -files are identical to ``standard'' object files.
> +complexity of PIC compiler flags and uses separate library object files
> +(the PIC one lives in the @address@hidden subdirectory and the

Hmm, I'm actually not so fond of writing ".libs" instead of "$objdir".
But it happens in other places, too, changing it globally is orthogonal
to your patch.  (another thing to add to TODO list)

> +static one lives in the current directory).  On systems without shared
> +libraries (or without special PIC compiler flags), the PIC library object
> +files are not created.

The addition in parentheses is not true.  On systems where all objects
are PIC all objects might live under $objdir (with AIX this is the
case).  I do not know whether this was different with old libtool
versions.

>  To create library object files for @file{foo.c} and @file{hello.c},
>  simply invoke libtool with the standard compilation command as
>  arguments (@pxref{Compile mode}):
>  
>  @example
> -a23$ @kbd{libtool compile gcc -g -O -c foo.c}
> +a23$ @kbd{libtool --mode=compile gcc -g -O -c foo.c}
>  gcc -g -O -c foo.c -o foo.o
> -a23$ @kbd{libtool compile gcc -g -O -c hello.c}
> +a23$ @kbd{libtool --mode=compile gcc -g -O -c hello.c}
>  gcc -g -O -c hello.c -o hello.o
>  a23$
>  @end example
>  
> -Note that libtool silently creates an additional control file for each
> +Note that libtool silently creates an additional control file on each
>  @samp{compile} invocation.  The @samp{.lo} file is the libtool object,
>  which Libtool uses to determine what object file may be built into a
> -shared library, and the @samp{.o} file is a standard object file.  On
> address@hidden, only static libraries are supported so the library objects
> -look like this:
> +shared library.  On @samp{a23}, only static libraries are supported so
> +the library objects look like this:
>  
>  @example
>  # foo.lo - a libtool object file
> @@ -540,13 +540,16 @@ additional PIC object by inserting the a
>  flags into the compilation command:
>  
>  @example
> -burger$ @kbd{libtool compile gcc -g -O -c foo.c}
> +burger$ @kbd{libtool --mode=compile gcc -g -O -c foo.c}
>  mkdir @value{objdir}
>  gcc -g -O -c foo.c  -fPIC -DPIC -o @value{objdir}/foo.o
>  gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1
>  burger$
>  @end example
>  
> +Note that Libtool automatically created @address@hidden directory
> +upon its first execution, where PIC library object files will be stored.
> +
>  Since @samp{burger} supports shared libraries, and requires PIC
>  objects to build them, Libtool has compiled a PIC object this time,
>  and made a note of it in the libtool object:
> @@ -573,7 +576,7 @@ inside @samp{#ifdef PIC} for example), y
>  the @option{-no-suppress} option to libtool's compile mode:
>  
>  @example
> -burger$ @kbd{libtool compile gcc -no-suppress -g -O -c hello.c}
> +burger$ @kbd{libtool --mode=compile gcc -no-suppress -g -O -c hello.c}
>  gcc -g -O -c hello.c  -fPIC -DPIC -o @value{objdir}/hello.o
>  gcc -g -O -c hello.c -o hello.o
>  burger$

> Index: libtool.texi
> ===================================================================
> RCS file: /cvsroot/libtool/libtool/doc/libtool.texi,v
> retrieving revision 1.192
> diff -u -p -u -r1.192 libtool.texi
> --- libtool.texi      30 Apr 2005 09:30:14 -0000      1.192
> +++ libtool.texi      11 Aug 2005 11:38:49 -0000
> @@ -609,22 +612,30 @@ shared libraries, libtool simply acts as
>  
>  @cindex libtool libraries
>  @cindex @samp{.la} files
> -Again, the libtool library name differs from the standard name (it has a
> address@hidden suffix instead of a @samp{.a} suffix).  The arguments to
> +Again, the libtool control file name (@samp{.la} suffix) differs from
> +the standard library name (@samp{.a} suffix).  The arguments to
>  libtool are the same ones you would use to produce an executable named
>  @file{libhello.la} with your compiler (@pxref{Link mode}):
>  
>  @example
> -a23$ @kbd{libtool link gcc -g -O -o libhello.la foo.o hello.o}
> -libtool: cannot build libtool library `libhello.la' from non-libtool \
> -         objects
> +a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o}
> +*** Warning: Linking the shared library libhello.la against the non-libtool
> +*** objects  foo.o hello.o is not portable!
> +ar cru .libs/libhello.a 
> +ranlib .libs/libhello.a
> +creating libhello.la
> +(cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
>  a23$
>  @end example
>  
>  Aha!  Libtool caught a common address@hidden trying to build a library
> -from standard objects instead of library objects.  This doesn't matter
> -so much for static libraries, but on shared library systems, it is of
> -great importance.
> +from standard objects instead of special @samp{.lo} object files.  This
> +doesn't matter so much for static libraries, but on shared library
> +systems, it is of great importance.  (Note that you may replace
> address@hidden with @samp{libhello.a} in which case : Libtool won't

s/@samp/@file; s/ : L/ l/

I'd write "libtool" lowercase as long as the actual script may be meant
(as opposed to the package as a whole).  I have wondered whether to
put all lowercase occurrences in @command{}, but have so far refrained
from doing so consistently.  It's quite a bit of work, and I'm not
certain readability of the result would really be enhanced.

> +issue the warning any more.  But although this method works, this is
> +not intended to be used be cause it makes you lose the benefits of
> +using Libtool.)

Here upper case seems ok to me.

>  So, let's try again, this time with the library object files.  Remember
>  also that we need to add @option{-lm} to the link command line because
> @@ -638,7 +649,7 @@ specify an @code{rpath}, then libtool bu
>  archive, not a shared library (@pxref{Static libraries}).}:
>  
>  @example
> -a23$ @kbd{libtool link gcc -g -O -o libhello.la foo.lo hello.lo \
> +a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
>                  -rpath /usr/local/lib -lm}
>  ar cru @value{objdir}/libhello.a foo.o hello.o
>  ranlib @value{objdir}/libhello.a
> @@ -650,7 +661,7 @@ a23$
>  Now, let's try the same trick on the shared library platform:
>  
>  @example
> -burger$ @kbd{libtool link gcc -g -O -o libhello.la foo.lo hello.lo \
> +burger$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
>                  -rpath /usr/local/lib -lm}
>  rm -fr  @value{objdir}/libhello.a @value{objdir}/libhello.la
>  ld -Bshareable -o @value{objdir}/libhello.so.0.0 foo.lo hello.lo -lm
> @@ -671,6 +682,11 @@ subdirectory, rather than the current di
>  make it easier to clean up the build directory, and to help ensure that
>  other programs fail horribly if you accidentally forget to use libtool
>  when you should.
> +
> +Again, you may want to have a look at the @samp{.la} file in order
> +to see what Libtool stores in it.  In particular, you will see that
> +Libtool uses this file to remember @samp{-rpath} argument as well as
> +the dependancy on the math library (@samp{-lm}).

maybe better (note also the typo):

Libtool uses this file to remember the destination directory for the
library (the argument to @option{-rpath}) as well as the dependency
on the math library (@samp{-lm}).

>  @node Linking executables
>  @section Linking executables