Re: preparing for 1.5.24

[Ralf Wildenhues]

Hi Charles,

* Charles Wilson wrote on Wed, Apr 25, 2007 at 05:38:49AM CEST:
> Ralf Wildenhues wrote:
>
>> Thanks also for the documentation suggestion.  Slightly rewritten
>> suggestion to come up.
>
> Ping? [antecedent reposted below]

Sigh.  I had hoped to have enough time to work on this.  Alas, I better
just post my thoughts.  Apologies for being the eye of the needle here
(can you use the phrase this way in English?).

First, I think this is a bit ad hoc here: the dllexport/dllimport issue,
or more generally, w32-specific issues (although as I understand it's
not /strictly/ w32-specific), don't start with using libltdl.  As such,
I think they deserves its own chapter in the manual, and then the
libltdl handling can refer to it, in shortened form.  Ideally, all the
gory details of how you can have several deplibs, some static some
shared, and currently need to define a macro for each based on that (but
maybe libtool can help there in the future to automatize that?).
AC_LIBTOOL_WIN32_DLL could refer to this section then.

I think some of this stuff has been discussed at length on the libtool
lists; I assume you were one of the people involved.

Even cooler would be to take into account the differences for when we
add support for MSVC, wgcc, ...

> Around line 3546 [probably 4476, now] in libtool.texi, something like:
>
> --------------------------%<----------------------------
> @emph{Win32 specific}

FWIW, I don't like this way of putting keywords much.  It should be a
heading, or part of the surrounding sentence.

> When building a DLL on windows (MinGW,Cygwin) that 

Let's not speak of a library as a DLL, except where we explain what a
DLL is, and except the strictly w32-specific parts of the manual.  We
should strive to use coherent names for things, here: shared library.
Just like you use "convenience archive" within the same sentence.

> uses @code{libltdl} as a convenience archive, there are some issues with 
> symbol decoration that must be carefully managed.  You must do one of the 
> following, within the code and/or build machinery of your library:

> @enumerate 1
> @item explicitly mark as @code{declspec(dllexport)} all symbols in your 
> library that should be exported when building your library's source code.  
> However, these symbols should @emph{not} be marked 
> @code{declspec(dllexport)} when building @emph{clients} of your library -- 
> instead, the symbols should be marked @code{declspec(dllimport)}. This 
> procedure will require careful macro design within your library's public 
> header files.  An example of this may be found in @file{zlib.h} from the 
> zlib distribution @url{http://www.zlib.net/}.

Let's rather not refer to an external source here: they could change,
the link is more than two links away from what the user really needs to
see when doing this, and zlib isn't GNU software (it's free, so there's
no real issue here).

Rather, a small, self-contained example would be great.  Ideally, that
example would be identical to a test in the new testsuite, so that we're
kept honest in that it actually works as expected.

> @item use the (win32-specific) linker option @code{-Xlinker 
> --export-all-symbols}.  This will restore the expected "auto-export" 
> behavior of the GNU linker on windows.  However, the 
> @code{--export-all-symbols} option is specific to the GNU linker's i386 PE 
> target -- @code{ld} for other targets will not recognize the option.  
> Therefore, using this option will require careful coding in your library's 
> @file{Makefile.am} and @file{configure.ac}.  For example:
>
> configure.ac:
> @example
> ...
> case $host_os in
> cygwin* | mingw* | pw32*)

This doesn't account for specifity to GNU binutils ld.  $with_gnu_ld
should help here, bugs in its setting notwithstanding.

>   RESTORE_AUTOEXPORT="-Xlinker --export-all-symbols"
[...]

Cheers, and thanks for all your work,
Ralf