The FreeType compilation HOWTO


Introduction

I. Quick compilation

  1. Unix
  2. OS/2
  3. Dos
  4. Amiga

II. Package layout

  1. The library components
  2. The graphics subsystem
  3. The graphics drivers
  4. The test programs

III. Compilation steps

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

IV. Test programs usage and additionnal notes

  1. zoom
  2. lint
  3. view
  4. timer

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

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 FreeType Alpha Release 4, contains several things:

 - an alpha version of the FreeType library, contained in the 'c/lib'
   directory. The library is written in ANSI C and portable. It should
   compile OK with any type of ANSI C compiler. Note that 16 bit compilers
   are not fully supported yet... (the library compiles though)

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

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

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

I. Quick compilation:

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

  1. Unix:

    We provide you with 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.

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

    After several seconds, you'll be able to type '(g)make' 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 you with two makefiles for OS/2, located in c/arch/os2.
    Note that you must be located in the 'c' 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. Note that display with 'timer'
                   doesn't work there.

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

                     make -f arch/os2/makefile.emx

                   The makefile can easily be changed to use a
                   different fullscreen display driver.

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

                   You need nmake. Go to the 'c' 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.

    NOTE:  For the PM driver with emx, you might need to use the command
           'emxbind -ep view.exe' to be able to use the font viewer
           correctly...

  3. DOS:

    We only provide one makefile for the gcc/emx compiler for 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 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 c directory, then type:

      make -f arch/amigaos/makefile.gcc

    The arch/amigaos contains two display drivers (fullscreen 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 'c' 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 susbsystem 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 'c' directory. For all other platforms, the drivers are
    located in architecture dependent directories of the form:

       c/arch/system

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

    We provide several display driver implementations on some platforms:

       c/arch/os2/gfs_os2.c  - fullscreen OS/2 driver
       c/arch/os2/gpm_os2.c  - PM OS/2 driver

       c/arch/amigaos/gfsamiga.c  - fullscreen Amiga driver
       c/arch/amigaos/gw_amiga.c  - windowed Aniga driver

       c/arch/msdos/gfs_dos.c  - fullscreen DOS driver

    You'll need to compile one of these drivers for your system, and
    link it to the test programs, 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

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

 # The 'c/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 c/arch/system/ directory:

       c/arch/os2/ft-conf.h
       c/arch/amigaos/ft-conf.h
       c/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 'c/debugger' directory:

    This directory contains a glyph instruction debugger. It is a port
    of the Pascal debugger which uses the Turbo Vision toolkit that
    Borland recently released freely.
    (for more info, try http://brooks.wvn.wvnet.edu/tvhome/)

    The C version has only been tested with the Linux TV port;
    the Pascal version works with BP7 and Virtual Pascal.

 # The 'c/lib/arch/system' directories:

    For now, these directories only contain makefiles used to build
    the library, and only the library. They are invoked by the
    package makefiles located in the 'c/arch/system' directories.

    You can modify them if you want to change some compilation options.

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

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 'c/lib' directory, then type

       gcc -c -Wall -ansi -pedantic -O tt*.c -I..           (on Unix)

     or

       gcc -c -Wall -ansi -pedantic -O tt*.c -I../arch/system
                                                            (on other systems)

     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 on

       -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 'c' dir:

       gcc -c -ansi -Wall gmain.c

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

       gcc -c -Wall gwin_x11.c -o gdriver.o   on Unix (see note below)

     or

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

     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 'c' directory:

     usually with something like:

        gcc -ansi -Wall -O testprogram.c lib/*.o gmain.o gdriver.o \
            -I./path_to_ft-conf.h -Ilib

     with additional libraries.

     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

  ESC :   exit

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


  1. Zoom:

       Zoom is a very simple glyph viewer that supports composite
       glyph loading as well as font smoothing. It 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.


       Some features are broken still...

  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

       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 'c/lib/tterror.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 12 pts.

         view -g 15 timesi.ttf   show the hinted and font-smoothed Times
                                 at size 15 pts.

       Note that it is possible to change pointsize 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 keymap 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'.

       Beware:  Do not try to hint glyphs at sizes under 7 points.
                This usually creates ugly artifacts and can even produce
                a divide by zero error. This is a technical issue which
                is completely intrinsic to TrueType (hinting is usually
                disabled at sizes < 7 ppem).

  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 rendererd at size 400 pts, which is _quite_ big.

       Its usage is:

          timer [-g] [-v] fontfilename

       where

          -g : asks for gray-level rendering at size 200 pts 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 performanced across machines, please
       only consider the undisplayed ones. We're interested in all kinds
       of results (please give them the following information:

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

           etc.)

       Note that display doesn't work with the OS/2 PM driver yet.
       You can use the fullscreen driver to activate it instead...
