docs/VERSION.DLL

Due  to our  use of  "libtool" to  generate and  install the  FreeType 2
libraries on  Unix systems,  as well as  other historical events,  it is
generally very  difficult to  know precisely which  release of  the font
engine is installed on a given system.

This file tries  to explain why and to document  ways to properly detect
FreeType on Unix.


1. Version & Release numbers
----------------------------

For each new  public release of FreeType 2,  there are generally *three*
distinct "version" numbers to consider:

  * The official FT2 release number, like 2.0.9, or 2.1.3.

  * The libtool (and Unix)  specific version number, like "9.2.3".  This
    is what "freetype-config --version" will return.

  * The platform-specific  shared object  number, used for  example when
    the library is installed as "/usr/lib/libfreetype.so.6.3.2".

The platform-specific  number is, unsurprisingly,  platform-specific and
varies  with the  operating system  you are  using (several  variants of
Linux, FreeBSD,  Solaris, etc.).  You  should thus _never_ use  it, even
for simple tests.

The libtool-specific  number does  not equal the  release number  but is
tied to it.

The release number is available  at *compile* time through the following
macros defined in FT_FREETYPE_H:

  - FREETYPE_MAJOR : major release number
  - FREETYPE_MINOR : minor release number
  - FREETYPE_PATCH : patch release number

See below for a small autoconf fragment.

The  release   number  is  also  available  at   *runtime*  through  the
"FT_Library_Version" API.   Unfortunately, this one  wasn't available or
working correctly before the 2.1.3 official release.


2. History
----------

The following table gives,  for each official release, the corresponding
libtool  number, as well  as the  shared object  number found  on _most_
systems, but not all of them:

    release       libtool        so
  -------------------------------------
     2.1.4         9.3.3         6.3.3
     2.1.3         9.2.3         6.3.2
     2.1.2         9.1.3         6.3.1
     2.1.1         9.0.3          ?
     2.1.0         8.0.2          ?
     2.0.9         9.0.3          ?
     2.0.8         8.0.2          ?

The libtool numbers are a bit inconsistent due to the library's history:

  - 2.1.0 was created as a development branch from 2.0.8 (hence the same
    libtool numbers).

  - 2.0.9  was  a  bug-fix  release  of  the  "stable"  branch,  and  we
    incorrectly increased its libtool number.

  - 2.1.4 is  still in  the "development" branch,  however it  is stable
    enough to be the basis of an upcoming 2.2.0 release.


3. Autoconf Code Fragment
-------------------------

Lars Clausen contributed the following autoconf fragment to detect which
version of  FreeType is  installed on  a system.  This  one tests  for a
version that  is at least 2.0.9;  you should change  it to check against
other release numbers.


  AC_MSG_CHECKING([whether FreeType version is 2.0.9 or higher])
  old_CPPFLAGS="$CPPFLAGS"
  CPPFLAGS=`freetype-config --cflags`
  AC_TRY_CPP([
#include <freetype/freetype.h>
#if (FREETYPE_MAJOR*1000 + FREETYPE_MINOR)*1000 + FREETYPE_PATCH < 2000009
#error Freetype version too low.
#endif
  ],[
    AC_MSG_RESULT(yes)
    FREETYPE_LIBS=`freetype-config --libs`
    AC_SUBST(FREETYPE_LIBS)
    AC_DEFINE(HAVE_FREETYPE,1,[Define if you have the FreeType2 library])
    CPPFLAGS="$old_CPPFLAGS"
  ],[
    AC_MSG_ERROR([Need FreeType library version 2.0.9 or higher])
  ])


--- end of VERSION.DLL ---