
		   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  Public Release, contains
  several  things  which  are  best  described  by  the  directories
  containing them:

  - `lib'

    Contains the 1.3 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 ---
