1 The FreeType Windows Compilation HowTo
6 I. Building the library
10 II. Building other parts of the package
12 2. Other contributions
13 III. Special issues of 16-bit Windows
20 This file describes the compilation of the FreeType package on a
21 Windows system. It comes with Makefiles for the following
24 - gcc/CygWin32 and gcc/MinGW32 with GNU make (32 bit)
26 - cl with nmake (16-bit and 32-bit Microsoft C and Visual C++)
28 - bcc with make (16-bit and 32-bit Borland C++ and also Borland
31 Throughout this file, we use `winXX' if it applies indifferently to
32 both 16-bit and 32-bit versions. You should replace it with win16
33 resp. win32, as applicable.
37 You are advised to jump to section II.1 if you want to run the
38 FreeType test/demo programs as quick as possible.
42 I. Building the library
43 =======================
49 The easiest way to compile the library on Windows is to go to the
50 directory `freetype/lib'. Then type, depending on your compiler:
52 gcc: make -f arch/win32/Makefile.gcc
54 cl: nmake /f arch\win16\Makefile.MS (for C/C++ 7)
55 cl: nmake /f arch\win16\Makefile.VC (for VC++ 16bit)
56 cl: nmake /f arch\win32\Makefile.CL (for VC++ 32bit)
58 bcc: make -farch/win16/Makefile.BC
59 bcc32: make -farch/win32/Makefile.BC
61 This should build the `libttf.a' or `libttf.lib' library files.
62 Of course, this assumes that your compiler is regularly installed.
64 You can also use the following targets:
66 clean - Cleans all intermediate object files created during
67 compilation. Keeps all library and executables in
70 distclean - Cleans everything, leaving the directories as they
71 were before the compilation.
73 debug - Makes a development version of the library. Only
74 useful for FreeType developers and hackers.
76 Note that you can also select to use the `debugging' flags for
77 your compiler (instead of the `optimizing' ones), by defining
78 the `DEBUG' symbol, like in
80 nmake /f arch\win32\Makefile.CL DEBUG=1
81 make -farch/winXX/Makefile.BC /DDEBUG
84 Doing so will automatically select the debug target instead of
87 For 16-bit compilers, you can also try to define the `BIGFONTS'
88 symbol, enabling the use of the `huge pointers' needed to handle
89 some big fonts. More on this at the end of this file.
91 Another way to compile the library is to use the IDE provided with
92 the following compilers: Borland C++ 5.0, Visual C++ 4.0, and
93 Visual C++ 5.0. The project/workspace files can be found in the
94 `freetype/lib/arch/win32' directory:
96 freetype.ide for Borland C++ 4.0 and 5.0 (and perhaps 4.5)
98 freetype.dsp project and workspace files for
99 freetype.dsw Visual C++ 5.0
101 freetype.mdp project and makefile files for
102 freetype.mak Visual C++ 4.0
104 They generate a static library, which contain the core engine as a
105 single object file, as well as all standard extensions.
109 - You may need to update the include paths in the Borland C++
110 workspace settings. The current one looks in the directory
111 "c:\Program Files\Borland\BC 5.0\Include" for include files.
113 - Take care that some compilers may overwrite these files when
114 generating the library (e.g. Borland C++ creates its own
115 `freetype.mdp' file, which isn't a Visual C++ project during
118 This is only important if you try to compile the lib with
121 We gladly accept project files for other compilers.
124 2. Manual compilation
125 ---------------------
127 Here are explained the steps that are required to compile the
128 FreeType _library_ (and only this one) by hand.
130 Unlike previous versions, FreeType 1.1 and above can be compiled
131 in two modes, called `debug mode' and `single object mode'.
133 Debug mode is simply the normal way of compiling C programs, i.e.,
134 each `*.c' file is compiled into an individual `*.obj' object
135 file, and all of them are linked together into an archive (i.e.,
138 Single object mode is slightly different: All C files are included
139 in a single source during compilation, resulting in a single final
140 object file for the core library. This has the advantage of
141 letting optimizing compilers do more global work, as well as
142 getting rid of all external which are used solely for the purpose
143 of components interfacing.
145 In both modes, you need to include the following paths to your
146 makefile/command line:
148 the location of all `tt*.[hc]' files
149 the location of system-specific files
151 For example, if you are compiling from the `freetype/lib'
152 directory, you can type for debug mode something like
154 gcc -c -I. -Iarch/win32 tt*.c
156 to compile all required files into object ones. Then assemble
157 them in a library with `ar', `lib', or `tlib'.
159 In single object mode, you only need to compile the file named
160 `freetype.c' which is located in `freetype/lib/arch/winXX'. From
161 the same directory as before, one would type
163 gcc -c -I. -Iarch/win32 arch/win32/freetype.c
165 You can also compile the extensions located in
166 `freetype/lib/extend' separately from the base engine. You will
167 need to include the same paths as before, though; be sure to add
168 the path to the `extend' directory, like in
170 gcc -c -I. -Iarch/win32 -Iextend extend/*.c
176 The easiest way to build the library as a DLL is also to use the
177 Makefiles we provide! Go to the directory `freetype/lib', then
178 type, depending on your compiler:
180 gcc: (not yet supported)
182 cl: nmake /f arch\win16\Makefile.VC DLL=1 dll (16bit)
183 cl: nmake /f arch\win32\Makefile.CL DLL=1 dll (32bit)
185 bcc: make -farch/win16/Makefile.BC -DDLL dll
186 bcc32: make -farch/win32/Makefile.BC -DDLL dll
188 This should build `ft13_XX.dll' (`13' for version 1.3, `XX' is
189 either 16 or 32), and the `libttf.lib' library file.
191 You can also use the following target:
193 install - Install the DLL `ft13_XX.dll' to your system directory
194 (`C:\WINDOWS' by default). You can override the
195 directory by specifying the name of the directory:
197 make -farch/winXX/Makefile.BC /DINSTALL_DIR=C:\TESTDLL install
198 nmake /f arch\win32\Makefile.CL INSTALL_DIR=D:\WINNT install
200 Note that you can also select to use the `debugging' flags for
201 your compiler (instead of the `optimizing' ones), by defining
202 the `DEBUG' symbol, like in
204 nmake /f arch\win16\Makefile.VC DEBUG=1 DLL=1 dll
205 make -farch/winXX/Makefile.BC /DDEBUG /DDLL dll
208 Another way to build to DLL with Visual C++ is to use a special
209 Makefile that does exactly that, without relying on any settings.
211 With VC++ 6.0, just type while in the `freetype/lib/arch/win32'
218 For other versions, modify the $(TOOLS32) variable to point to the
219 directory where the build tools are. No need to set any
220 environment variables.
226 `char' is always `signed char' in the sources!
228 `ttconfig.h' relies heavily on a file called `ft_conf.h' that
229 contains information related to the target platform, located in
230 the `freetype/lib/arch/winXX/' directory. Depending on your
231 compiler, you may need to slightly edit it.
233 We use gcc as our reference compiler for warnings. This means
234 that we use the `-ansi -pedantic -Wall' flags and try to get rid
235 of warnings in this situation. If you are compiling with another
236 compiler, you may encounter warnings, not errors. Note that the
237 Borland compilers seem to produce lots of irrelevant warnings
238 (like `potential loss of precision').
242 II. Building other parts of the package
243 =======================================
249 All test programs are located in `freetype/test'. Most of them
250 use a tiny graphics sub-system which is simply used to display
251 bitmaps and pixmaps on a variety of platforms. The Windows
252 version is a very basic one that only displays a small graphic
253 windows in addition to the console where the flow of messages
256 To compile them, you must be in the `freetype/test' directory and
257 invoke the makefile in arch/winXX. For example:
259 nmake -f arch\os2\Makefile.VC
263 This will automatically invoke the library makefile for you!
267 For now, the graphical test programs only run on the following
268 platforms: Unix, OS/2, Dos, Amiga, and Windows.
270 The library, being pure ANSI-C, can be used on any system to
271 generate bitmaps and pixmaps.
274 2. Other contributions
275 ----------------------
277 You may find some other contributions to the FreeType project in
278 the `freetype/contrib' directory. Each of these programs should
279 have its own Makefiles and documentations. Also check their
280 licenses, as the programs are not necessarily distributed under
283 Most of these contributions are targeted to Unix. You are invited
284 to port them to Windows, and then contribute your improvements.
288 III. Special issues of 16-bit Windows
289 =====================================
291 As usual, 16-bit Windows have some limitations.
293 First, and mainly, only the large model is usable. The small and
294 medium models are not usable, because the library uses more than
295 64kByte of data; and the compact model is unusable as well, since
296 the code of the library itself is slightly less than 64kByte, thus
297 leaving very small place for the real work. The net effect of
298 that limitation is that performances are not very impressive, to
299 say the least (32-bit DOS extenders perform usually three-time
302 Even with the large model, the rasterizer is still limited in
303 size, particularly with pixmaps (that is, with anti-aliasing gray
306 The test programs rely on a tiny graphical driver that mimics the
307 ones available on other platforms. It has some peculiarities.
308 First, as the test programs need a `console', the programs should
309 linked with some emulation of that concept. We used successfully
310 Borland EasyWin and Microsoft QuickWin for this purpose. Then,
311 the graphics window that displays the bitmaps incur the usual
312 64kByte limit: The size of the window is quite tiny, particularly
313 when displaying `gray-level' bitmaps (the size is then 320x200,
314 but contrary to full-screen MS-DOS the pixels are not magnified).
315 Ultimately, no efforts have been done to accomodate the colors of
316 the screen: As a result, displaying gray bitmaps in 256-color mode
317 uses only 4 levels of gray (instead of 5 rendered by the library).
319 Another annoying limitation exists with some East Asian fonts that
320 have 16,383 glyphs or more, since an internal table then
321 overflows. We tried to overcome this using so-called `huge
322 pointers', but then good support for these in the run-time library
323 is needed. To enable huge pointers, try defining the `BIGFONTS'
324 symbol with the makefile, like
326 nmake /f arch\win16\makefile.VC BIGFONTS=1
327 make -farch/win16/makefile.BC /DBIGFONTS
330 The makefiles for both Microsoft and Borland compilers depend on a
331 special file, arch/winXX/depend.win, which is built by a Unix
332 script named `makedep'. You may consider editing it if you
333 heavily modify the source files; or better yet, re-run the script,
334 using any clone of the Bourne shell and gcc, the GNU compiler,
339 in both the `lib' and the `test' directories.
344 --- end of windows.txt ---