/
README.minGW
236 lines (167 loc) · 9.25 KB
/
README.minGW
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
=====================================================================
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
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):
C:\>make install
5.) Clean all files produced by the recent build process:
C:\>make clean
6.) Create a static FreeImage library:
C:\>set FREEIMAGE_LIBRARY_TYPE=STATIC
C:\>make
You should be able to link progams with the -lFreeImage option
after the shared library is compiled and installed. You can also
link statically against FreeImage.a from MinGW.
---------------------------------------------------------------------
3. Using the MinGW FreeImage library with Microsoft Visual Studio
=====================================================================
Since the MinGW makefile creates an import library in MSVC's lib
format, the produced shared library (DLL) can be used from both
MinGW and Microsoft Visual Studio with no further adaption. Just
link to the import library FreeImage.lib from either MinGW or
Microsoft Visual Studio.
---------------------------------------------------------------------
4. Useful links
=====================================================================
- The MinGW homepage:
http://www.mingw.org/
- The GnuWin32 homepage:
http://gnuwin32.sourceforge.net/
- The GCC homepage and online documentation:
http://gcc.gnu.org/
http://gcc.gnu.org/onlinedocs/
- The GNU Binutils homepage and online documentation:
http://www.gnu.org/software/binutils/
http://sourceware.org/binutils/docs-2.19/
- The GNU Make homepage and online documentation:
http://www.gnu.org/software/make/
http://www.gnu.org/software/make/manual/make.html