The FreeType OS/2 Compilation HowTo

Contents

Introduction
I.   Building the library
  1. Quick Compilation
  2. Manual compilation
  3. Notes
II.  Building other parts of the package
  1. Test programs
  2. Other contribs
III. Troubleshooting



Introduction
============

This file  describes the compilation  of the FreeType package  on an
OS/2 system.  It comes with makefiles for the following compilers:

  - gcc/emx with GNU make

  - icc with nmake (Visual Age C++)

  - wcc386 with wmake (Watcom -- tried with 10.6)

  - gcc/emx with dmake


NOTE:

  You're advised  to jump  to section  II.1 if you  want to  run the
  FreeType test/demo programs as quick as possible.



I. Building the library
=======================


1. Quick Compilation
--------------------

  The easiest  way to compile  the library on  OS/2 is to go  to the
  directory `freetype/lib'.  Then type, depending on your compiler,

    gcc/emx:     make  -f arch/os2/makefile.emx
    gcc/dmake:   dmake -f arch/os2/makefile.dm

    icc:         nmake -f arch\os2\makefile.icc
    wcc386:      wmake -f=arch\os2\makefile.wat

  This should build the `libttf.a' or `libttf.lib' library files.

  You can also use the following targets:

    debug     - Makes  a development version  of the  library.  Only
                useful for FreeType developers and hackers.

    clean     - Cleans all intermediate  object files created during
                compilation.  Keeps  all library and  executables in
                place.

    distclean - Cleans everything,  leaving the directories  as they
                were before the compilation.


2. Manual compilation
---------------------

  Here  are explained  the  steps  that are  required  to compile  the
  FreeType _library_ (and only this one) by hand.

  Unlike previous  versions, FreeType 1.1 and above  can be compiled
  in two modes, called `debug mode' and `single object mode'.
     
  Debug mode is simply the normal way of compiling C programs, i.e.,
  each  `*.c' file  is compiled  into an  individual  `*.obj' object
  file, and all  of them are linked together  into an archive (i.e.,
  `*.lib' library).

  Single object mode is slightly different: all C files are included
  in a single source during compilation, resulting in a single final
  object  file for  the core  library.   This has  the advantage  of
  letting  optimizing compilers  do  more global  work,  as well  as
  getting rid of all external  symbols which are used solely for the
  purpose of components interfacing.

  In both  modes, you  need to include  the following paths  to your
  makefile/command line:

    the location of all `tt*.[hc]' files
    the location of system-specific files

  For  example,  if  you   are  compiling  from  the  `freetype/lib'
  directory, you can type for debug mode something like

    gcc -c -I. -Iarch/os2 tt*.c arch/os2/os2file.c

  to  compile all required  files into  object ones.   Then assemble
  them in a library with `ar' or `implib'.

  In single  object mode,  you only need  to compile the  file named
  `freetype.c'  which is  located in  `freetype/lib/arch/os2'.  From
  the same directory as before, one would type:

    gcc -c -I. -Iarch/os2 arch/os2/freetype.c

  You    can    also    compile    the   extensions    located    in
  `freetype/lib/extend' separately  from the base  engine.  You will
  need to include  the same paths as before, though;  be sure to add
  the path to the `extend' directory, like in

      gcc -c -I. -Iarch/os2 -Iextend extend/*.c



II. Building other parts of the package
=======================================


1. Test programs
----------------

  The test  programs are located  in `freetype/test'.  Most  of them
  use a  tiny graphics  sub-system which is  simply used  to display
  bitmaps and pixmaps  in a windows on a  variety of platforms.  The
  OS/2 version comes in two flavors: PM and full-screen.

  To compile them, you must be in the `freetype/test' directory, and
  invoke the makefile in arch/os2.  For example:

    nmake -f arch\os2\makefile.os2


  NOTE 1:

    This will automatically invoke the library makefile for you!

  NOTE 2:

    The test programs come in two flavors, distinguished by the `fs'
    suffix appended to their name.  For example:

      ftview   (PM version)
      ftviewfs (Full Screen version)

  The full-screen version is there mainly for debugging purposes.

  NOTE 3:

    For now, the  graphical test programs only run  on the following
    platforms: Unix, OS/2, Dos, Amiga, and Windows.

    The library,  being pure  ANSI-C, can be  used on any  system to
    generate bitmaps and pixmaps.


2. Other contributions
----------------------

  You may find  some other contributions to the  FreeType project in
  the `freetype/contrib'  directory.  Each of  these programs should
  have  its  own Makefiles  and  documentations.   Also check  their
  licenses, as  the programs  not necessarily distributed  under the
  FreeType one.   You are invited to port  the non-OS/2 applications
  to OS/2.

  For OS/2,  you will find the  source code for  the FreeType/2 font
  driver   in   `freetype/contrib/os2'.    Read  its   documentation
  carefully before  trying to compile  it, as it certainly  won't be
  easy.



III. Troubleshooting
====================

  There is only one important point on OS/2:

  `The test program crashes with anti-aliasing on!'

  It  has been  discovered  that  some versions  of  Visual Age  C++
  contain  a  bug  which  miscompiles the  anti-aliasing  source  in
  ttraster.c, hence resulting in a  page fault when trying to render
  a pixmap  in the engine.   Apparently, not all  levels/versions of
  the  compiler   contain  the  bug.   You'll   notice  the  problem
  immediately (page fault :-).

  Please apply the  most recent fixpack to your  Visual Age C++ copy
  in  order to  get rid  of  it (newer  fixpacks seem  to solve  the
  issue).


Good luck!


--- end of os2.txt ---