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/<system>' directory,
where <system> 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/<system>/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/<system>' 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/<system>'. 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/<system>' 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/<system>' 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/<system>/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 \
<program name>.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 ---