view release on metacpan or  search on metacpan

src/README.minGW  view on Meta::CPAN

---------------------------------------------------------------------
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

5.) Use this library to link against with GCC:

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



---------------------------------------------------------------------
2. Building the FreeImage library with MinGW
=====================================================================

You *do not* need to have any other third party library (like
libjpeg, libpng, libtiff, libmng and zlib and others) installed on
your system in order to compile and use the library. FreeImage uses
its own versions of these libraries. This way, you can be sure that
FreeImage will always use the latest and properly tested versions
of of these third party libraries.

In order to build the FreeImage library under Windows with MinGW
(GCC), ensure that all the prerequisites mentioned above are met.
The MinGW makefile aims to build a Windows DLL, that differs as
least as possible from the precompiled library that comes with the
FreeImage distribution. Thus, the build process also includes the
DLL version resource as well as the __stdcall attribute for all the
exported functions, including the MSVC-like function decorations
_FuncName@nn.

When building the FreeImage DLL, of course, an import library is
generated, too. However, this input library is not in GCC's native
format, but in MSVC lib format, which makes it usable from both
MinGW and Microsoft Visual Studio with no further processing.

The MinGW makefile can also be used to build a static library.
However, due to the different function export attributes needed
for both the dynamic and the shared library (DLL), this requires
a separate invocation of make, which in turn needs to rebuild every
source file after switching from dynamic to static and vice versa.
So, a 'make clean' is required each time, the library type is
changed.

The type of library to build is specified by a variable named
FREEIMAGE_LIBRARY_TYPE, which may either be set directly in the
Makefile.mingw near line 18 or may be specified as an environment
variable. This variable may either take SHARED or STATIC to build
a dynamic link library (DLL) or a static library respectively.
Since this value is used to dynamically form the actual make target
internally, only uppercase values are valid. Defaults to SHARED.

The MinGW makefile also supports the 'install' target. However,
this only copies the FreeImage dynamic link library (DLL) from the
Dist folder into the %SystemRoot%\system32 folder. So, invoking this
target only makes sense, if the DLL has been built before.

Since there is neither a common system wide 'include' nor a 'lib'
directory available under Windows, the FreeImage header file
FreeImage.h as well as both the static library and the DLL import
library FreeImage.lib just remain in the 'Dist' folder.

The following procedure creates the FreeImage dynamic link library
(DLL) from the sources, installs it and also creates a static
FreeImage 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 the FreeImage dynamic link library (DLL):

    C:\>make

4.) Install the FreeImage dynamic link library (DLL):