FREETYPE 2.2.0 ISSUES

Introduction

Installing FreeType 2.2.0 on a Unix system is likely to break your desktop, by making it impossible to start any graphics application. This includes ‘gdm’ and ‘kdm’, the default graphical login programs of many distributions.

The problem doesn't lie in the font engine itself, but on dependent libraries that use it incorrectly. This document node tries to explain the current situation, and what can be done. We also provide patches for the most important programs and libraries.

Understanding the Problem

Exposed Internals

The source of our worries is that the font engine's internals were exposed in previous releases of FreeType 2.

• The internal headers used to build the font engine were installed together with the public ones, in $PREFIX/include/freetype2/freetype/internal. Additionally, many internal functions, though not all, were also exposed by the dynamic library libfreetype.so generated by our default build system.

• We also included some experimental code to help developers get a taste of what future features we are going to implement (e.g., the cache subsystem or the path stroker). However, we warned in our header files (and in the documentation) that the code is likely to change.

Theory and Reality

Experience has taught that our point of view has been naïve.

• Some developers use the internal headers and functions intensively. In some cases there are even public APIs to do exactly the same thing.

• Other developers go one step further and ignore warnings in the headers, using FreeType's experimental code in final releases of applications. The most notable program belonging into this category is ‘firefox’.

• The situation is worsened due to lack of communication. Developers use experimental code without asking for any help or direction (e.g., sending ‘how do I implement feature X?’ to our mailing lists). Most of the time, we, the FreeType developers, have no idea of what is being used by whom. Neither are we aware of the needs the programmers have while using FreeType.

Notice that in nearly each release of FreeType, we do modify our internals in order to fix bugs, add features, or optimize things. However, we are very conservative with the public API, and the interface broke only once by mistake since the library's origin.

Consequences

With some luck, the internal changes of a new FreeType release don't break anything. Otherwise we get e-mails to our mailing lists, telling us that ‘FreeType 2.1.x broke my system when I installed it’, or even ‘We, (distribution-name), can't update our version of FreeType because it breaks things’.

Sometimes, it is real fun to find the mistakes in the application's code which causes the problem. In one specific case we even provided patches to correct a given ‘rogue’ library to make it use only standard FreeType APIs (without losing features), just to discover that its developers repeat the same mistakes in later releases.

The Solution

Starting with FreeType version 2.2.0, we will no longer expose the internal interface to the public.

• Internal header files won't be installed anymore. In case the installation script finds a directory named $PREFIX/include/freetype2/freetype/internal, it renames it to something different.

• We use libtool's ‘-export-symbols’ command-line option to ensure that only our public APIs are exported by libfreetype.so.

• Due to heavy reorganization it is very likely that applications which directly use FreeType's internal structures no longer compile.

This decision probably cause incompatibilities or even crashes; the effects can be summarized as follows.

• Most installed rogue library or program that directly depends on FreeType internals will not be able to properly link, and will fail to load.

• Other rogue programs and libraries may still link, but there is no guarantee that they will work properly. If you are extremely lucky, nothing will change.

• You won't be able to compile any of those libraries and programs from sources either. To behave correctly some patches are necessary (see below).

• Any program or library that depends on a rogue one will fail to load as well, which is why your desktop will be essentially broken if you naïvely install 2.2.0 on your machine.

How to Fix Bad Packages

If you are a developer or a distribution packager, here some steps to detect rogue packages.

Detection

The easiest way to detect rogue packages is by grepping its source code for the following items.

• FT_INTERNAL_
• freetype/internal
• FT_CACHE_INTERNAL_

These indicate dependencies on FreeType internals at compile time. Note that they can be followed by anything in the source files. If they don't appear you are pretty safe!

Find a Newer Version or a Patch

If you have a rogue package, first try to see whether a more recent version exists that fixes the problem. Otherwise, check our page to see whether we provide a patch for it.

What to Do If No Patch is Available

Send a note to our development mailing list describing the problem, giving us the full reference for the package and how to get its source code. We will take a look at it and try to provide a patch as soon as possible.

Create a Patch and Please Send It to Us

In case you have namaged to write your own patch which fixes a rogue package please don't hesitate to send it to us!

• We will be able to review it, telling you whether it fixes correctly the problem.

• We will make the patches available on our pages to other people.

Complain to The Authors

If none of the above appears as a valid solution you might complain directly to the application's or library's authors. Don't be rude, just tell them that what kind of problems you experience, and that they can get help on our development mailing list in case the problem is caused by a new FreeType version.