The FreeType Windows Compilation HowTo Contents Introduction I. Building the library 1. Quick Compilation 2. Manual compilation 3. Notes II. Building other parts of the package 1. Test programs 2. Other contributions III. Special issues of 16-bit Windows Introduction ============ This file describes the compilation of the FreeType package on a Windows system. It comes with Makefiles for the following compilers: - gcc/CygWin32 and gcc/MinGW32 with GNU make (32 bit) - cl with nmake (16-bit and 32-bit Microsoft C and Visual C++) - bcc with make (16-bit and 32-bit Borland C++ and also Borland C++ builder) Throughout this file, we use `winXX' if it applies indifferently to both 16-bit and 32-bit versions. You should replace it with win16 resp. win32, as applicable. NOTE: You are advised to jump to section II.1 if you want to run the FreeType test/demo programs as quick as possible. I. Building the library ======================= 1. Quick Compilation -------------------- The easiest way to compile the library on Windows is to go to the directory `freetype/lib'. Then type, depending on your compiler: gcc: make -f arch/win32/Makefile.gcc cl: nmake /f arch\win16\Makefile.MS (for C/C++ 7) cl: nmake /f arch\win16\Makefile.VC (for VC++ 16bit) cl: nmake /f arch\win32\Makefile.CL (for VC++ 32bit) bcc: make -farch/win16/Makefile.BC bcc32: make -farch/win32/Makefile.BC This should build the `libttf.a' or `libttf.lib' library files. Of course, this assumes that your compiler is regularly installed. You can also use the following targets: clean - Cleans all intermediate object files created during compilation. Keeps all library and executables in place. distclean - Cleans everything, leaving the directories as they were before the compilation. debug - Makes a development version of the library. Only useful for FreeType developers and hackers. Note that you can also select to use the `debugging' flags for your compiler (instead of the `optimizing' ones), by defining the `DEBUG' symbol, like in nmake /f arch\win32\Makefile.CL DEBUG=1 make -farch/winXX/Makefile.BC /DDEBUG etc. Doing so will automatically select the debug target instead of the normal mode. For 16-bit compilers, you can also try to define the `BIGFONTS' symbol, enabling the use of the `huge pointers' needed to handle some big fonts. More on this at the end of this file. Another way to compile the library is to use the IDE provided with the following compilers: Borland C++ 5.0, Visual C++ 4.0, and Visual C++ 5.0. The project/workspace files can be found in the `freetype/lib/arch/win32' directory: freetype.ide for Borland C++ 4.0 and 5.0 (and perhaps 4.5) freetype.dsp project and workspace files for freetype.dsw Visual C++ 5.0 freetype.mdp project and makefile files for freetype.mak Visual C++ 4.0 They generate a static library, which contain the core engine as a single object file, as well as all standard extensions. Notes: - You may need to update the include paths in the Borland C++ workspace settings. The current one looks in the directory "c:\Program Files\Borland\BC 5.0\Include" for include files. - Take care that some compilers may overwrite these files when generating the library (e.g. Borland C++ creates its own `freetype.mdp' file, which isn't a Visual C++ project during compilation). This is only important if you try to compile the lib with several compilers. We gladly accept project files for other compilers. 2. Manual compilation --------------------- Here are explained the steps that are required to compile the FreeType _library_ (and only this one) by hand. Unlike previous versions, FreeType 1.1 and above can be compiled in two modes, called `debug mode' and `single object mode'. Debug mode is simply the normal way of compiling C programs, i.e., each `*.c' file is compiled into an individual `*.obj' object file, and all of them are linked together into an archive (i.e., `*.lib' library). Single object mode is slightly different: All C files are included in a single source during compilation, resulting in a single final object file for the core library. This has the advantage of letting optimizing compilers do more global work, as well as getting rid of all external which are used solely for the purpose of components interfacing. In both modes, you need to include the following paths to your makefile/command line: the location of all `tt*.[hc]' files the location of system-specific files For example, if you are compiling from the `freetype/lib' directory, you can type for debug mode something like gcc -c -I. -Iarch/win32 tt*.c to compile all required files into object ones. Then assemble them in a library with `ar', `lib', or `tlib'. In single object mode, you only need to compile the file named `freetype.c' which is located in `freetype/lib/arch/winXX'. From the same directory as before, one would type gcc -c -I. -Iarch/win32 arch/win32/freetype.c You can also compile the extensions located in `freetype/lib/extend' separately from the base engine. You will need to include the same paths as before, though; be sure to add the path to the `extend' directory, like in gcc -c -I. -Iarch/win32 -Iextend extend/*.c 3. Building a DLL ----------------- The easiest way to build the library as a DLL is also to use the Makefiles we provide! Go to the directory `freetype/lib', then type, depending on your compiler: gcc: (not yet supported) cl: nmake /f arch\win16\Makefile.VC DLL=1 dll (16bit) cl: nmake /f arch\win32\Makefile.CL DLL=1 dll (32bit) bcc: make -farch/win16/Makefile.BC -DDLL dll bcc32: make -farch/win32/Makefile.BC -DDLL dll This should build `ft13_XX.dll' (`13' for version 1.3, `XX' is either 16 or 32), and the `libttf.lib' library file. You can also use the following target: install - Install the DLL `ft13_XX.dll' to your system directory (`C:\WINDOWS' by default). You can override the directory by specifying the name of the directory: make -farch/winXX/Makefile.BC /DINSTALL_DIR=C:\TESTDLL install nmake /f arch\win32\Makefile.CL INSTALL_DIR=D:\WINNT install Note that you can also select to use the `debugging' flags for your compiler (instead of the `optimizing' ones), by defining the `DEBUG' symbol, like in nmake /f arch\win16\Makefile.VC DEBUG=1 DLL=1 dll make -farch/winXX/Makefile.BC /DDEBUG /DDLL dll etc. Another way to build to DLL with Visual C++ is to use a special Makefile that does exactly that, without relying on any settings. With VC++ 6.0, just type while in the `freetype/lib/arch/win32' directory: nmake /f makefile.vc on the command line. For other versions, modify the $(TOOLS32) variable to point to the directory where the build tools are. No need to set any environment variables. 4. Notes -------- `char' is always `signed char' in the sources! `ttconfig.h' relies heavily on a file called `ft_conf.h' that contains information related to the target platform, located in the `freetype/lib/arch/winXX/' directory. Depending on your compiler, you may need to slightly edit it. We use gcc as our reference compiler for warnings. This means that we use the `-ansi -pedantic -Wall' flags and try to get rid of warnings in this situation. If you are compiling with another compiler, you may encounter warnings, not errors. Note that the Borland compilers seem to produce lots of irrelevant warnings (like `potential loss of precision'). II. Building other parts of the package ======================================= 1. Test programs ---------------- All test programs are located in `freetype/test'. Most of them use a tiny graphics sub-system which is simply used to display bitmaps and pixmaps on a variety of platforms. The Windows version is a very basic one that only displays a small graphic windows in addition to the console where the flow of messages still goes. To compile them, you must be in the `freetype/test' directory and invoke the makefile in arch/winXX. For example: nmake -f arch\os2\Makefile.VC NOTE 1: This will automatically invoke the library makefile for you! NOTE 2: For now, the graphical test programs only run on the following platforms: Unix, OS/2, Dos, Amiga, and Windows. The library, being pure ANSI-C, can be used on any system to generate bitmaps and pixmaps. 2. Other contributions ---------------------- You may find some other contributions to the FreeType project in the `freetype/contrib' directory. Each of these programs should have its own Makefiles and documentations. Also check their licenses, as the programs are not necessarily distributed under the FreeType one. Most of these contributions are targeted to Unix. You are invited to port them to Windows, and then contribute your improvements. III. Special issues of 16-bit Windows ===================================== As usual, 16-bit Windows have some limitations. First, and mainly, only the large model is usable. The small and medium models are not usable, because the library uses more than 64kByte of data; and the compact model is unusable as well, since the code of the library itself is slightly less than 64kByte, thus leaving very small place for the real work. The net effect of that limitation is that performances are not very impressive, to say the least (32-bit DOS extenders perform usually three-time faster). Even with the large model, the rasterizer is still limited in size, particularly with pixmaps (that is, with anti-aliasing gray levels). The test programs rely on a tiny graphical driver that mimics the ones available on other platforms. It has some peculiarities. First, as the test programs need a `console', the programs should linked with some emulation of that concept. We used successfully Borland EasyWin and Microsoft QuickWin for this purpose. Then, the graphics window that displays the bitmaps incur the usual 64kByte limit: The size of the window is quite tiny, particularly when displaying `gray-level' bitmaps (the size is then 320x200, but contrary to full-screen MS-DOS the pixels are not magnified). Ultimately, no efforts have been done to accomodate the colors of the screen: As a result, displaying gray bitmaps in 256-color mode uses only 4 levels of gray (instead of 5 rendered by the library). Another annoying limitation exists with some East Asian fonts that have 16,383 glyphs or more, since an internal table then overflows. We tried to overcome this using so-called `huge pointers', but then good support for these in the run-time library is needed. To enable huge pointers, try defining the `BIGFONTS' symbol with the makefile, like nmake /f arch\win16\makefile.VC BIGFONTS=1 make -farch/win16/makefile.BC /DBIGFONTS etc. The makefiles for both Microsoft and Borland compilers depend on a special file, arch/winXX/depend.win, which is built by a Unix script named `makedep'. You may consider editing it if you heavily modify the source files; or better yet, re-run the script, using any clone of the Bourne shell and gcc, the GNU compiler, with arch/winXX/makedep in both the `lib' and the `test' directories. Good luck! --- end of windows.txt ---