The FreeType compilation HOWTO


Introduction

I. Quick compilation

  1. Unix
  2. OS/2
  3. MS-DOS
  4. Amiga

II. Package layout

  1. The library
  2. The test programs
  3. ttf2bdf

III. Compilation steps

  1. Compiling the library
  2. Compiling the graphics subsystem & driver
  3. Compiling the test programs

IV. Test programs usage and additional notes

  1. zoom
  2. lint
  3. view
  4. timer
  5. ftdump
  6. ftstring

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

Introduction:

This  file describes  the steps  that are  necessary to  compile the
files  found in this  package.  Section  I contains  instructions to
compile   the    package   'out-of-the-box'   on    a   variety   of
platforms/compilers.  Section  II gives  the detailed layout  of the
package's  files,   a  necessary  understanding   for  the  detailed
compilation steps given in section III.

This package, known as the FreeType Public Release, contains several
things:

 - the 1.0 release of the  FreeType library, contained in  the 'lib'
   directory. The library  is written in portable ANSI  C. It should
   compile fine with any type of ANSI C compiler.

   Note  that 16  bit compilers  are  not fully  supported yet  (the
   library compiles, though), as some problems may arise  with  very
   large point sizes, or large font files.

 - a  set of  test programs,  found  in the  directory 'test'  which
   provide:

    - A  small  graphics  subsystem  used  to  display  the  bitmaps
      produced by the  library, on a great variety  of systems.  The
      subsystem is made of several files:

        - a  set of  common files  (gmain.h, gmain.c,  gdriver.h and
          gevents.h)

        - some  system-specific   drivers  used  to   implement  the
          interface found in 'gdriver.h' and 'gevents.h' (gfs_dos.c,
          gfs_os2.c, gwin_x11.c, etc).  The X11 driver is located in
          "test", while others  are located in architecture-specific
          directories (example: "test/arch/os2/gpm_os2.c").

        - "common.h/c" provide the 'basename' and 'getopt' functions
          for systems which do not provide it already.

    - Several test  programs which use the library  and the graphics
      subsystem:

        - ftzoom:   A simple glyph viewer.  Supports composite glyph
                    loading, font smoothing.

        - ftlint:   A  simple glyph  instruction verifier.   Used to
                    execute all glyphs  instructions found in a font
                    file at a given  ppem size.  Useful to find bugs
                    in the library and/or font files.

        - ftview:   A simple  font viewer.  Supports  font smoothing
                    and hinting!

        - fttimer:  Performance   timer   used   to  benchmark   the
                    scan-line   converter.   Supports   display  and
                    font-smoothing.  This is _not_ an indiciation of
                    FreeType's overall performance !

        - ftdump:   A very simple font information dumper.

        - ftstring: A  simple program to  display a given  string or
                    message in a given  font, at a given point size.

  - a  conversion  tool, called  ttf2bdf,  which  uses the  FreeType
    library to produce bitmaps in  BDF format (used with X Windows),
    located in the directory "tools/ttf2bdf/".  It is only supported
    on Unix for now..

  - another conversion tool, called ttf2pk, used to convert TrueType
    fonts to TeX's PK font format, in "tools/ttf2pk"

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

I. Quick compilation:

  NOTE: With  the exception of Unix,  all system-dependent makefiles
        and  configuration  files  are  located in  the  directories
        lib/arch/platform/ and test/arch/platform/.

  1. Unix:

    We provide  a 'configure' script that  will automatically create
    configuration and Makefile files in all relevant directories.

    Graphics display is performed through X11 only, which means that
    the performance measured by 'timer' with display 'on' should not
    be considered as 'informative'.

    You  will need gcc  and GNU  make to  compile currently.   It is
    however  possible  to   compile  everything  with  another  ANSI
    compiler by modifying only the Makefiles.

    Go to your 'freetype' directory, then type './configure'.

    After several seconds, you'll be able to launch GNU make (either
    'make' or 'gmake') to build the package.  You'll then be able to
    run the test programs with your font files.
    
    Please jump to section IV for usage descriptions.

    If not using  gcc and gmake, please read sections  II and III to
    learn how to compile the package for your own system.


  2. OS/2:

  o Note that PM display programs  like  'ftview',  'ftzoom',  etc..
    hide  their output.  To view messages (and error logs), redirect
    stderr with a command like :

      "fttimer -v arial 2> log.txt"

    instead of

      "fttimer -v arial"


  o Note that you  must  be  located  in  the  "test" directory when
    invoking one the three following makefiles :


    makefile.emx: This file must be  used with GNU make and gcc/emx.
                  It builds a version  of the test programs that use
                  a PM  display window (xxx.exe) and  a version that
                  uses the full-screen display driver (xxxfs.exe).

                  To use it, go to your 'test' directory, then type:

                     make -f arch/os2/makefile.emx


    makefile.icc: This  file  must  be used with Visual Age C++.  It
                  now supports  full-screen  and  PM  display.  Note
                  that the library is  compiled  with  optimizations
                  OFF,  due to a compiler bug which make icc compile
                  the file 'ttraster.c'  erroneously.  This bug will
                  be reported to IBM.

                  To use it, go to your 'test' directory, then type:

                     nmake -f arch\os2\makefile.icc


                  This file must be used with Watcom.   If  supports
                  PM  and fullscreen output alike.  To use it, go to
                  your 'test' directory, then type :

                     wmake -f arch\os2\makefile.wat


    In addition, the following make targets can be invoked :

      * clean     : erases all object and library files, only
                    keeping the executables in place

      * distclean : same as 'clean', but also erase executables
    

    For other compilers, please read sections II and III to know how
    to compile  the package on  your system.  You're welcome  to add
    new makefiles and  send them to us, as long  as they respect our
    current location conventions.


  3. MS-DOS and clones:

    We  provide  one  makefile  for  the  gcc  compiler  for  MS-DOS
    (emx/djgpp).

    Please  read the  note  relative  to  makefile.gcc  in the  OS/2
    section above, replacing 'arch/os2' by 'arch/msdos'.

    There is only one full-screen display driver for MS-DOS.

    For other compilers, please read sections II and III to know how
    to compile  the package on  your system.  You're welcome  to add
    new makefiles and  send them to us, as long  as they respect our
    current location conventions.


  4. Amiga:

    You will need gcc and GNU make for Amiga to compile the package.
    Go to the 'test' directory, then type:

      make -f arch/amigaos/makefile.gcc

    The arch/amigaos  contains two display drivers  (full screen and
    windowed).  The default driver is the windowed one, but this can
    be changed easily in the makefile.

    For other compilers, please read sections II and III to know how
    to compile the package on your system. You're welcome to add new
    makefiles  and send  them to  us, as  long as  they  respect our
    current location conventions.

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

II. Package Layout:

  Here is  a more  thorough description of  the package's  files and
  layout.

 # The 'test' directory:

    Contains the graphics subsystem's common files.

       gmain.h
       gmain.c
       gdriver.h
       gevents.h

    where 'gdriver.h'  is the interface that must  be implemented by
    all display drivers used by the subsystem.

    Note that the  graphics subsystem is _not_ part  of the library,
    it's just a  way we found to display  the engine's production on
    several systems.

    The  platform-specific driver (which means the implementation of
    "gdriver.h") is found  in the architecture-dependent directories
    of the form :

       test/arch/<platform>

    where <platform> can be either "msdos", "amiga", "os2", "unix",
    etc..

    We  provide  several  display  driver  implementations  on  some
    platforms:

       test/arch/os2/gfs_os2.c  - full-screen OS/2 driver
       test/arch/os2/gpm_os2.c  - PM OS/2 driver

       test/arch/amigaos/gfsamiga.c  - full-screen Amiga driver
       test/arch/amigaos/gw_amiga.c  - windowed Aniga driver

       test/arch/msdos/gfs_dos.c  - full-screen DOS driver

       test/arch/unix/gwin_x11.c  - windowed X11 driver

    You'll need to compile one of these drivers for your system, and
    link  it  to  the  test  programs  together  with  the  compiled
    'gmain.c'.

    It also contains several test files:

       common.c   -- common subroutines uses by all test programs
                  -- this file defines and implement the functions
                  -- "basename" and "getopt" if they're not provided
                  -- by your environment

       display.c  -- a small lib used by several test programs used
                  -- to 

       ftview.c   -- font viewer
       fttimer.c  -- performance tester
       ftzoom.c   -- simple glyph viewer
       ftstring.c -- simple string text generation program

       ftlint.c   -- font instruction checker. console mode only
       ftdump.c   -- simple font dumper - console mode only

       fdebug.c   -- short debugger;  you need to  compile ttdebug.c
                  -- and  ttins.c in  the c/lib  directory  with the
                  -- DEBUG  constant defined  to use  it.  Text mode
                  --  only.  Makes sense for development only. avoid
                  -- completely if you don't need to hack the engine.


 # The 'lib' directory:

    Contains the engine's source code.

    The engine is made  of  several  components, each one having its
    name beginning with a 'tt'  prefix  like  'ttmemory',  'ttfile',
    'ttraster', etc.

    All components rely on the 'freetype.h' interface file (which is
    the   engine's  interface  to  be  used  by  all  clients),  and
    'ttconfig.h'(which is used to generate configuration
    macros).

    Note  that   'ttconfig.h'  relies  heavily  on   a  file  called
    'ft_conf.h'  that  contains information  related  to the  target
    platform.  The  ft_conf.h file  is generated by  the 'configure'
    script  under Unix.   For other  systems, it  is located  in the
    lib/arch/system/ directory:

       lib/arch/os2/ft_conf.h
       lib/arch/amigaos/ft_conf.h
       lib/arch/msdos/ft_conf.h

    It should be pretty obvious  to create a new ft_conf.h file from
    a current one: just copy  it and define/undefine the macros that
    are relevant to your platform.

 # The 'lib/extend' directory:

    This directory  contains the current core  engine extensions. To
    know  more  about  extensions,  read  the user  guide  found  in
    "docs/user.txt".

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

III. Detailed Compilation Steps:

  You must  perform the following  steps to compile this  package by
  hand:

  1. Compile the library:

     with gcc, go to the 'lib' directory, then type

       gcc -c -Wall -ansi -pedantic -O2 tt*.c -I.. -Iextend

     forUnix systems or

       gcc -c -Wall -ansi -pedantic -O2 tt*.c -Iarch/<system> -Iextend

     for other platforms.

     The flags mean:

       -c        : compile only.

       -Wall     : display all warnings during compilation.

       -ansi     : check for ANSI conventions.

       -pedantic : be _very_ pedantic when checking ANSI convention.

       -O        : optimization level.

       -I..      : add  '..'  or 'arch/system'  as  an include  dir.
                   This  line is  requested  to give  access to  the
                   'ft_conf.h' file.


  2. Compile the graphics subsystem:

     a. compile the subsystem in the 'test' dir:

       gcc -c -ansi -Wall gmain.c

     b. compile the display driver in the 'test' dir:

       gcc -c -Wall arch/unix/gwin_x11.c -o gdriver.o

     for Unixish systems (see note below) or

       gcc -c -Wall arch/system/yourdriver.c -o gdriver.o

     for other platforms.   Of course, don't forget to  add the path
     to your system's display libraries.

     NOTE: You may need to  include the path to your 'ft_conf.h' and
           to the  library directory for some  drivers (for example,
           the X11 driver relies on 'tttypes.h', which relies itself
           on 'ft_conf.h').


  3. Compile the test programs in the 'test' directory:

     Usually with something like:

        gcc -ansi -Wall -O testprogram.c \
            ../lib/*.o gmain.o gdriver.o \
            -I<path_to_ft_conf.h> -I../lib

     with additional libraries ('\' indicate a line continuation).

     Have a look  at the supplied makefiles to get  a better idea of
     the required flags/commands.

     You should now be able to run the test programs.

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

IV. Test programs usage:

  NOTE: All  test programs having  a graphic interface use  the same
        key convention:

    x :   fine counter_clockwise rotation (ftzoom only)
    c :   fine clockwise rotation         (ftzoom only)

    v :   fast counter_clockwise rotation (ftzoom only)
    b :   fast clockwise rotation         (ftzoom only)

    h :   toggle hinting on/off

    + :   fast scale up
    - :   fast scale down
    u :   fine scale up
    j :   fine scale down

    l :   go to next glyph
    k :   go to previous glyph

    o :   go to tenth next glyph
    i :   go to tenth previous glyph

    9 :   go to hundredth next glyph (useful for CJK fonts)
    0 :   go to hundredth previous glyph

    q :
  ESC :   exit

  These  keys  were  chosen   because  they  are  available  on  all
  platforms.  Note also that each program uses only a subset of this
  key map.


  1. FTZoom:

       'ftzoom'  is  a  very   simple  glyph  viewer  that  supports
       font smoothing.  Its usage is:

          ftzoom [-g] [-p platform -e encodingID] fontfilename

       For example:

         ftzoom arial.ttf             to show the glyphs found
                                      in the Arial font
         ftzoom -g times.ttf          to show smoothed version of
                                      Times's glyphs.
         ftzoom -p 3 -e 1 uwjmg3.ttf  use cmap for platform 3,
                                      encoding ID 1 for this Japanese
                                      font.
  2. FTLint:

       FTLint is used to execute all glyphs instructions found in  a
       font file at a given char size size.  Its usage is:

          lint pointsize fontfilename [fontfilename] ...

       For example:

          lint 12 arial.ttf
          lint 15 times.ttf

       It reports error  codes and faulty glyph numbers.   This is a
       console tool that doesn't need the graphics subsystem.

       It's  a  production  tool,  so  don't get  surprised  to  see
       numerical   error   codes   (the   list  is   in   the   file
       'lib/freetype.h' anyway).

       NOTE: Trying to hint at sizes smaller than 7 is irrelevant.

  3. FTView:

       A font  viewer that supports hinting and  font smoothing. Its
       usage:

          ftview [-g] pointsize fontfilename

       like in:

         ftview 12 arial.ttf       show the hinted Arial at size 12pt.

         ftview -g 15 timesi.ttf   show the hinted and font-smoothed
                                   Times at size 15pt.

       Note  that it  is possible  to change  the point  size during
       display  with the  keys 'u',  'j', '+'  and '-'.  It  is also
       possible to  browse the  whole glyph set  with the  'k', 'l',
       'i', 'o', '9' and '0' keys (see key map above).

       The  OS/2  PM  driver  comes with  an  additional  magnifying
       window.   The magnified  zone is  set with  the  mouse, while
       scale is changed with the help of 'PageUp' and 'PageDown'.

       Note1: the engine uses the font's CVT program to determine at
              which size to enable  or disable glyph hinting.  Don't
              be surprised to see unhinted glyphs at sizes < 7pt.

       Note2: vertical drop-out control has been added to the gray  
              scaling renderer. As a consequence, the library doesn't
              produce unpleasant results at small ppems with badly  
              hinted glyphs.   

  4. FTTimer:

       This program  is used to  benchmark FreeType's scan-converter
       (the  component in  charge of  translating a  vectorial shape
       description  into a bitmap).   It does  so in  preloading all
       glyphs  from a  font file,  then  rendering them  as fast  as
       possible  in a 640x450  buffer.  The  glyphs are  rendered at
       size 400pt / 96dpi, which is _quite_ big.

       Its usage is:

          timer [-g] [-v] fontfilename

       where

          -g : asks for  gray-level rendering at  size 200pt instead
               (a.k.a. font-smoothing)

          -v : asks  for the display of the  produced bitmap. Beware
               that  display slows  things down  (display on  X11 is
               _terrible_, especially with  gray-levels, but this is
               not a problem for us :-).

       Note  that  the  returned  numbers  are  not  a  becnhmark of
       FreeType's overall  performance  !!   Only  of  the scan-line
       renderer (which seems quite fast, apparently :-)

       When comparing measured  performances across machines, please
       only consider the undisplayed  ones.  We're interested in all
       kinds of results (please provide the following information:

           font file
           number of rendered glyphs
           render time
           total time
           glyphs / s
           processor type
           CPU clock

           and compiler used  (with optimization involved)! This can
           make a great difference!

           etc.)

  5. ftdump:

       This program  is a very  simple font dumper.  In  its current
       incarnation,  it  will  only  output  a  font's  name  table,
       character encoding maps IDs and total memory consumption.

       The "total memory  used" reported is the amount  that is used
       by the  engine to load one  face, with one  instance (a point
       size).

       Each  additional  instance  takes  only a  fraction  of  that
       amount, and is labeled by "instance object".  As you can see,
       FreeType isn't really greedy.

       Usage:   ftdump fontpathname[.ttf|.ttc]


  6. ftstring:

       This  program demonstrates  string text  generation.  It only
       displays a given  message on the screen, and  lets you resize
       it with the classic key bindings "u", "j", "+" and "-".

       Usage:

          ftstring  ptsize  fontname[.ttf|.ttc]  [message_string]

       If  the message  is omitted,  it will  revert to  the classic
       typographic test sentence:

          The quick brown fox jumps over the lazy dog

       which is made of all letters of the English alphabet.

       Ftstring only  works with font  files that contain  a Unicode
       character  mapping  table (either  Windows  Unicode or  Apple
       Unicode).  For  the moment, the  message can however  only be
       written in ASCII, as accents aren't supported yet.

--- end of HOWTO ---
