Home Page Project Page Download CVS repository

Debugging with FontForge

Xgridfit has no debugger, and it's pretty safe to predict that it never will. FontForge, however, has an excellent debugger, which you can use to step through the TrueType instructions for a glyph and watch the effect of each instruction on the outline.

You may have to compile FontForge from source to enable the debugger; and if so, you will need the source code for FreeType. We'll go through the procedure below; but first will discuss problems and solutions for debugging Xgridfit code.

For Xgridfit users, the trouble with the FontForge debugger is that it knows nothing about Xgridfit. It can be used to debug the raw TrueType instructions generated by Xgridfit, but it does not display the Xgridfit code in the debugger window. Without a pretty thorough knowledge of TrueType and how Xgridfit generates instructions, it can be difficult to identify an Xgridfit element that is causing problems.

The solution is the Xgridfit debug mode, which, instead of a FontForge or Python script, generates a file that shows exactly what TrueType instructions are generated by every Xgridfit element. If you are using the xgridfit command-line tool, simply include the -d parameter:

    $ xgridfit -d Junicode-Bold.xgf

Now, instead of generating a script Junicode-Bold.pe or Junicode-Bold.py, it generates a file Junicode-Bold.debug. This file always contains output for all functions and the <pre-program>. By default, it generates output for every <glyph> in your Xgridfit program. You can save time and generate a smaller file by using the -g (glyph-select) parameter, thus:

    $ xgridfit -d -g amacron Junicode-Bold.xgf

And now the only glyph Xgridfit generates output for is <glyph ps-name="amacron">.

The output of debug mode consists of the Xgridfit element (sometimes omitting child elements that do not generate code) enclosing the TrueType instructions generated from it. For example, this element:

    <move distance="baseline">
      <point num="bottom-a"/>
      <align>
	<point num="bottom-b"/>
      </align>
    </move>

generates this output:

    <move distance="baseline">
    <point num="bottom-a"/>
      PUSHB_2
      35
      0
      MIAP[rnd]
    <align>
    <point num="bottom-b"/>
      PUSHB_1
      9
      ALIGNRP
    </align>
    </move>

By comparing this output with the TrueType instructions in the FontForge debugger, one can quickly locate an Xgridfit element that is causing problems.

A couple of points. First, if you invoke Xgridfit directly using an XSLT engine rather than the xgridfit script, run in debug mode by using the XSLT script xgridfit-debug.xsl rather than xgridfit.xsl. Second, be aware that you will see some TrueType instructions in the output that do not belong to Xgridfit elements. This is because Xgridfit inserts code of its own, e.g. at the beginnings of glyph programs and at the beginnings and ends of functions.

Activating the FontForge debugger

There are general instructions for building FontForge from source and activating the debugger on the FontForge site. Here are some helpful pointers.

You will need the source code for FreeType2. Most Linux distributions provide a convenient way to obtain it. For example, in Debian or Ubuntu,

    $ apt-get source freetype2

should do it. Users of RPM-based distributions can easily obtain a source RPM for FreeType. Once you have unpacked the source, you need to find the file ftoption.h; it should be in include/freetype/config/ (assuming you are in the FreeType base directory). Open this file with a text editor and find a line that looks like this:

    /* #define TT_CONFIG_OPTION_BYTECODE_INTERPRETER */

Uncomment the line by removing the /* and */ and save the file. Depending on your system configuration, you may or may not have to build FreeType from source and install this new version. On Ubuntu Linux you don't have to. On other systems it may be necessary. One way to find out is to build FontForge and see if the debugger works.

Note the location of the FreeType base directory (perhaps by typing pwd at the command line) and then go to the FontForge base directory. Run configure with a parameter pointing out the location of the FreeType source code, e.g.

    $ ./configure --with-freetype-src=/path-to-freetype

If you don't use the --with-freetype-src parameter, the configure script will probably find the FreeType source, but will hang for a long time while looking for it.

Now do make and, if the build finishes successfully, become root and run make install. If all has gone well, you will be able to use the debugger next time you start FontForge.

Note that Apple Computer Inc. owns several patents relating to the instructing of TrueType fonts. Strictly speaking, you should not enable the FreeType bytecode interpreter unless you have a license from Apple, you live in a country where the patent does not apply, or you are willing to risk a lawsuit. It is perhaps worth noting that Apple does not appear to have a history of suing Open Source font developers.