ffmpeg update

[casparcg] / FreeImage / README.minGW

=====================================================================\r
Using the FreeImage library with the MinGW Compiler Suite\r
=====================================================================\r
\r
This file describes how to use the precompiled FreeImage library\r
FreeImage.dll with the MinGW port of the GNU Compiler Collection\r
(GCC), how to build this library from source using MinGW and how\r
to use this MinGW-built library with Microsoft Visual Studio.\r
\r
Contents:\r
\r
I. Prerequisites\r
\r
1. Using the precompiled FreeImage library with MinGW\r
\r
2. Building the FreeImage library with MinGW\r
\r
3. Using the MinGW FreeImage library with Microsoft Visual Studio\r
\r
4. Useful links\r
\r
\r
---------------------------------------------------------------------\r
I. Prerequisites\r
=====================================================================\r
\r
The procedures described in this document have been developed and\r
tested using the following free tools:\r
\r
1. MinGW GCC Version 4.4.0 (Core and C++ including required libs)\r
2. MinGW GNU Binutils Version 2.19.1\r
3. MinGW GNU Make Version 3.81-20080326-3\r
4. MinGW Runtime Version 3.15.2\r
5. MinGW API for MS-Windows Version 3.13\r
6. GnuWin32 Package CoreUtils Version 5.3.0 (only for building)\r
7. GnuWin32 Package Sed Version 4.2 (only for creating the GCC\r
   import library)*\r
\r
* Sed is only needed to create a GCC-native import library from\r
  the MSVC import library FreeImage.lib. However, since MinGW now\r
  supports linking against MSVC lib files, this process seems to\r
  be obsolete. See section 1.\r
\r
Basically, no version dependent capabilities are used so, this\r
should also work with older versions of the tools mentioned above.\r
Similarly, the GnuWin32 packages (which I just prefer over MSYS)\r
could likely be replaced by a properly installed MSYS environment.\r
\r
Furthermore, the following preconditions should be met:\r
\r
1. The folders 'bin' under both the MinGW and the GnuWin32\r
   installation directory should have been added to the PATH\r
   environment variable. Likely it is best adding these\r
   directories permanently to PATH through the System\r
   Properties dialog on the Control Panel.\r
\r
2. The MinGW Make package only provides a 'mingw32-make.exe'\r
   executable. There is no alias 'make.exe'. However, make is\r
   preconfigured to use 'make' as the default $(MAKE) command.\r
   This seems to be a bug in the MinGW GNU Make distribution.\r
   Thus, a copy of 'mingw32-make.exe' named 'make.exe' should\r
   be placed into MinGW's 'bin' directory.\r
\r
\r
\r
---------------------------------------------------------------------\r
1. Using the precompiled FreeImage library with MinGW\r
=====================================================================\r
\r
When using functions from C/C++, that reside in a DLL, the linker\r
needs a so called import library, which specifies, how to\r
dynamically link these external functions during runtime. However,\r
different linkers use different types or formats of these import\r
libraries.\r
\r
Since the precompiled FreeImage library was build with Microsoft\r
Visual Studio, in the past, some extra work was required to use it\r
from MinGW. An import library, that was compatible with GNU ld,\r
must have been created first.\r
\r
However, for several MinGW versions, the GNU linker ld also\r
supports linking against Microsoft Visual C++ import libraries\r
directly. So, this effectively makes any circulating HOWTO's on\r
how to create a GCC-compatible import library from a MSVC lib file\r
more or less obsolete. Additionally, MinGW does not require the\r
GCC/Linux usual lib prefix for libraries, so linking with MinGW\r
against the precompiled FreeImage DLL is as easy as with MSVC:\r
\r
1.) Open a DOS shell (run application cmd.exe)\r
\r
2.) Ensure, that the 'bin' folder of MinGW is added to the PATH\r
    environment variable (see Prerequisites).\r
\r
3.) Link directly against the supplied lib file:\r
\r
    C:\>gcc -oFreeImageTest.exe FreeImageTest.c -lFreeImage\r
\r
Nonetheless, for the sake of completeness, the following steps\r
describe how to create a native GCC import library:\r
\r
1.) Open a DOS shell (run application cmd.exe)\r
\r
2.) Ensure, that the 'bin' folders of both MinGW and GnuWin32 are\r
    added to the PATH environment variable (see Prerequisites).\r
\r
3.) Create a .def file 'libfreeimage.def', that contains all symbols\r
    exported by the FreeImage library:\r
\r
    C:\>pexports FreeImage.dll | sed "s/^_//" > libfreeimage.def\r
\r
4.) Create the GCC compatible import library 'libfreeimage.a':\r
\r
    C:\>dlltool --add-underscore -d libfreeimage.def -l libfreeimage.a\r
\r
5.) Use this library to link against with GCC:\r
\r
    C:\>gcc -oFreeImageTest.exe FreeImageTest.c -lfreeimage\r
\r
\r
\r
---------------------------------------------------------------------\r
2. Building the FreeImage library with MinGW\r
=====================================================================\r
\r
You *do not* need to have any other third party library (like\r
libjpeg, libpng, libtiff, libmng and zlib and others) installed on\r
your system in order to compile and use the library. FreeImage uses\r
its own versions of these libraries. This way, you can be sure that\r
FreeImage will always use the latest and properly tested versions\r
of of these third party libraries.\r
\r
In order to build the FreeImage library under Windows with MinGW\r
(GCC), ensure that all the prerequisites mentioned above are met.\r
The MinGW makefile aims to build a Windows DLL, that differs as\r
least as possible from the precompiled library that comes with the\r
FreeImage distribution. Thus, the build process also includes the\r
DLL version resource as well as the __stdcall attribute for all the\r
exported functions, including the MSVC-like function decorations\r
_FuncName@nn.\r
\r
When building the FreeImage DLL, of course, an import library is\r
generated, too. However, this input library is not in GCC's native\r
format, but in MSVC lib format, which makes it usable from both\r
MinGW and Microsoft Visual Studio with no further processing.\r
\r
The MinGW makefile can also be used to build a static library.\r
However, due to the different function export attributes needed\r
for both the dynamic and the shared library (DLL), this requires\r
a separate invocation of make, which in turn needs to rebuild every\r
source file after switching from dynamic to static and vice versa.\r
So, a 'make clean' is required each time, the library type is\r
changed.\r
\r
The type of library to build is specified by a variable named\r
FREEIMAGE_LIBRARY_TYPE, which may either be set directly in the\r
Makefile.mingw near line 18 or may be specified as an environment\r
variable. This variable may either take SHARED or STATIC to build\r
a dynamic link library (DLL) or a static library respectively.\r
Since this value is used to dynamically form the actual make target\r
internally, only uppercase values are valid. Defaults to SHARED.\r
\r
The MinGW makefile also supports the 'install' target. However,\r
this only copies the FreeImage dynamic link library (DLL) from the\r
Dist folder into the %SystemRoot%\system32 folder. So, invoking this\r
target only makes sense, if the DLL has been built before.\r
\r
Since there is neither a common system wide 'include' nor a 'lib'\r
directory available under Windows, the FreeImage header file\r
FreeImage.h as well as both the static library and the DLL import\r
library FreeImage.lib just remain in the 'Dist' folder.\r
\r
The following procedure creates the FreeImage dynamic link library\r
(DLL) from the sources, installs it and also creates a static\r
FreeImage library:\r
\r
1.) Open a DOS shell (run application cmd.exe)\r
\r
2.) Ensure, that the 'bin' folders of both MinGW and GnuWin32 are\r
    added to the PATH environment variable (see Prerequisites).\r
\r
3.) Create the FreeImage dynamic link library (DLL):\r
\r
    C:\>make\r
\r
4.) Install the FreeImage dynamic link library (DLL):\r
\r
    C:\>make install\r
\r
5.) Clean all files produced by the recent build process:\r
\r
    C:\>make clean\r
\r
6.) Create a static FreeImage library:\r
\r
    C:\>set FREEIMAGE_LIBRARY_TYPE=STATIC\r
    C:\>make\r
\r
You should be able to link progams with the -lFreeImage option\r
after the shared library is compiled and installed. You can also\r
link statically against FreeImage.a from MinGW.\r
\r
\r
\r
---------------------------------------------------------------------\r
3. Using the MinGW FreeImage library with Microsoft Visual Studio\r
=====================================================================\r
\r
Since the MinGW makefile creates an import library in MSVC's lib\r
format, the produced shared library (DLL) can be used from both\r
MinGW and Microsoft Visual Studio with no further adaption. Just\r
link to the import library FreeImage.lib from either MinGW or\r
Microsoft Visual Studio.\r
\r
\r
\r
---------------------------------------------------------------------\r
4. Useful links\r
=====================================================================\r
\r
- The MinGW homepage:\r
     http://www.mingw.org/\r
\r
- The GnuWin32 homepage:\r
     http://gnuwin32.sourceforge.net/\r
\r
- The GCC homepage and online documentation:\r
     http://gcc.gnu.org/\r
     http://gcc.gnu.org/onlinedocs/\r
\r
- The GNU Binutils homepage and online documentation:\r
     http://www.gnu.org/software/binutils/\r
     http://sourceware.org/binutils/docs-2.19/\r
\r
- The GNU Make homepage and online documentation:\r
     http://www.gnu.org/software/make/\r
     http://www.gnu.org/software/make/manual/make.html\r