doc/ld-output-def.texi

   1 @node Visual Studio Compatibility
   2 @section Visual Studio Compatibility
   3 @cindex DEF files
   4 @cindex LD DEF files
   5
   6 @mindex lib-msvc-compat
   7 The @code{lib-msvc-compat} module detects whether the linker supports
   8 @code{--output-def} when building a library.  That parameter is used
   9 to generate a DEF file for a shared library (DLL).  DEF files are
  10 useful for developers that use Visual Studio to develop programs that
  11 links to your library.  See the GNU LD manual for more information.
  12
  13 There are other ways to create a DEF file, but we believe they are all
  14 sub-optimal to using @code{--output-def} during the build process.
  15 The variants we have considered include:
  16
  17 @itemize @bullet
  18 @item Use DUMPBIN /EXPORTS.
  19 This is explained in
  20 @url{https://docs.microsoft.com/en-us/cpp/build/reference/dash-exports}.
  21 The tool does not generate DEF files directly, so its output needs to
  22 be post processed manually:
  23 @smallexample
  24 $ @{ echo EXPORTS; \
  25     dumpbin /EXPORTS libfoo-0.dll | tail -n+20 | awk '@{ print $4 @}'; \
  26   @} > libfoo-0.def
  27 $ lib /def:libfoo-0.def
  28 @end smallexample
  29
  30 @item Use IMPDEF.
  31 There is a tool called IMPDEF
  32 that can generate DEF files.  However, it is not part of a standard
  33 Visual Studio installation.  Further, it is documented as being an
  34 unreliable process.
  35
  36 @item Use DLLTOOL.
  37 The dlltool is part of the MinGW suite, and thus not part of a
  38 standard Visual Studio installation.  The documentation for the IMPDEF
  39 tool claims that DLLTOOL is the wrong tool for this job.  Finally,
  40 DLLTOOL does not generate DEF files directly, so it requires
  41 post-processing of the output.
  42
  43 @end itemize
  44
  45 If you are using libtool to build your shared library, here is how to
  46 use this module.  Import @code{lib-msvc-compat} to your project, and
  47 then add the following lines to the @code{Makefile.am} that builds the
  48 library:
  49
  50 @smallexample
  51 if HAVE_LD_OUTPUT_DEF
  52 libfoo_la_LDFLAGS += -Wl,--output-def,libfoo-$(DLL_VERSION).def
  53 libfoo-$(DLL_VERSION).def: libfoo.la
  54 defexecdir = $(libdir)
  55 defexec_DATA = libfoo-$(DLL_VERSION).def
  56 DISTCLEANFILES += $(defexec_DATA)
  57 endif
  58 @end smallexample
  59
  60 The @code{DLL_VERSION} variable needs to be defined.  It should be the
  61 shared library version number used in the DLL filename.  For Windows
  62 targets you compute this value from the values you pass to Libtool's
  63 @code{-version-info}.  Assuming you have variables @code{LT_CURRENT}
  64 and @code{LT_AGE} defined for the @code{CURRENT} and @code{AGE}
  65 libtool version integers, you compute @code{DLL_VERSION} as follows:
  66
  67 @smallexample
  68 DLL_VERSION=`expr $@{LT_CURRENT@} - $@{LT_AGE@}`
  69 AC_SUBST(DLL_VERSION)
  70 @end smallexample