freetype1/INSTALL

   1
   2                    The FreeType compilation guide
   3
   4
   5 Table of contents
   6 -----------------
   7
   8   I. Introduction
   9
  10  II. Compiling and installing the C library
  11
  12     1. Choosing a configuration file
  13     2. Compiling the library
  14     3. System-specific builds
  15     4. Compiling the extensions
  16     5. Using a Makefile
  17     6. Building a dynamic library (`DLL' or `so')
  18     7. Internationalization and the `ftxerr18' extension
  19     8. TrueType patents
  20
  21
  22 III. Compiling the test programs
  23
  24     1. Compiling the graphics sub-system
  25     2. Internationalization on Unix
  26     3. Compiling the test programs
  27     4. The `fdebug' program
  28
  29
  30  IV. Compiling the Pascal source
  31
  32     1. Compiling the library
  33     2. Compiling the test programs
  34     3. Porting the library to a different Pascal compiler
  35
  36 --------------------------------------------------------------------
  37
  38
  39
  40 I. Introduction
  41 ===============
  42
  43   This file gives detailed information on how to compile and install
  44   this release of FreeType on your system.
  45
  46
  47 ********************************************************************
  48 *                                                                  *
  49 *  FOR A QUICK INSTALLATION GUIDE,  WE STRONGLY RECOMMEND TO READ  *
  50 *  THE SYSTEM-SPECIFIC DOCUMENTS LOCATED IN THE `howto' DIRECTORY  *
  51 *  INSTEAD OF THIS GENERIC DOCUMENTATION.                          *
  52 *                                                                  *
  53 ********************************************************************
  54
  55
  56   This package,  known as the FreeType 1.3.1  Public Release, contains
  57   several  things  which  are  best  described  by  the  directories
  58   containing them:
  59
  60   - `lib'
  61
  62     Contains the 1.3.1 release of the FreeType library.  It is written
  63     in  portable ANSI C  and should  compile fine  with any  type of
  64     ANSI C compiler.
  65
  66     Note however that some system-specific files are provided in the
  67     `lib/arch' directory, in order to provide enhanced performance.
  68
  69     If  you need to  include FreeType  in a  graphics library  or an
  70     embedded system,  you will  most probably only  need to  use its
  71     contents and discard the rest.
  72
  73   - `test'
  74
  75     Contains test  and demo programs used  during development.  Note
  76     that some of these programs  might not compile on all platforms,
  77     as they need to display graphics.
  78
  79   - `pascal'
  80
  81     Contains  the Pascal  version of  FreeType's source  code.  Note
  82     that  the library  has  been  successfully  compiled with  Turbo
  83     Pascal  6,  Borland  Pascal  7,  Virtual  Pascal,  Free  Pascal,
  84     Delphi 1, 2 and 3.
  85
  86     The  pascal source  tree contains  its own  test  programs which
  87     should  *only*  run  with   either  Borland  or  Virtual  Pascal
  88     compilers.
  89
  90   - `po'
  91
  92     On    Unix,   all    of   FreeType    test    programs   support
  93     internationalization through  the use of  the `gettext' library.
  94     This directory contains `po'  files, which are used to translate
  95     the original english text into language-specific one.
  96
  97     Note  also  that  this  release contains  an  extension,  called
  98     `ftxerr18'  used to  return internationalized  strings  from the
  99     usual  FreeType  error  codes.   The  `po'  files  also  contain
 100     translations for this extension.
 101
 102     If  you don't  plan to  use `ftxerr18'  or internationalization,
 103     simply  ignore  it.  Note  also  that  even  if `gettext'  isn't
 104     available  on your system,  the test  programs will  be compiled
 105     correctly (using the `--disable-nls' configure switch).
 106
 107   - `contrib'
 108
 109     Contains  a set of  contributed tools  and utilities  related to
 110     TrueType or FreeType.  Here you  can find real situations how to
 111     use the library.
 112
 113
 114   This  file explains  how  to  compile the  library,  and the  test
 115   programs on various platforms.
 116
 117
 118
 119 II. Compiling the C library
 120 ===========================
 121
 122
 123 ********************************************************************
 124 *                                                                  *
 125 *  NOTE THAT  WE STRONGLY  RECOMMEND TO READ  THE SYSTEM-SPECIFIC  *
 126 *  DOCUMENTS   LOCATED   IN   THE   `howto'   DIRECTORY   FOR   A  *
 127 *  `QUICK'N'EASY'  COMPILATION  &   INSTALLATION  GUIDE  ON  YOUR  *
 128 *  PLATFORM.  THE FOLLOWING IS A VERY DETAILED EXPLANATION ON HOW  *
 129 *  TO COMPILE THE LIBRARY.                                         *
 130 *                                                                  *
 131 ********************************************************************
 132
 133
 134   The following concepts are important to build the library.
 135
 136
 137   1. Choosing a configuration file
 138   --------------------------------
 139
 140     The  source code  for  the C  library  is located  in the  `lib'
 141     directory.
 142
 143     It uses a file named `ft_conf.h', which contains the definitions
 144     of many configuration macros  to toggle various engine features,
 145     as well  as tell system-specific information (e.g.,  the size of
 146     the `int' type in bytes, etc).
 147
 148     There  are  several   configuration  files  provided  with  this
 149     release.  They are located in the `lib/arch/<system>' directory,
 150     where <system> stands for a given architecture or environment.
 151
 152     For example,  the file `lib/arch/ansi/ft_conf.h' can  be used to
 153     build the  library with any ANSI-compliant  compiler and runtime
 154     library.
 155
 156     This release also provides configuration files for the following
 157     systems: MS-DOS, OS/2, Unix, VMS, Win 16, Amiga OS, and Win 32.
 158
 159     Make  sure, when  compiling  each source  file  of the  FreeType
 160     library, to include the path  to your configuration file in your
 161     include directories.
 162
 163
 164   2. Compiling the library
 165   ------------------------
 166
 167     The library can  be quickly compiled by invoking  a Makefile, as
 168     described  in  the  system-specific  documents  in  the  `howto'
 169     directory.
 170
 171     We will now describe how to compile the library by hand.
 172
 173     Traditionally,  building  a  library  like  FreeType  needs  the
 174     following steps:
 175
 176     - Compile  each  individual  `.c'  file into  the  corresponding
 177       object  file,  whose  extension   might  be  `.o'  or  `.obj',
 178       depending on the platform.
 179
 180     - Group all object files into a library (e.g. `libfreetype.a' or
 181       `freetype.lib'), which is later used at link time to build the
 182       executables using it.
 183
 184     For  example, to  build a  static  FreeType library  on an  ANSI
 185     system, with gcc, one should type
 186
 187       cd lib                           # go to `lib' directory
 188       gcc -c -Iarch/ansi tt*.c         # compile base engine sources
 189       ar -r libfreetype.a tt*.o        # create library from objects
 190
 191     Note that we included the  path to the configuration file in the
 192     include list during compilation, by using the `-I' switch on the
 193     `arch/ansi'   directory.    This   is   required  to   use   the
 194     configuration file named `lib/arch/ansi/ft_conf.h'.
 195
 196     However, we recommend you to build the base FreeType engine as a
 197     SINGLE   OBJECT   FILE,   i.e.,   a   single   `freetype.o'   or
 198     `freetype.obj' file containing all the code for the base engine.
 199     It works  by including all the  `.c' files in a  single one, and
 200     has a few advantages over a `traditional build':
 201
 202     - Because all the  code is `part' of a  single source file, many
 203       internal functions need not be declared as `extern' anymore.
 204
 205       This  means  that  when  compiling  the engine  as  a  dynamic
 206       library, only FreeType  external functions will (correctly) be
 207       exported as entry points.
 208
 209       This  also  typically  allows  the compiler  to  perform  more
 210       aggressive optimizations  on the  source code, and  results in
 211       somewhat faster and/or smaller  overall code size depending on
 212       your compiler and environment.
 213
 214     - Compilation  speed is greatly  improved, as  the pre-processor
 215       and compiler need  to be called only once,  instead of a dozen
 216       times.
 217
 218     - During  development,   this  allows  to   detect  very  easily
 219       unresolved dependencies  regarding the base  engine's internal
 220       symbols.
 221
 222     To compile the engine as a  single object file, simply go to the
 223     `lib'       directory      and       compile       the      file
 224     `lib/arch/<system>/freetype.c'.
 225
 226     For example, to compile the ANSI build with gcc in SINGLE OBJECT
 227     MODE, use
 228
 229       cd lib
 230       gcc -c -Iarch/ansi -I. arch/ansi/freetype.c
 231
 232     This will  create a  single file called  `freetype.o' containing
 233     the object code for the base TrueType engine.
 234
 235     Note that  we did  include the paths  to the  configuration file
 236     (i.e.   `arch/ansi') AND  to  the current  directory (i.e.  `.',
 237     where the included source files are located).
 238
 239     `freetype.o' only  contains the base engine.   Extensions to the
 240     engine  are located in  the `lib/extend'  directory and  must be
 241     compiled separately as described later.
 242
 243
 244   3. System-specific builds
 245   -------------------------
 246
 247     The files `ttfile.c', `ttmemory.c',  and `ttmutex.c' are used to
 248     provide an implementation of  i/o access, memory management, and
 249     thread synchronization for the rest of the library.
 250
 251     These source files, located in the `lib' directory, use the ANSI
 252     C library for i/o and  memory, and simply ignore threads (as the
 253     standard doesn't know threads at all).
 254
 255     However,  this release  provides, for  each  supported platform,
 256     system-specific  versions   of  these  files,   located  in  the
 257     `lib/arch/<system>' hierarchy.  Here are a few examples:
 258
 259       lib/arch/os2/os2file.c:
 260
 261         A replacement  for `ttfile' which directly  uses OS/2 system
 262         calls  for  i/o access.   This  results  in slightly  better
 263         performance, but much reduced resource requirements.
 264
 265       lib/arch/unix/ttmmap.c:
 266
 267         A  replacement for `ttfile'  which uses  memory-mapped files
 268         instead  of buffered-based  reads on  Unix.   This increases
 269         *dramatically*  the engine's  performance when  reading font
 270         files and loading glyphs.
 271
 272     These  files  are directly  included  by  the platform  specific
 273     versions    of    `freetype.c'     which    are    located    in
 274     `lib/arch/<system>'.    This  means   that,   by  default,   the
 275     single-object  build   of  FreeType  always   chooses  the  best
 276     implementation available for a supported system.
 277
 278     Note  that  it  is  also  possible  to  redefine  `ttmemory'  or
 279     `ttmutex' with a similar scheme.   This is used, for example, by
 280     the  OS/2 font  driver  based on  FreeType (called  FreeType/2),
 281     which  uses  some  special   system  calls  to  allocate  memory
 282     shareable among distinct processes.
 283
 284     By  providing  your own  version  of  `ttfile', `ttmemory',  and
 285     `ttmutex',  you  are able  to  tailor  the  FreeType engine  for
 286     optimal performance and resource usage on your system.
 287
 288
 289   4. Compiling the extensions
 290   ---------------------------
 291
 292     The  base TrueType  engine is  located in  the  `lib' directory.
 293     This   release  also  provides   many  specific   extensions  in
 294     `lib/extend'.
 295
 296     An extension is a  simple way to extend FreeType's capabilities.
 297     It is used to perform any of the following:
 298
 299     - Access some  TrueType tables that are not  loaded and returned
 300       by the base engine, like
 301
 302       * the kerning table(s)
 303       * the `gasp' table
 304       * the glyph Postscript names
 305       * some  OpenType  layout  tables  (GDEF,  GSUB;  GPOS  is  not
 306         finished yet)
 307
 308     - Perform some advanced operations on the TrueType data for very
 309       specific uses, like
 310
 311       * enumerate the contents of a given charmap
 312       * access a font file's embedded bitmaps (called sbits)
 313       * return an  array containing the dimensions of  each glyph in
 314         the font
 315
 316     The idea is to keep the base engine small (under 50kByte), while
 317     providing optional enhancements for specific uses.
 318
 319     Writing an extension is rather easy.  And adding a new extension
 320     to  the  engine  doesn't  need  any modifications  to  the  base
 321     engine's source code.
 322
 323     To  compile the extensions,  simply go  to the  `lib' directory,
 324     then compile each file in `lib/extend'.  Here is an example with
 325     gcc:
 326
 327       cd lib                                ; go to `lib'
 328       gcc -c -Iarch/ansi -I. extend/ftx*.c  ; compile all extensions
 329
 330
 331     You can  later add  each extension object  file to  the FreeType
 332     library file.   For example,  here is how  to create  the static
 333     library on Unix:
 334
 335       cd lib
 336       -- compile the engine, then the extensions
 337       ar libfreetype.a *.o                   ; create static library
 338
 339
 340   5. Using a Makefile
 341   -------------------
 342
 343     This  release  also  provides  Makefiles for  many  systems  and
 344     compilers  in  the   `lib/arch/<system>'  hierarchy.   For  more
 345     information,  please  read  the  documentation  in  the  `howto'
 346     directory, which contains system-specific instructions on how to
 347     use them.
 348
 349     Generally, you  should go the `lib' directory,  then invoke your
 350     system-specific Makefile from there.  Here is an example:
 351
 352       cd lib
 353       make -farch\msdos\Makefile.TC
 354
 355     to compile the  library under DOS with the  Turbo C compiler and
 356     make tool.  Or:
 357
 358       cd lib
 359       wmake -f arch\msdos\Makefile.wat
 360
 361     to compile it under DOS with the Watcom compiler and wmake tool.
 362
 363     The ANSI  target does not come  with a Makefile, as  there is no
 364     standard make tool available on all platforms.  You will have to
 365     compile the library by hand as described in section I.3.
 366
 367     We welcome new Makefile  submissions for platforms not currently
 368     listed in the `lib/arch' hierarchy.
 369
 370     Finally, note that most of  the makefiles will build the library
 371     in  single object  mode; for  a `traditional  compile',  try the
 372     `debug' target (i.e., say `make debug').
 373
 374
 375   6. Building a dynamic library (`DLL' or `so')
 376   ---------------------------------------------
 377
 378     It is  possible to build the  engine as a  dynamic library.  The
 379     method to do so can vary greatly depending on the platform.
 380
 381     a. Building a shared object on Unix
 382
 383       NOTE THAT THIS RELEASE  USES `libtool' TO AUTOMATICALLY CREATE
 384       A  SHARED OBJECT  FOR FREETYPE  ON UNIX  SYSTEMS  THAT SUPPORT
 385       DYNAMIC  LIBRARIES.  WE  STRONGLY  RECOMMEND YOU  TO READ  THE
 386       `howto/unix.txt'  FILE  TO KNOW  HOW  TO  USE THE  `configure'
 387       SCRIPT.  THIS SUB-SECTION DESCRIBES  HOW TO COMPILE THE SHARED
 388       OBJECT BY HAND.
 389
 390       In  order to build  a shared  object like  `libfreetype.so' on
 391       Unix,   one    has   to   compile   each    object   file   as
 392       position-independent code (a.k.a. PIC).
 393
 394       We  also strongly  recommend to  build  the base  engine as  a
 395       single object, as this prevents internal `extern' functions to
 396       be exported  as entry points  (and creating a  smaller overall
 397       .so file).
 398
 399       For example, this with gcc,  one can use the `-fPIC' flag when
 400       compiling the object files.  Here is an example:
 401
 402         cd lib                                      ; go to `lib'
 403         gcc -c -fPIC -Iarch/ansi -I. \
 404             arch/ansi/freetype.c                    ; compile engine
 405         gcc -c -fPIC -Iarch/ansi -I. extend/ftx*.c  ; & extensions
 406
 407       You can  now invoke  your linker to  create the  shared object
 408       from   the   various   object   files.   See   your   system's
 409       documentation for details, or  read the Unix-specific howto to
 410       know how to do it `easily' through the use of `libtool'.
 411
 412     b. Building a DLL on Windows or OS/2
 413
 414       The dynamic  linkers of Windows  and OS/2 differ  greatly from
 415       Unix ones.
 416
 417       - The first difference  is that the object files  that make up
 418         the DLL  do not need to be  compiled as position-independent
 419         code.
 420
 421       - The second  difference is that  the DLL's entry  points must
 422         generally be declared as so in the source file, and/or maybe
 423         listed  in  a  `definition'  file  used at  link  time  when
 424         creating the DLL.
 425
 426       Each  FreeType API  function is  declared with  the help  of a
 427       special  macro named  EXPORT_DEF.   For example,  here is  the
 428       declaration of the  function `FT_Init_FreeType', as written in
 429       `freetype.h':
 430
 431         EXPORT_DEF
 432         TT_Error  TT_Init_FreeType( TT_Engine*  engine );
 433
 434       If   the  configuration   file   `ft_conf.h'  doesn't   define
 435       EXPORT_DEF, it is automatically set to `extern' by default.
 436
 437       In order to build FreeType as  a DLL, one might need to define
 438       EXPORT_DEF  in  its  `ft_conf.h'  to  a  keyword  tagging  the
 439       function  as a  DLL  entry point.   This  keyword varies  with
 440       compilers    and   platforms;    examples    are   `__system',
 441       `__dllentry', etc.
 442
 443       Please refer to your compiler's user guide for instructions.
 444
 445       You can also `grep'  for EXPORT_DEF in the `freetype.h' source
 446       file to obtain the list  of exported functions of the FreeType
 447       API, which  could then be used  to write a `def'  file for the
 448       DLL. We provide a sample .def file (built with an Unix script)
 449       for Windows.
 450
 451       Note  also that  the definition  (i.e. its  implementation) of
 452       each exported function is preceded with the EXPORT_FUNC macro,
 453       as in
 454
 455         EXPORT_FUNC
 456         TT_Error  TT_Init_FreeType( TT_Engine*  engine )
 457         {
 458           TT_Error  error;
 459           ...
 460         }
 461
 462       (to be found in `ttapi.c').
 463
 464       By default,  EXPORT_FUNC converts to  an empty string,  but it
 465       can also be redefined if you need to.
 466
 467       Note that  the EXPORT_DEF/EXPORT_FUNC mechanism  does not work
 468       for 16-bit  Windows (in this environment,  the special keyword
 469       for declaring entry points,  (the `__export' keyword), must be
 470       after the type name).  We  suggest you to use the makefiles we
 471       provide for both Microsoft and Borland compilers.
 472
 473
 474   7. Internationalization and the `ftxerr18' extension
 475   ----------------------------------------------------
 476
 477     The  engine extension  named  `ftxerr18' is  used  to convert  a
 478     FreeType error code into a human-readable string of text.
 479
 480     However,  it is  able  to support  internationalization on  Unix
 481     systems through  the use of  the `gettext' library.   This means
 482     that  the error  messages  will be  localized  to your  system's
 483     language,  provided  it  is  available  in  this  release.   The
 484     currently available languages are
 485
 486       - English (by default)
 487       - Czech
 488       - German
 489       - Spanish
 490       - French
 491       - Dutch
 492
 493     One can  add a new language by  adding a `.po' file  in the `po'
 494     directory.   Please  read  the  file  `docs/i18n.txt'  for  more
 495     details on how to use `gettext'.
 496
 497     In order to enable localization of the `ftxerr18' extension, one
 498     has  to  set  the  macro  HAVE_LIBINTL_H at  compile  time.   By
 499     default, the  extension will build with support  for the English
 500     language.
 501
 502     Unix-specific: -------------------------------------------------
 503
 504       Note  that the Unix  `configure' script  that comes  with this
 505       release is  able to  automatically detect whether  your system
 506       has  `gettext'   installed  and  set   HAVE_LIBINTL_H  in  the
 507       `ft_conf_h' file accordingly.
 508
 509       To  disable  internationalization,  run `configure'  with  the
 510       option  `--disable-nls'  (NLS  stands for  `National  Language
 511       Support').  Then rebuild the library.
 512
 513     ----------------------------------------------------------------
 514
 515     Note  that we  do not  support internationalization  on non-Unix
 516     platforms, as the  `gettext' library isn't available everywhere,
 517     or does not work in a consistent way in different environments.
 518
 519
 520   8. TrueType patents
 521   -------------------
 522
 523     We have recently discovered that Apple owns several patents that
 524     relate to the rendering of TrueType fonts.  This could mean that
 525     the free use  and distribution of the FreeType  library could be
 526     illegal in the US, Japan, and possibly other countries.
 527
 528     For more information, please see the FreeType Patents page at:
 529
 530       http://www.freetype.org/patents.htm
 531
 532     This  section will  now  explain how  to  build a  `patent-free'
 533     engine, at the  cost of rendering quality.  This  is done simply
 534     by  de-activating  the  compilation  of  the  TrueType  bytecode
 535     interpreter  (which is  the  only part  of  FreeType that  might
 536     violate an Apple patent).  This has two effects:
 537
 538     - saving about 18kByte of code in the engine
 539     - ignoring completely the grid-fitting of vector outlines, which
 540       results in extremely low quality at small pixel sizes.
 541
 542     Such an  engine can be  used by font converters  and/or graphics
 543     libraries to display glyphs at high pixel sizes.
 544
 545     In order  to do so, simply  look for the following  line in your
 546     configuration file `ft_conf.h':
 547
 548       #undef  FT_CONFIG_OPTION_NO_INTERPRETER
 549
 550     Then change the `#undef' into a `#define':
 551
 552       #define FT_CONFIG_OPTION_NO_INTERPRETER
 553
 554     Now rebuild the engine with this new configuration file.
 555
 556
 557
 558 III. Compiling the test programs
 559 ================================
 560
 561   This section  explains how to  compile the FreeType  test programs
 562   located  in  the `test'  directory.   Note  that  you should  have
 563   successfully  compiled  the library,  as  described  in section  I
 564   before proceeding.
 565
 566   WE STRONGLY RECOMMEND TO READ THE SYSTEM-SPECIFIC DOCUMENTS IN THE
 567   `howto' DIRECTORY FOR A `QUICK'N'EASY' GUIDE ON HOW TO COMPILE AND
 568   RUN THE TEST PROGRAMS.
 569
 570
 571   1. Compile the graphics sub-system and utility sources
 572   ------------------------------------------------------
 573
 574     Some of the  test programs need to display  a graphics window to
 575     show their results.  In order to do so, they use a tiny graphics
 576     system which  was specifically  written for FreeType  (Note: The
 577     code isn't really clean there -- you have been warned).
 578
 579     Also, some simple C sources  in the `test' directory are utility
 580     functions used by nearly all test programs, and they should also
 581     be compiled before them.  These are the following files:
 582
 583       gmain.h:   the sub-system interface
 584       gmain.c:   the sub-system device-independent implementation
 585       gevents.h: the definition  of  the  events  used  by the  test
 586                  program
 587       gdriver.h: the system-specific device interface
 588       blitter.c: a set of simple bitmap blitting functions
 589       common.c:  common routines used by all test programs
 590       display.c: some routines dealing with text display
 591
 592     as well  as a system-specific  `graphics driver' located  in the
 593     `test/arch/<system>' hierarchy.  For example:
 594
 595       test/arch/msdos/gfs_dos.c: used  to  display   graphics  in  a
 596                                  full-screen Dos session
 597       test/arch/os2/gpm_os2.c:   used to display graphics in an OS/2
 598                                  Presentation Manager window
 599       test/arch/unix/gwin_x11.c: used to  display graphics in an X11
 600                                  window.
 601
 602     You must  compile the  graphics sub-system and  utilities before
 603     compiling the test  programs.  This can be done  simply with gcc
 604     as:
 605
 606       cd test
 607       gcc -c -I../lib gmain.c blitter.c common.c display.c
 608       gcc -c -I../lib -I. arch/<system>/yourdriver.c -o ./gdriver.o
 609
 610     Note that a given test program may require some specific include
 611     paths (like `/usr/X11/include' with X11 for example).
 612
 613     The resulting  object files can be  grouped in a  library if you
 614     want to.
 615
 616
 617   2. Internationalization on Unix
 618   -------------------------------
 619
 620     On Unix  and Unix-like  systems, the test  programs are  able to
 621     support  internationalization through the  use of  the `gettext'
 622     library and the `ftxerr18' engine extension (see section I.7).
 623
 624     To  enable it, one  has to  compile each  test program  with the
 625     macro HAVE_LIBINTL_H set.  This is the same macro used to enable
 626     it in `ftxerr18'.
 627
 628     Note  that the  Unix  `configure' script  that  comes with  this
 629     release  is able  to automatically  detect whether  `gettext' is
 630     available  on your  system and  set the  macro  accordingly when
 631     compiling the test programs.
 632
 633     You  can disable  internationalisation with  the `--disable-nls'
 634     option when invoking the `configure' script.
 635
 636
 637   3. Compile the test programs
 638   ----------------------------
 639
 640     All  test programs  begin with  the  `ft' prefix  in the  `test'
 641     directory, as in `ftzoom',  `ftdump', `ftmetric'", etc. are test
 642     programs.
 643
 644     The easiest way  to compile the test programs  is compiling each
 645     source  file  to an  object  file,  including  the path  to  the
 646     FreeType engine source and its  extensions.  You need to use the
 647     following include paths:
 648
 649     - the path to the engine's public header file, i.e. `freetype.h'
 650       which normally is `lib'
 651
 652     - the  path to  the  engine's extensions  header files,  located
 653       normally in `lib/extend'
 654
 655     - the path to the  configuration file `ft_conf.h'.  This is only
 656       required to support internationalisation, as the test programs
 657       read  `ft_conf.h'  only   to  see  whether  HAVE_LIBINTL_H  is
 658       defined.
 659
 660       When compiling  your own  programs to FreeType,  you shouldn't
 661       normally need this file and path.
 662
 663     Here  is an  example, compiling  a  test program  with the  ANSI
 664     build:
 665
 666       cd test
 667       gcc -c -I../lib -I../lib/extend -I../lib/arch/ansi \
 668           <program name>.c
 669
 670     Then, link  this object file to the  FreeType library, utilities
 671     and graphics sub-system to build an executable.
 672
 673     You can then invoke each program directly.
 674
 675
 676   4. The `fdebug' test program
 677   ----------------------------
 678
 679     All  test programs  begin with  the `ft'  prefix (in  the `test'
 680     directory) as in `ftzoom', `ftdump', `ftmetric', etc.
 681
 682     However, one test program  named `fdebug' is used exclusively by
 683     FreeType  developers.  It  is  a very  simple TrueType  bytecode
 684     debugger,  and  was written  to  inspect  the  execution of  the
 685     TrueType interpreter.
 686
 687     Note that we rather use the Pascal debugger for real work on the
 688     interpreter,  as it  provides a  much easier  windowed interface
 689     through the use of the  Turbo Vision library.  The C debugger is
 690     mainly used to check that  both Pascal and C sources produce the
 691     same output.
 692
 693     You will  need gcc to compile  the debugger.  It  uses a special
 694     build of  the FreeType  engine to work.   Follow these  steps to
 695     compile it:
 696
 697       1. Compile the library for the `debugger' system, i.e.
 698
 699         cd freetype/lib
 700         make -f arch/debugger/Makefile
 701
 702       this  will create  a file  named `libttf.a'  in  the directory
 703       `freetype/lib/arch/debugger'  which  will  NOT interfere  with
 704       your normal build (which is located in `freetype/lib').
 705
 706       2. Compile the debugger:
 707
 708         cd freetype/test
 709         make -f arch/debugger/Makefile
 710
 711       This  will   create  an  executable   called  `fdebug.exe'  or
 712       `fdebug',  which is  linked with  the version  of  the library
 713       found in `freetype/lib/arch/debugger' as described above.
 714
 715       [For old Unix  variants like 4.2BSD please  uncomment the flag
 716       HAVE_POSIX_TERMIOS in the makefile.]
 717
 718     You can invoke the debugger in two ways:
 719
 720       a. To debug a given glyph program in a given font, type
 721
 722         fdebug glyph_number pointsize fontfile[.ttf]
 723
 724       b. To debug a given font's CVT program, type
 725
 726         fdebug --cvt pointsize fontfile[.ttf]
 727
 728     Type `?' while running fdebug for a list of key bindings.
 729
 730
 731 IV. Compiling the Pascal source
 732 ===============================
 733
 734   This section deals  with the compilation of the  Pascal version of
 735   the FreeType engine, whose source  code is located in the `pascal'
 736   directory.
 737
 738   Note that the Pascal version is more limited than the C one, as it
 739   lacks the following `features':
 740
 741   - Extensions are neither supported nor provided in Pascal.
 742
 743   - The  interpreter  is more  pedantic  than  the  C one  and  will
 744     probably not work with many broken glyphs.
 745
 746   - It doesn't compile on old Turbo Pascal (TP 6.0 is a minimum), as
 747     it uses inline assembly code.
 748
 749   Other than that, the Pascal version supports charmaps and the name
 750   table correctly since the 1.3 release.
 751
 752 ********************************************************************
 753 *                                                                  *
 754 *  AN IMPORTANT NOTE REGARDING TURBO AND BORLAND PASCAL USERS      *
 755 *  ==========================================================      *
 756 *                                                                  *
 757 *  Programs compiled with TP6 and BP7 might not be able to run on  *
 758 *  fast machines!                                                  *
 759 *                                                                  *
 760 *  Usually, the program aborts immediately with a message like     *
 761 *                                                                  *
 762 *    Runtime error 200: Divide by zero at xxxx:xxxx                *
 763 *                                                                  *
 764 *  The  bug is  located in  the runtime's  initialization routine  *
 765 *  used to compute the machine's speed.  It does so by dividing a  *
 766 *  value taken through the BIOS timer by a small constant.         *
 767 *                                                                  *
 768 *  On fast machines,  the result exceeds 16 bits,  which causes a  *
 769 *  CPU  exception/interrupt.    The  latter  is   caught  by  the  *
 770 *  runtime's  exception handlers which  aborts the  execution and  *
 771 *  prints the above message.                                       *
 772 *                                                                  *
 773 *  We don't know anything that can be done to fix this bug, as it  *
 774 *  would need a recompilation of a version of the Borland runtime  *
 775 *  initialization code.                                            *
 776 *                                                                  *
 777 ********************************************************************
 778
 779   Due to lack  of time, the library could not  be fully tested under
 780   TP6 or BP7.
 781
 782
 783   1. Compiling the library
 784   ------------------------
 785
 786     The library itself is  located in `pascal/lib'.  You can compile
 787     it  very simply  by invoking  your Pascal  compiler on  the file
 788     `freetype.pas'.
 789
 790     As always with Pascal, dependencies are resolved automatically.
 791
 792
 793   2. Compiling the test programs
 794   ------------------------------
 795
 796     The test programs are located in `pascal/test'.  You will mainly
 797     find there the following:
 798
 799       lint - A TrueType  glyph  loading checker.  This  test program
 800              will simply  load each glyph  in a font file  and check
 801              for errors  in its hinting  programs.  It is  useful to
 802              find broken glyphs in fonts.
 803
 804       view - A  simple TrueType glyph viewer.  Shows  all the glyphs
 805              within a  given font file  on a graphics  screen.  Only
 806              works under  DOS (with  Borland Pascal) and  OS/2 (with
 807              Virtual Pascal).
 808
 809       timer - A   simple  benchmark   program   for  the   scan-line
 810               converter.  Similar to the C `fttimer' test program.
 811
 812       debugger - A  TrueType bytecode  debugger.  This  one  must be
 813                  compiled with the Turbo  Vision library.  It uses a
 814                  rather advanced  windowed interface to  display the
 815                  glyph  program and  their execution.   It  can also
 816                  display the current glyph  in a graphics window.  A
 817                  bit rough  but extremely useful  to the development
 818                  of FreeType.
 819
 820       dump - A TrueType  metrics checker.  This  test program simply
 821              checks that the hinted  width of each glyph corresponds
 822              to  the one  found in  the TrueType  `hdmx'  table when
 823              present.  This  program is  now obsolete and  should be
 824              ignored.
 825
 826     As  always,  simply invoke  the  root  source  file to  make  an
 827     executable automatically -- don't  forget to include the path to
 828     the FreeType unit as described in section III.1.
 829
 830
 831   3. Porting the library to a different Pascal compiler
 832   -----------------------------------------------------
 833
 834     The Pascal  sources use inline assembly to  implement the 64-bit
 835     computation  routines  needed  by  the  TrueType  engine.   This
 836     release  comes  with various  versions  of  the `ttcalc'  inline
 837     assembly.
 838
 839     These files are (within `pascal/lib'):
 840
 841       ttcalc1.inc: for Turbo and Borland Pascal & Delphi 1 (16-bit)
 842       ttcalc2.inc: for Virtual Pascal (32-bit)
 843       ttcalc3.inc: for Delphi 2 & 3 (untested on Delphi 4 & 5)
 844       ttcalc4.inc: for Free Pascal on a i386 (32-bit)
 845
 846     Note that in order to port  the Pascal source to a new compiler,
 847     one has to:
 848
 849     a. Write a specific  version of `ttcalc?.inc' for the compiler's
 850        inline assembly.
 851
 852        Be sure  to respect the compiler's assembler  syntax, as well
 853        as  its  parameter-passing  function interface,  i.e.,  which
 854        registers and/or  stack slots are  used to pass  arguments at
 855        function call.
 856
 857     b. Add some lines to detect your compiler in `ttconfig.inc'.
 858
 859        This  file  contains some  tests  to  define  macros used  to
 860        determine  which compiler  is  used.  These  macros are  used
 861        later in  `ttcalc.pas' in order to select  the correct inline
 862        assembly file to use.
 863
 864        See the source files for more details.
 865
 866     c. Add an include to the new `ttcalc?.inc' in `ttcalc.pas'.
 867
 868        Make   this   according   to   the   compiler   detected   in
 869        `ttconfig.inc'.
 870
 871        See the source files for more details.
 872
 873     d. Submit your changes to the FreeType Developers list.
 874
 875        In order to see them added  to the next release of the Pascal
 876        engine.
 877
 878
 879 --- end of INSTALL ---