		The FreeType OS/2 Compilation HowTo


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.

  a. Choose your compilation mode:

    Unlike  previous versions,  FreeType 1.1  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  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're   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'll
    need to include the same paths as before, though.



II. Building other parts of the package:

1. Test programs:

  These  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  simply  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 program come in  two flavors, distinguished from 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 and Amiga.  Windows support is expected
    soon.

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


2. Other contribs:

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

  For OS/2, you'll  find the source code for  the beta 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. Trouble Shooting:

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