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 Beta,  contains several
things:

 - a beta  version 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).

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

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

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

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

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

        - timer:    Performance   timer   used   to  benchmark   the
                    scan-line   converter.   Supports   display  and
                    font-smoothing.

        - 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.
                    Note  that  the advance  width  is not  computed
                    correctly yet in some cases.

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

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

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.

    NOTE: beware that 'view' is often  used as an alias for the 'vi'
          editor  on  some  Unix  systems.  In these  cases,  it  is
          preferable  to type './view  ppem fontfile.ttf'  to invoke
          the program.

          If you  end up stuck in  'vi', type ':q' or  ':q!' to exit
          it...


  2. OS/2:

    We  provide two  makefiles for  OS/2, located  in test/arch/os2.
    Note  that you  must be  located  in the  "test" directory  when
    invoking these files.

    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

                  Note  that PM display  programs like  'timer' hide
                  their output. To view the messages, go to the OS/2
                  prompt and redirect stderr with

                      timer  -v  arial 2> log.txt

                  Then view "log.txt"

    makefile.icc: This  file must be  used with Visual Age  C++.  It
                  uses  the full-screen  display  driver (PM  hasn't
                  been tested yet) but can be easily modified.

                  You need  nmake. Go to the  'test' directory, then
                  type:

                     nmake arch\os2\makefile.icc

    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  only  provide one  makefile  for  the  gcc/emx compiler  for
    MS-DOS.  Please read the  note relative  to makefile.emx  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  Unix X11  windowed  driver is  called  'gwin_x11.c' and  is
    located in  the 'test' directory.  For all  other platforms, the
    drivers are located in architecture dependent directories of the
    form:

       test/arch/system

    where 'system' can be 'os2', 'amigaos' or 'dos' currently.

    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

    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:

       view.c     -- font viewer
       lint.c     -- font instruction checker.  Text mode only.
       timer.c    -- performance tester
       zoom.c     -- simple glyph viewer
       ftdump.c   -- simple font dumper
       ftstring.c -- simple string text generation program

       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.

 # 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
    doomed to become the only  high level interface to the library),
    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

     for Unixish 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 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 (not implemented yet)
    c :   fine clockwise rotation (not implemented yet)

    v :   fast counter_clockwise rotation (not implemented yet)
    b :   fast clockwise rotation (not implemented yet)

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

    h :   in view,  this key disables glyph hinting.  This is useful
          to spot incorrect glyphs in  a broken font file (or simply
          when the  font file has a "feature"  that isn't recognized
          by the interpreter yet... damn TrueType specs!)

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

       Zoom is  a very simple  glyph viewer that  supports composite
       glyph loading as well as font smoothing. Its usage is:

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

       For example:

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


  2. Lint:

       Lint is  used to execute  all glyphs instructions found  in a
       font file at a given ppem 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. View:

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

          view [-g] pointsize fontfilename

       like in:

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

         view -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: the  current  gray-scaling  algorithm  doesn't use  an
              intermediate bitmap to produce filtered pixmaps.  This
              implies (for  some technical reasons)  that it doesn't
              perform  horizontal dropout  controls.   This results,
              for  badly  hinted glyphs,  in  disappearance of  some
              horizontal stems at small sizes.

              This is  more a  feature than a  bug, as  its solution
              lies in changing the test programs, and not the engine
              itself.  We'll fix them in the final FreeType release.

  4. Timer:

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

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