               The FreeType MS-DOS 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. Compiler Issues
  1. Special issues of 16-bit MS-DOS
  2. Borland Turbo C v.2.0x



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

This file  describes the  compilation of the  FreeType package  on a
MS-DOS system.  It comes with Makefiles for the following compilers:

  - gcc/emx and gcc/djgpp with GNU make (32 bit)

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

  - gcc/emx with dmake (32 bit)

  - cl with nmake (16-bit Microsoft C -- tried with 7 and VC++ 1.5x)

  - bcc/tcc with Borland make (16-bit Borland C++ and Turbo C)

NOTE:

  You are  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 MS-DOS is  to go to the
  directory `freetype/lib'.  Then type, depending on your compiler:

    gcc/emx,
    gcc/djgpp:   make  -f arch/msdos/Makefile.gcc
    gcc/dmake:   dmake -r -f arch/msdos/Makefile.dm

    wcc386:      wmake -f=arch\msdos\Makefile.wat

    cl:          nmake /f arch\msdos\Makefile.MS  (for versions 6-7)
    cl:          nmake /f arch\msdos\Makefile.VC  (for Visual C++ 1.x)

    tcc:         make  -farch/msdos/Makefile.TC
    bcc:         make  -farch/msdos/Makefile.BC

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

  You can also use the following targets:

    depend    - (for gcc with emx or DJGPP only) Creates a file that
                lists the dependancies. Useful for the developper.

    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.

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

    Note that you  can also select to use  the `debugging' flags for
    your compiler  (instead of  the `optimizing' ones),  by defining
    the `DEBUG' symbol, like in

      nmake /f arch\msdos\Makefile.MS DEBUG=1
      make -farch/msdos/Makefile.BC /DDEBUG
      etc.

    Doing so  will automatically select the debug  target instead of
    the normal mode.

    For 16-bit compilers, you  can also try defining  the `BIGFONTS'
    symbol, to  enable  the  use of  the `huge  pointers'  needed to
    handle some big fonts.  More on this at the end of this file.


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  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/msdos tt*.c

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

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

    cl -c -I. -Iarch/msdos arch/msdos/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

    bcc -c -I. -Iarch/msdos -Iextend extend/*.c


3. Notes
--------

  `char' is always `signed char' in the sources!

  `ttconfig.h'  relies heavily  on  a file  called `ft_conf.h'  that
  contains information  related to  the target platform,  located in
  the  `freetype/lib/arch/msdos/'   directory.   Depending  on  your
  compiler, you may need to slightly edit it.

  We use  gcc as  our reference compiler  for warnings.   This means
  that we use  the `-ansi -pedantic -Wall' flags and  try to get rid
  of warnings  in this situation.  If you're  compiling with another
  compiler, you  may encounter warnings, not errors.   Note that the
  Borland  compilers seem  to  produce lots  of irrelevant  warnings
  (like `potential loss of precision').



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 on a  variety of platforms.  The MS-DOS  version is a very
  basic one that only works in full-screen using standard VGA mode.

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

    nmake /f arch\msdos\Makefile.VC


  NOTE 1:

    This will automatically invoke the library makefile for you!

  NOTE 2:

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

  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  are not necessarily  distributed under
  the FreeType one.

  Most of these contributions are targeted to Unix.  You are invited
  to port them to MS-DOS, and then contribute your improvements.



III. Compiler Issues
====================

  Many comments specific  to a given compiler  are now stored in its
  relevant Makefile's, in the arch/msdos subdirectories.


1. Special issues of 16-bit MS-DOS
----------------------------------

  As usual, 16-bit MS-DOS have some limitations.

  First, and mainly, only the  large model is usable.  The small and
  medium models are  not usable, because the library  uses more than
  64kByte of data; and the  compact model is unusable as well, since
  the code of the library itself is slightly less than 64kByte, thus
  leaving very  small place  for the real  work.  The net  effect of
  that limitation  is that performances are not  very impressive, to
  say the  least (32-bit  DOS extenders  perform usually  three-time
  faster).

  Even  with the  large model,  the rasterizer  is still  limited in
  size, particularly with pixmaps  (that is, with anti-aliasing gray
  levels).

  Another annoying limitation exists with some East Asian fonts that
  have  16,383  glyphs  or   more,  since  an  internal  table  then
  overflows.  We  tried to overcome  this using the  so-called `huge
  pointers', but then good support for these in the run-time library
  is needed.  To enable  this support,  try defining  the `BIGFONTS'
  symbol with the makefile, like using

    nmake /f arch\msdos\makefile.MS BIGFONTS=1
    make -farch/msdos/makefile.BC /DBIGFONTS
    etc.

  The Makefiles for both Microsoft and Borland compilers depend on a
  special file,  `arch/msdos/depend.dos', which  is built by  a Unix
  script  named  `makedep'.  You  may  consider  editing  it if  you
  heavily modify the source files; or better yet, re-run the script,
  using any  clone of  the Bourne shell  and gcc, the  GNU compiler,
  with

    arch/msdos/makedep

  in both the `lib' and the `test' directories.


2. Turbo C v. 2.0x
------------------

  Unlike the precedent version 1.5 (!), Turbo C v.2.0 is not able to
  compile  C sources  if they  use the  Unix convention  for end-of-
  line.  So make  sure either you use the  .zip archive (where files
  are stored  with CR-LF),  or if you  use the .tar.gz  version, the
  program  that  does  the  transformation  (WinZip  can  do  it  if
  instructed, look after "CR/LF conversion for TAR").


Good luck!


--- end of msdos.txt ---
