view release on metacpan or  search on metacpan

src/README.minGW  view on Meta::CPAN

=====================================================================
Using the FreeImage library with the MinGW Compiler Suite
=====================================================================

This file describes how to use the precompiled FreeImage library
FreeImage.dll with the MinGW port of the GNU Compiler Collection
(GCC), how to build this library from source using MinGW and how
to use this MinGW-built library with Microsoft Visual Studio.

Contents:

I. Prerequisites

1. Using the precompiled FreeImage library with MinGW

2. Building the FreeImage library with MinGW

3. Using the MinGW FreeImage library with Microsoft Visual Studio

4. Useful links


---------------------------------------------------------------------
I. Prerequisites
=====================================================================

The procedures described in this document have been developed and
tested using the following free tools:

1. MinGW GCC Version 4.4.0 (Core and C++ including required libs)
2. MinGW GNU Binutils Version 2.19.1
3. MinGW GNU Make Version 3.81-20080326-3
4. MinGW Runtime Version 3.15.2
5. MinGW API for MS-Windows Version 3.13
6. GnuWin32 Package CoreUtils Version 5.3.0 (only for building)
7. GnuWin32 Package Sed Version 4.2 (only for creating the GCC
   import library)*

* Sed is only needed to create a GCC-native import library from
  the MSVC import library FreeImage.lib. However, since MinGW now
  supports linking against MSVC lib files, this process seems to
  be obsolete. See section 1.

Basically, no version dependent capabilities are used so, this
should also work with older versions of the tools mentioned above.
Similarly, the GnuWin32 packages (which I just prefer over MSYS)
could likely be replaced by a properly installed MSYS environment.

Furthermore, the following preconditions should be met:

1. The folders 'bin' under both the MinGW and the GnuWin32
   installation directory should have been added to the PATH
   environment variable. Likely it is best adding these
   directories permanently to PATH through the System
   Properties dialog on the Control Panel.

2. The MinGW Make package only provides a 'mingw32-make.exe'
   executable. There is no alias 'make.exe'. However, make is
   preconfigured to use 'make' as the default $(MAKE) command.
   This seems to be a bug in the MinGW GNU Make distribution.
   Thus, a copy of 'mingw32-make.exe' named 'make.exe' should
   be placed into MinGW's 'bin' directory.



---------------------------------------------------------------------
1. Using the precompiled FreeImage library with MinGW
=====================================================================

When using functions from C/C++, that reside in a DLL, the linker
needs a so called import library, which specifies, how to
dynamically link these external functions during runtime. However,
different linkers use different types or formats of these import
libraries.

Since the precompiled FreeImage library was build with Microsoft
Visual Studio, in the past, some extra work was required to use it
from MinGW. An import library, that was compatible with GNU ld,
must have been created first.

However, for several MinGW versions, the GNU linker ld also
supports linking against Microsoft Visual C++ import libraries
directly. So, this effectively makes any circulating HOWTO's on
how to create a GCC-compatible import library from a MSVC lib file
more or less obsolete. Additionally, MinGW does not require the
GCC/Linux usual lib prefix for libraries, so linking with MinGW
against the precompiled FreeImage DLL is as easy as with MSVC:

1.) Open a DOS shell (run application cmd.exe)

2.) Ensure, that the 'bin' folder of MinGW is added to the PATH
    environment variable (see Prerequisites).

3.) Link directly against the supplied lib file:

    C:\>gcc -oFreeImageTest.exe FreeImageTest.c -lFreeImage

Nonetheless, for the sake of completeness, the following steps
describe how to create a native GCC import library:

1.) Open a DOS shell (run application cmd.exe)

2.) Ensure, that the 'bin' folders of both MinGW and GnuWin32 are
    added to the PATH environment variable (see Prerequisites).

3.) Create a .def file 'libfreeimage.def', that contains all symbols
    exported by the FreeImage library:

    C:\>pexports FreeImage.dll | sed "s/^_//" > libfreeimage.def

4.) Create the GCC compatible import library 'libfreeimage.a':

    C:\>dlltool --add-underscore -d libfreeimage.def -l libfreeimage.a