
                   The FreeType compilation guide

  This file gives detailed information on how to compile and install
  this release of FreeType on your system.


Table of contents
-----------------

  I. Introduction

 II. Compiling and installing the Pascal library

    1. Compiling the library
    2. Configuration of the library
    3. Compiling extensions
    4. 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. Porting the library to a different Pascal compiler

--------------------------------------------------------------------



I. Introduction
===============

  This package,  known as the FreeType 1.4  Pascal Release, contains
  several  things  which  are  best  described  by  the  directories
  containing them:

  - `lib'

    Contains the 1.4  release of the Pascal version  of the FreeType
    library.  It is written in  "portable" TurboPascal and has  been
    successfully  compiled with  Turbo Pascal  6 and 7, Turbo Pascal
    for Windows 1, Borland  Pascal  7, Virtual  Pascal, Free  Pascal
    and Delphi (1, 2, 3 and 4).

    Note however that some system-specific files are provided, in
    order to provide support for 64-bit arithmetic using inline
    assembler.

    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.

    Also contains a  TrueType font debugger,  that have been heavily
    used  during development to find bugs in the tested  fonts. Note
    that this program  also might not compile on all platform  as it
    needs a graphic sub-system and Turbo-Vision (works on Dos and
    OS/2+Virtual).

  - `docs'

    Contains a set of documentation files that describe the uses and
    (in a partial form) the internals of the FreeType library.


  This  file explains  how  to  compile the  library,  and the  test
  programs on various platforms.


  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.  Of
    course,  one may use  units that  `uses' the  internal  units of
    FreeType to provide similar effects.

  - The  interpreter  is more  pedantic  than  the  C one  and  will
    probably not work with many broken fonts.

  - 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.

 ********************************************************************
 *                                                                  *
 *  AN IMPORTANT NOTE REGARDING TURBO AND BORLAND PASCAL USERS      *
 *  ==========================================================      *
 *                                                                  *
 *  Programs compiled with TP6 and BP7 might not be able to run on  *
 *  fast machines (beyond 180 MHz)!                                 *
 *                                                                  *
 *  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 today's 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.                                            *
 *                                                                  *
 ********************************************************************




II. Compiling the Pascal library
================================


  1. Compiling the library
  ------------------------

    The library itself is located in `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
    by the `making' of the dependant units.

    You can  redirect the  produced units  files (.TPU,  .PPU, .DCU,
    etc.) to some other directory in  order to avoid the `pollution'
    of the `lib' directory.


    The following concepts are also important to build the library.

  2. Configuration of the library
  -------------------------------

    Contrary to the C which have a number of options, there are only
    a few  of them  available  for the  Pascal code  (mainly because
    Pascal compilers are much more homogeneous).

    Tere is a file named `config.inc',  which is in charge to detect
    the compiler used,  in order to toggle various  engine features,
    as well  as tell system-specific information (e.g.,  the size of
    the `Integer' type in bytes, etc).

    There  are  several   compilers  that  are  detected  with  this
    release:  Turbo  Pascal  6 and 7,  Turbo  Pascal  for Windows 1,
    Borland  Pascal 7,  Virtual Pascal,  Free Pascal  and Delphi (1,
    2, 3 and 4). Refer to section IV of this file if you use another
    compiler.


  3. Compiling extensions
  -----------------------

    The  Pascal  version  of  FreeType  does  not  provide  anything
    similar  to  the  C extensions,  because  thanks  to the  `unit'
    mechanism of Turbo Pascal and its clones, it is not necessary to
    rely on such a mechanism.

    If for  any reason  the FreeType API  is not sufficient to cover
    the needs,  then it is quite easy to  write an unit that `uses',
    in addition  to  `freetype.pas',  directly  the inner  units  of
    FreeType.  This way one can:

    - 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

    - 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

    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.

    As a demonstration,  you can take a look  at `ttdebug.pas': this
    unit  provides  the  debugger  direct  access  to many  internal
    variables  and structures of FreeType;  this allows  the code of
    the  debugger  itself, in  the file  `test/debugger.pas',  to be
    protected from the specificities of FreeType.  Note however that
    `lib/ttdebug.pas'  is not  really an  example for  an extension,
    since its needs are rather specific...


  4. 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 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.

    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 compile the  library while $DEFINing
    FT_CONFIG_OPTION_NO_INTERPRETER.  This  can be  achieved through
    the command line (usually with a /D or -D switch).



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 II
  before proceeding.  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.

      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.

      timer - A   simple  benchmark   program   for  the   scan-line
              converter.  Similar to the C `fttimer' test program.

      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).

      write - A simple  TrueType string  renderer.  Similar to the C
              `ftstring' 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.

    As  always,  simply invoke  the  root program  file to  make  an
    executable automatically -- don't  forget to include the path to
    the FreeType units as described in section III.2.


  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 Pascal 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.pas:   the sub-system device-independent implementation
      gevents.pas: the definition  of  the  events  used  by the  test
                   program
      gdriver.pas: the system-specific device interface
      common.pas:  common routines (filename expansion)

    as well  as a system-specific  `graphics driver' located  in a
    `.inc' file.  We provide:

      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.


  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. 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 `lib'):

      ttcalc1.inc: for Turbo and Borland Pascal & Delphi 1 (16-bit)
      ttcalc2.inc: for Virtual Pascal (32-bit)
      ttcalc3.inc: for Delphi (32-bit)
      ttcalc4.inc: for Free Pascal on a i386 (32-bit, AT&T syntax)

    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 ---
