The FreeType compilation guide Table of contents ----------------- I. Introduction II. Compiling and installing the C library 1. Choosing a configuration file 2. Compiling the library 3. System-specific builds 4. Compiling the extensions 5. Using a Makefile 6. Building a dynamic library (`DLL' or `so') 7. Internationalization and the `ftxerr18' extension 8. TrueType patents III. Compiling the test programs 1. Compiling the graphics sub-system 2. Internationalization on Unix 3. Compiling the test programs 4. The `fdebug' program IV. Compiling the Pascal source 1. Compiling the library 2. Compiling the test programs 3. Porting the library to a different Pascal compiler -------------------------------------------------------------------- I. Introduction =============== This file gives detailed information on how to compile and install this release of FreeType on your system. ******************************************************************** * * * FOR A QUICK INSTALLATION GUIDE, WE STRONGLY RECOMMEND TO READ * * THE SYSTEM-SPECIFIC DOCUMENTS LOCATED IN THE `howto' DIRECTORY * * INSTEAD OF THIS GENERIC DOCUMENTATION. * * * ******************************************************************** This package, known as the FreeType 1.3.1 Public Release, contains several things which are best described by the directories containing them: - `lib' Contains the 1.3.1 release of the FreeType library. It is written in portable ANSI C and should compile fine with any type of ANSI C compiler. Note however that some system-specific files are provided in the `lib/arch' directory, in order to provide enhanced performance. If you need to include FreeType in a graphics library or an embedded system, you will most probably only need to use its contents and discard the rest. - `test' Contains test and demo programs used during development. Note that some of these programs might not compile on all platforms, as they need to display graphics. - `pascal' Contains the Pascal version of FreeType's source code. Note that the library has been successfully compiled with Turbo Pascal 6, Borland Pascal 7, Virtual Pascal, Free Pascal, Delphi 1, 2 and 3. The pascal source tree contains its own test programs which should *only* run with either Borland or Virtual Pascal compilers. - `po' On Unix, all of FreeType test programs support internationalization through the use of the `gettext' library. This directory contains `po' files, which are used to translate the original english text into language-specific one. Note also that this release contains an extension, called `ftxerr18' used to return internationalized strings from the usual FreeType error codes. The `po' files also contain translations for this extension. If you don't plan to use `ftxerr18' or internationalization, simply ignore it. Note also that even if `gettext' isn't available on your system, the test programs will be compiled correctly (using the `--disable-nls' configure switch). - `contrib' Contains a set of contributed tools and utilities related to TrueType or FreeType. Here you can find real situations how to use the library. This file explains how to compile the library, and the test programs on various platforms. II. Compiling the C library =========================== ******************************************************************** * * * NOTE THAT WE STRONGLY RECOMMEND TO READ THE SYSTEM-SPECIFIC * * DOCUMENTS LOCATED IN THE `howto' DIRECTORY FOR A * * `QUICK'N'EASY' COMPILATION & INSTALLATION GUIDE ON YOUR * * PLATFORM. THE FOLLOWING IS A VERY DETAILED EXPLANATION ON HOW * * TO COMPILE THE LIBRARY. * * * ******************************************************************** The following concepts are important to build the library. 1. Choosing a configuration file -------------------------------- The source code for the C library is located in the `lib' directory. It uses a file named `ft_conf.h', which contains the definitions of many configuration macros to toggle various engine features, as well as tell system-specific information (e.g., the size of the `int' type in bytes, etc). There are several configuration files provided with this release. They are located in the `lib/arch/' directory, where stands for a given architecture or environment. For example, the file `lib/arch/ansi/ft_conf.h' can be used to build the library with any ANSI-compliant compiler and runtime library. This release also provides configuration files for the following systems: MS-DOS, OS/2, Unix, VMS, Win 16, Amiga OS, and Win 32. Make sure, when compiling each source file of the FreeType library, to include the path to your configuration file in your include directories. 2. Compiling the library ------------------------ The library can be quickly compiled by invoking a Makefile, as described in the system-specific documents in the `howto' directory. We will now describe how to compile the library by hand. Traditionally, building a library like FreeType needs the following steps: - Compile each individual `.c' file into the corresponding object file, whose extension might be `.o' or `.obj', depending on the platform. - Group all object files into a library (e.g. `libfreetype.a' or `freetype.lib'), which is later used at link time to build the executables using it. For example, to build a static FreeType library on an ANSI system, with gcc, one should type cd lib # go to `lib' directory gcc -c -Iarch/ansi tt*.c # compile base engine sources ar -r libfreetype.a tt*.o # create library from objects Note that we included the path to the configuration file in the include list during compilation, by using the `-I' switch on the `arch/ansi' directory. This is required to use the configuration file named `lib/arch/ansi/ft_conf.h'. However, we recommend you to build the base FreeType engine as a SINGLE OBJECT FILE, i.e., a single `freetype.o' or `freetype.obj' file containing all the code for the base engine. It works by including all the `.c' files in a single one, and has a few advantages over a `traditional build': - Because all the code is `part' of a single source file, many internal functions need not be declared as `extern' anymore. This means that when compiling the engine as a dynamic library, only FreeType external functions will (correctly) be exported as entry points. This also typically allows the compiler to perform more aggressive optimizations on the source code, and results in somewhat faster and/or smaller overall code size depending on your compiler and environment. - Compilation speed is greatly improved, as the pre-processor and compiler need to be called only once, instead of a dozen times. - During development, this allows to detect very easily unresolved dependencies regarding the base engine's internal symbols. To compile the engine as a single object file, simply go to the `lib' directory and compile the file `lib/arch//freetype.c'. For example, to compile the ANSI build with gcc in SINGLE OBJECT MODE, use cd lib gcc -c -Iarch/ansi -I. arch/ansi/freetype.c This will create a single file called `freetype.o' containing the object code for the base TrueType engine. Note that we did include the paths to the configuration file (i.e. `arch/ansi') AND to the current directory (i.e. `.', where the included source files are located). `freetype.o' only contains the base engine. Extensions to the engine are located in the `lib/extend' directory and must be compiled separately as described later. 3. System-specific builds ------------------------- The files `ttfile.c', `ttmemory.c', and `ttmutex.c' are used to provide an implementation of i/o access, memory management, and thread synchronization for the rest of the library. These source files, located in the `lib' directory, use the ANSI C library for i/o and memory, and simply ignore threads (as the standard doesn't know threads at all). However, this release provides, for each supported platform, system-specific versions of these files, located in the `lib/arch/' hierarchy. Here are a few examples: lib/arch/os2/os2file.c: A replacement for `ttfile' which directly uses OS/2 system calls for i/o access. This results in slightly better performance, but much reduced resource requirements. lib/arch/unix/ttmmap.c: A replacement for `ttfile' which uses memory-mapped files instead of buffered-based reads on Unix. This increases *dramatically* the engine's performance when reading font files and loading glyphs. These files are directly included by the platform specific versions of `freetype.c' which are located in `lib/arch/'. This means that, by default, the single-object build of FreeType always chooses the best implementation available for a supported system. Note that it is also possible to redefine `ttmemory' or `ttmutex' with a similar scheme. This is used, for example, by the OS/2 font driver based on FreeType (called FreeType/2), which uses some special system calls to allocate memory shareable among distinct processes. By providing your own version of `ttfile', `ttmemory', and `ttmutex', you are able to tailor the FreeType engine for optimal performance and resource usage on your system. 4. Compiling the extensions --------------------------- The base TrueType engine is located in the `lib' directory. This release also provides many specific extensions in `lib/extend'. An extension is a simple way to extend FreeType's capabilities. It is used to perform any of the following: - Access some TrueType tables that are not loaded and returned by the base engine, like * the kerning table(s) * the `gasp' table * the glyph Postscript names * some OpenType layout tables (GDEF, GSUB; GPOS is not finished yet) - Perform some advanced operations on the TrueType data for very specific uses, like * enumerate the contents of a given charmap * access a font file's embedded bitmaps (called sbits) * return an array containing the dimensions of each glyph in the font The idea is to keep the base engine small (under 50kByte), while providing optional enhancements for specific uses. Writing an extension is rather easy. And adding a new extension to the engine doesn't need any modifications to the base engine's source code. To compile the extensions, simply go to the `lib' directory, then compile each file in `lib/extend'. Here is an example with gcc: cd lib ; go to `lib' gcc -c -Iarch/ansi -I. extend/ftx*.c ; compile all extensions You can later add each extension object file to the FreeType library file. For example, here is how to create the static library on Unix: cd lib -- compile the engine, then the extensions ar libfreetype.a *.o ; create static library 5. Using a Makefile ------------------- This release also provides Makefiles for many systems and compilers in the `lib/arch/' hierarchy. For more information, please read the documentation in the `howto' directory, which contains system-specific instructions on how to use them. Generally, you should go the `lib' directory, then invoke your system-specific Makefile from there. Here is an example: cd lib make -farch\msdos\Makefile.TC to compile the library under DOS with the Turbo C compiler and make tool. Or: cd lib wmake -f arch\msdos\Makefile.wat to compile it under DOS with the Watcom compiler and wmake tool. The ANSI target does not come with a Makefile, as there is no standard make tool available on all platforms. You will have to compile the library by hand as described in section I.3. We welcome new Makefile submissions for platforms not currently listed in the `lib/arch' hierarchy. Finally, note that most of the makefiles will build the library in single object mode; for a `traditional compile', try the `debug' target (i.e., say `make debug'). 6. Building a dynamic library (`DLL' or `so') --------------------------------------------- It is possible to build the engine as a dynamic library. The method to do so can vary greatly depending on the platform. a. Building a shared object on Unix NOTE THAT THIS RELEASE USES `libtool' TO AUTOMATICALLY CREATE A SHARED OBJECT FOR FREETYPE ON UNIX SYSTEMS THAT SUPPORT DYNAMIC LIBRARIES. WE STRONGLY RECOMMEND YOU TO READ THE `howto/unix.txt' FILE TO KNOW HOW TO USE THE `configure' SCRIPT. THIS SUB-SECTION DESCRIBES HOW TO COMPILE THE SHARED OBJECT BY HAND. In order to build a shared object like `libfreetype.so' on Unix, one has to compile each object file as position-independent code (a.k.a. PIC). We also strongly recommend to build the base engine as a single object, as this prevents internal `extern' functions to be exported as entry points (and creating a smaller overall .so file). For example, this with gcc, one can use the `-fPIC' flag when compiling the object files. Here is an example: cd lib ; go to `lib' gcc -c -fPIC -Iarch/ansi -I. \ arch/ansi/freetype.c ; compile engine gcc -c -fPIC -Iarch/ansi -I. extend/ftx*.c ; & extensions You can now invoke your linker to create the shared object from the various object files. See your system's documentation for details, or read the Unix-specific howto to know how to do it `easily' through the use of `libtool'. b. Building a DLL on Windows or OS/2 The dynamic linkers of Windows and OS/2 differ greatly from Unix ones. - The first difference is that the object files that make up the DLL do not need to be compiled as position-independent code. - The second difference is that the DLL's entry points must generally be declared as so in the source file, and/or maybe listed in a `definition' file used at link time when creating the DLL. Each FreeType API function is declared with the help of a special macro named EXPORT_DEF. For example, here is the declaration of the function `FT_Init_FreeType', as written in `freetype.h': EXPORT_DEF TT_Error TT_Init_FreeType( TT_Engine* engine ); If the configuration file `ft_conf.h' doesn't define EXPORT_DEF, it is automatically set to `extern' by default. In order to build FreeType as a DLL, one might need to define EXPORT_DEF in its `ft_conf.h' to a keyword tagging the function as a DLL entry point. This keyword varies with compilers and platforms; examples are `__system', `__dllentry', etc. Please refer to your compiler's user guide for instructions. You can also `grep' for EXPORT_DEF in the `freetype.h' source file to obtain the list of exported functions of the FreeType API, which could then be used to write a `def' file for the DLL. We provide a sample .def file (built with an Unix script) for Windows. Note also that the definition (i.e. its implementation) of each exported function is preceded with the EXPORT_FUNC macro, as in EXPORT_FUNC TT_Error TT_Init_FreeType( TT_Engine* engine ) { TT_Error error; ... } (to be found in `ttapi.c'). By default, EXPORT_FUNC converts to an empty string, but it can also be redefined if you need to. Note that the EXPORT_DEF/EXPORT_FUNC mechanism does not work for 16-bit Windows (in this environment, the special keyword for declaring entry points, (the `__export' keyword), must be after the type name). We suggest you to use the makefiles we provide for both Microsoft and Borland compilers. 7. Internationalization and the `ftxerr18' extension ---------------------------------------------------- The engine extension named `ftxerr18' is used to convert a FreeType error code into a human-readable string of text. However, it is able to support internationalization on Unix systems through the use of the `gettext' library. This means that the error messages will be localized to your system's language, provided it is available in this release. The currently available languages are - English (by default) - Czech - German - Spanish - French - Dutch One can add a new language by adding a `.po' file in the `po' directory. Please read the file `docs/i18n.txt' for more details on how to use `gettext'. In order to enable localization of the `ftxerr18' extension, one has to set the macro HAVE_LIBINTL_H at compile time. By default, the extension will build with support for the English language. Unix-specific: ------------------------------------------------- Note that the Unix `configure' script that comes with this release is able to automatically detect whether your system has `gettext' installed and set HAVE_LIBINTL_H in the `ft_conf_h' file accordingly. To disable internationalization, run `configure' with the option `--disable-nls' (NLS stands for `National Language Support'). Then rebuild the library. ---------------------------------------------------------------- Note that we do not support internationalization on non-Unix platforms, as the `gettext' library isn't available everywhere, or does not work in a consistent way in different environments. 8. TrueType patents ------------------- We have recently discovered that Apple owns several patents that relate to the rendering of TrueType fonts. This could mean that the free use and distribution of the FreeType library could be illegal in the US, Japan, and possibly other countries. For more information, please see the FreeType Patents page at: http://www.freetype.org/patents.htm This section will now explain how to build a `patent-free' engine, at the cost of rendering quality. This is done simply by de-activating the compilation of the TrueType bytecode interpreter (which is the only part of FreeType that might violate an Apple patent). This has two effects: - saving about 18kByte of code in the engine - ignoring completely the grid-fitting of vector outlines, which results in extremely low quality at small pixel sizes. Such an engine can be used by font converters and/or graphics libraries to display glyphs at high pixel sizes. In order to do so, simply look for the following line in your configuration file `ft_conf.h': #undef FT_CONFIG_OPTION_NO_INTERPRETER Then change the `#undef' into a `#define': #define FT_CONFIG_OPTION_NO_INTERPRETER Now rebuild the engine with this new configuration file. III. Compiling the test programs ================================ This section explains how to compile the FreeType test programs located in the `test' directory. Note that you should have successfully compiled the library, as described in section I before proceeding. WE STRONGLY RECOMMEND TO READ THE SYSTEM-SPECIFIC DOCUMENTS IN THE `howto' DIRECTORY FOR A `QUICK'N'EASY' GUIDE ON HOW TO COMPILE AND RUN THE TEST PROGRAMS. 1. Compile the graphics sub-system and utility sources ------------------------------------------------------ Some of the test programs need to display a graphics window to show their results. In order to do so, they use a tiny graphics system which was specifically written for FreeType (Note: The code isn't really clean there -- you have been warned). Also, some simple C sources in the `test' directory are utility functions used by nearly all test programs, and they should also be compiled before them. These are the following files: gmain.h: the sub-system interface gmain.c: the sub-system device-independent implementation gevents.h: the definition of the events used by the test program gdriver.h: the system-specific device interface blitter.c: a set of simple bitmap blitting functions common.c: common routines used by all test programs display.c: some routines dealing with text display as well as a system-specific `graphics driver' located in the `test/arch/' hierarchy. For example: test/arch/msdos/gfs_dos.c: used to display graphics in a full-screen Dos session test/arch/os2/gpm_os2.c: used to display graphics in an OS/2 Presentation Manager window test/arch/unix/gwin_x11.c: used to display graphics in an X11 window. You must compile the graphics sub-system and utilities before compiling the test programs. This can be done simply with gcc as: cd test gcc -c -I../lib gmain.c blitter.c common.c display.c gcc -c -I../lib -I. arch//yourdriver.c -o ./gdriver.o Note that a given test program may require some specific include paths (like `/usr/X11/include' with X11 for example). The resulting object files can be grouped in a library if you want to. 2. Internationalization on Unix ------------------------------- On Unix and Unix-like systems, the test programs are able to support internationalization through the use of the `gettext' library and the `ftxerr18' engine extension (see section I.7). To enable it, one has to compile each test program with the macro HAVE_LIBINTL_H set. This is the same macro used to enable it in `ftxerr18'. Note that the Unix `configure' script that comes with this release is able to automatically detect whether `gettext' is available on your system and set the macro accordingly when compiling the test programs. You can disable internationalisation with the `--disable-nls' option when invoking the `configure' script. 3. Compile the test programs ---------------------------- All test programs begin with the `ft' prefix in the `test' directory, as in `ftzoom', `ftdump', `ftmetric'", etc. are test programs. The easiest way to compile the test programs is compiling each source file to an object file, including the path to the FreeType engine source and its extensions. You need to use the following include paths: - the path to the engine's public header file, i.e. `freetype.h' which normally is `lib' - the path to the engine's extensions header files, located normally in `lib/extend' - the path to the configuration file `ft_conf.h'. This is only required to support internationalisation, as the test programs read `ft_conf.h' only to see whether HAVE_LIBINTL_H is defined. When compiling your own programs to FreeType, you shouldn't normally need this file and path. Here is an example, compiling a test program with the ANSI build: cd test gcc -c -I../lib -I../lib/extend -I../lib/arch/ansi \ .c Then, link this object file to the FreeType library, utilities and graphics sub-system to build an executable. You can then invoke each program directly. 4. The `fdebug' test program ---------------------------- All test programs begin with the `ft' prefix (in the `test' directory) as in `ftzoom', `ftdump', `ftmetric', etc. However, one test program named `fdebug' is used exclusively by FreeType developers. It is a very simple TrueType bytecode debugger, and was written to inspect the execution of the TrueType interpreter. Note that we rather use the Pascal debugger for real work on the interpreter, as it provides a much easier windowed interface through the use of the Turbo Vision library. The C debugger is mainly used to check that both Pascal and C sources produce the same output. You will need gcc to compile the debugger. It uses a special build of the FreeType engine to work. Follow these steps to compile it: 1. Compile the library for the `debugger' system, i.e. cd freetype/lib make -f arch/debugger/Makefile this will create a file named `libttf.a' in the directory `freetype/lib/arch/debugger' which will NOT interfere with your normal build (which is located in `freetype/lib'). 2. Compile the debugger: cd freetype/test make -f arch/debugger/Makefile This will create an executable called `fdebug.exe' or `fdebug', which is linked with the version of the library found in `freetype/lib/arch/debugger' as described above. [For old Unix variants like 4.2BSD please uncomment the flag HAVE_POSIX_TERMIOS in the makefile.] You can invoke the debugger in two ways: a. To debug a given glyph program in a given font, type fdebug glyph_number pointsize fontfile[.ttf] b. To debug a given font's CVT program, type fdebug --cvt pointsize fontfile[.ttf] Type `?' while running fdebug for a list of key bindings. IV. Compiling the Pascal source =============================== This section deals with the compilation of the Pascal version of the FreeType engine, whose source code is located in the `pascal' directory. Note that the Pascal version is more limited than the C one, as it lacks the following `features': - Extensions are neither supported nor provided in Pascal. - The interpreter is more pedantic than the C one and will probably not work with many broken glyphs. - It doesn't compile on old Turbo Pascal (TP 6.0 is a minimum), as it uses inline assembly code. Other than that, the Pascal version supports charmaps and the name table correctly since the 1.3 release. ******************************************************************** * * * AN IMPORTANT NOTE REGARDING TURBO AND BORLAND PASCAL USERS * * ========================================================== * * * * Programs compiled with TP6 and BP7 might not be able to run on * * fast machines! * * * * Usually, the program aborts immediately with a message like * * * * Runtime error 200: Divide by zero at xxxx:xxxx * * * * The bug is located in the runtime's initialization routine * * used to compute the machine's speed. It does so by dividing a * * value taken through the BIOS timer by a small constant. * * * * On fast machines, the result exceeds 16 bits, which causes a * * CPU exception/interrupt. The latter is caught by the * * runtime's exception handlers which aborts the execution and * * prints the above message. * * * * We don't know anything that can be done to fix this bug, as it * * would need a recompilation of a version of the Borland runtime * * initialization code. * * * ******************************************************************** Due to lack of time, the library could not be fully tested under TP6 or BP7. 1. Compiling the library ------------------------ The library itself is located in `pascal/lib'. You can compile it very simply by invoking your Pascal compiler on the file `freetype.pas'. As always with Pascal, dependencies are resolved automatically. 2. Compiling the test programs ------------------------------ The test programs are located in `pascal/test'. You will mainly find there the following: lint - A TrueType glyph loading checker. This test program will simply load each glyph in a font file and check for errors in its hinting programs. It is useful to find broken glyphs in fonts. view - A simple TrueType glyph viewer. Shows all the glyphs within a given font file on a graphics screen. Only works under DOS (with Borland Pascal) and OS/2 (with Virtual Pascal). timer - A simple benchmark program for the scan-line converter. Similar to the C `fttimer' test program. debugger - A TrueType bytecode debugger. This one must be compiled with the Turbo Vision library. It uses a rather advanced windowed interface to display the glyph program and their execution. It can also display the current glyph in a graphics window. A bit rough but extremely useful to the development of FreeType. dump - A TrueType metrics checker. This test program simply checks that the hinted width of each glyph corresponds to the one found in the TrueType `hdmx' table when present. This program is now obsolete and should be ignored. As always, simply invoke the root source file to make an executable automatically -- don't forget to include the path to the FreeType unit as described in section III.1. 3. Porting the library to a different Pascal compiler ----------------------------------------------------- The Pascal sources use inline assembly to implement the 64-bit computation routines needed by the TrueType engine. This release comes with various versions of the `ttcalc' inline assembly. These files are (within `pascal/lib'): ttcalc1.inc: for Turbo and Borland Pascal & Delphi 1 (16-bit) ttcalc2.inc: for Virtual Pascal (32-bit) ttcalc3.inc: for Delphi 2 & 3 (untested on Delphi 4 & 5) ttcalc4.inc: for Free Pascal on a i386 (32-bit) Note that in order to port the Pascal source to a new compiler, one has to: a. Write a specific version of `ttcalc?.inc' for the compiler's inline assembly. Be sure to respect the compiler's assembler syntax, as well as its parameter-passing function interface, i.e., which registers and/or stack slots are used to pass arguments at function call. b. Add some lines to detect your compiler in `ttconfig.inc'. This file contains some tests to define macros used to determine which compiler is used. These macros are used later in `ttcalc.pas' in order to select the correct inline assembly file to use. See the source files for more details. c. Add an include to the new `ttcalc?.inc' in `ttcalc.pas'. Make this according to the compiler detected in `ttconfig.inc'. See the source files for more details. d. Submit your changes to the FreeType Developers list. In order to see them added to the next release of the Pascal engine. --- end of INSTALL ---