freetype2/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 the last line to check
against other release numbers.

  AC_MSG_CHECKING([for version of FreeType])
  FREETYPE_INCLUDE=`freetype-config --cflags | cut -c3-`
  FREETYPE_MAJOR=`grep '^#define FREETYPE_MAJOR' \
                  $FREETYPE_INCLUDE/freetype/freetype.h | cut -d' ' -f3`
  FREETYPE_MINOR=`grep '^#define FREETYPE_MINOR' \
                  $FREETYPE_INCLUDE/freetype/freetype.h | cut -d' ' -f3`
  FREETYPE_PATCH=`grep '^#define FREETYPE_PATCH' \
                  $FREETYPE_INCLUDE/freetype/freetype.h | cut -d' ' -f3`
  FREETYPE_VERSION=`echo | awk "BEGIN { printf \"%d\", \
                     ($FREETYPE_MAJOR * 1000 + $FREETYPE_MINOR) * 1000 \
                     + $FREETYPE_PATCH;}"`
  AC_MSG_RESULT([$FREETYPE_MAJOR.$FREETYPE_MINOR.$FREETYPE_PATCH])
  if test "$FREETYPE_VERSION" -ge 2000009; then


--- end of VERSION.DLL ---