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 -------------------------------------------------------------------- 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.4.9 Public Release, contains several things which are best described by the directories containing them: - `lib' Contains the 1.4.9 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. - `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, Win 32, Amiga OS, Mac, and BeOS. 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, UK, France, and possibly other countries. For more information, please see the FreeType Patents page at: http://www.freetype.org/patents.htm To avoid problems, we have decided to turn off by default 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 18 kbyte of code in the engine - ignoring completely the grid-fitting of vector outlines, which results in extremely low quality at small pixel sizes. Nevertheless, such an engine can be used by font converters and/or graphics libraries to display glyphs at high pixel sizes. If you believe you can go ahead, this section will now explain how to build a `complete' engine, at the cost of possible patent violation. This is done simply by activating the compilation of the TrueType bytecode interpreter. In order to do so, simply recompile the library (more exactly, it affects only ttinterp.c) while #defin'ing TT_CONFIG_OPTION_BYTECODE_INTERPRETER. In order to do so, simply look for the following line in your configuration file `ft_conf.h': #undef FT_CONFIG_OPTION_BYTECODE_INTERPRETER Then change the `#undef' into a `#define': #define FT_CONFIG_OPTION_BYTECODE_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. The Pascal debugger is available in the `ftpascal' package, it is not included with this release. 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. Ensure the bytecode interpreter is not turned off (using the debugger with the default build which is patents-compliant is not really useful). How to process is explained in part 8 of chapter II above. This implies that you must first be sure that you are really allowed to use such a version of FreeType. 2. 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'). 3. 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 =============================== The Pascal source code is no longer part of this package. It has been moved to another archive (resp. CVS repository). Please visit http://www.freetype.org for more information. --- end of INSTALL ---