1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
|
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 (`so' or `DLL')
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.5 Public Release, contains
several things which are best described by the directories
containing them:
- `lib'
Contains the 1.5 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/<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, 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 -I arch/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 -I arch/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
C standard doesn't know about 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
* the OpenType layout tables (GDEF, GPOS, GSUB)
- 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 60 kByte),
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 -I arch/ansi -I . -I extend 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
Borland 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.
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 (`so' or `DLL')
---------------------------------------------
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 -I arch/ansi -I . \
arch/ansi/freetype.c # compile engine
gcc -c -fPIC -I arch/ansi -I . -I extend
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 FT_EXPORT_DEF. For example, here is the
declaration of the function `FT_Init_FreeType', as written in
`freetype.h':
FT_EXPORT_DEF( TT_Error )
TT_Init_FreeType( TT_Engine* engine );
If the configuration file `ft_conf.h' doesn't define
FT_EXPORT_DEF, it is automatically set to `extern' by default.
In order to build FreeType as a DLL, one might need to define
FT_EXPORT_DEF in its `ft_conf.h' to the keywords tagging the
function as a DLL entry point. This keyword varies with
compilers and platforms; examples are `__system',
`__dllentry', `_FAR _PASCAL _export' after the type name, etc.
Note that FT_EXPORT_DEF is a (macro) function, taking the type
name as argument, in order to allow the last example.
Please refer to your compiler's user guide for instructions.
You can also `grep' for FT_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 FT_EXPORT_FUNC
macro, as in
FT_EXPORT_FUNC( TT_Error )
TT_Init_FreeType( TT_Engine* engine )
{
TT_Error error;
...
}
(to be found in `ttapi.c').
By default, FT_EXPORT_FUNC converts to an empty string, but it
can also be redefined if you need to.
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. 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/<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. 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 (but of course you should modify the
`ft_conf.h' file which is specific to the debugger). 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 ---
|