		The FreeType Unix Compilation HowTo

Contents

Introduction
I.   Building the library
II.  Building other parts of the package
III. Successful Build Reports

Introduction:

This file  describes the  compilation of the  FreeType package  on a
Unix system.  Using the 'configure'  script it should be rather easy
to  build the  library.  However,  detailed instructions  on  how to
compile the library manually are given later in this document.


I. Building the library:


1. Quick Compilation

  The easiest  way to  compile the  library on a  Unix system  is by
  using the 'configure' script that comes with it.  Simply go to the
  root directory of the freetype package, then type:

    ./configure

  This runs a script that  will probe your system and detect various
  configuration issues, which are explained later in this document.

  From there, you can simply type

    make

  to invoke compilation of the  whole package.  You can also use the
  following commands:

    make debug     - Make  a  development  version of  the  library.
                     Only   useful  for   FreeType   developers  and
                     hackers.   The default  build should  come with
                     '-g'  (i.e.,  debug info  in  the object  file)
                     already.

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

    make distclean - Clean  everything, leaving the  directories  as
                     they were  before the compilation.  You'll need
                     to  run  './configure'  again  to  be  able  to
                     re-build it.

    make install   - Install  the library files  libttf.a, libttf.la
                     or  libttf.so  to   your  system  library  path
                     (/usr/local/lib by  default).  The path  can be
                     set manually with ./configure.

    make uninstall - Undo a `make install'.
                    

2. Trouble-shooting and simple customization:

  The  make build seems  to fail  on some  Solaris systems.  This is
  mainly  due to  the  fact that  the  test programs  (not the  font
  library itself)  try to use certain libraries  and/or utilities if
  they find  them on your system.   In some cases,  the Sun versions
  are incompatible to the GNU ones.  If you encounter such problems,
  please report them to us so we can try to fix it.

  The configure script and makefiles  that it generates can make use
  of the following things:

    - gettext    - In order  to compile the  internationalized error
                   message string extension, which isn't part of the
                   core  library.  You  can disable  this and  get a
                   clean compile with

                     ./configure --disable-nls


    - libtool    - Used  to  generate  shared  libraries.   You  can
                   disable it by typing

                     ./configure --disable-shared

                   which will generate  and link the FreeType engine
                   as a static library.

                   By default, static compilation is disabled if the
                   configure  script   detects  that  your  compiler
                   and/or    operating   system    supports   shared
                   libraries.  You can ask for static libraries with

                     ./configure --enable-static

  For more configuration options, type './configure --help' to see a
  summary of  what is  possible.  The option  to change  the library
  installation   path    for   'make   install'    is,   as   usual,
  "--prefix=...".  Example:

    ./configure --prefix=${HOME}/local/lib --disable-shared

  To install  a static library (libttf.a) in  '~/local/lib' (after a
  `make install')


3. Manual compilation:

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

  a. Generate a configuration file named "ft_conf.h":

    This file  must contain a certain number  of configuration macro
    declarations which  must fit your system.   The configure script
    generates it  automatically for you,  but you can also  take the
    template  file "freetype/ft_conf.h.in"  and change  it  by hand,
    then save it as "freetype/ft_conf.h".

  b. 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  *.o object
    file, and all of them are linked together into an archive (i.e.,
    *.a library).

    Single  object  mode is  slightly  different:  all  C files  are
    included in  a single source file  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 purposes of components interfacing.

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

      the location of the "ft_conf.h" file
      the location of all "tt*.[hc]" files
      the location of system-specific files,
        i.e., "ttmmap.c" on Unix.

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

      gcc -c -I.. -I. -Iarch/unix tt*.c arch/unix/ttmmap.c

    to compile all required files.   Then assemble them in a library
    with 'ar' (and run `runlib' if necessary).

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

      gcc -c -I.. -I. -Iarch/unix arch/unix/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.   Of course, the
  Unix version uses X11.

  The default "make" builds  all tests programs automatically.  Just
  go the "freetype/test" and  launch the programs when you're there.
  Documentation  on the  test  programs  can be  found  in the  file
  "freetype/test/readme.txt"

  NOTE:

    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.


III. Successful Build Reports:

Nelson  H. F.  Beebe  <beebe@math.utah.edu>  and others  report  the
following successfully builds (with gcc 2.8.1) of freetype-1.1 on 

  DEC Alpha 2100-5/250;          OSF/1 3.2   
  HP 9000/735;                   HP-UX 10.01
  Intel Pentium (200MHz MMX)     Linux 2.0.30
  SGI Challenge L;               IRIX 5.3
  Sun SPARC 20/512;              Solaris 2.6
  Sun SPARC Ultra-2              SunOS 5.5.1
  IBM RS/6000;                   AIX 4.1


There are build problems reported on SunOs 4.x which have the form

  ld: /usr/tmp/cca07291.o: assert pure-text failed: 
  reference to [offset] at f754 in /usr/tmp/cca07291.o

This may be a compiler bug in gcc 2.8.1.

You can work around by just building a static library
(./configure --disable-shared --enable-static --disable-nls).
Maybe make debug will help here, too (untested).


Other successful builds:

  Sun SPARC Solaris 2.5 with Sun C compiler+linker

For updated build reports, please consult our web site:

   http://www.freetype.org

--- end of unix.txt ---
