SIL Non-Roman Script Initiative


A free and open rendering engine for complex scripts

Graphite Tutorial

Unit 1: Compiling, installing, and testing a Graphite font



Compiling. To compile a GDL program, run grcompiler and include the name of the GDL program as an argument, as well as the name of the font against which to perform the compilation. It is a good idea to include the “-D” switch so that the compiler will output files that can be used for debugging your Graphite font behavior. See “Compiler Debug Files” for detailed information about what is included in these files. It is also possible to specify a new font face name.

The syntax needed to run grcompiler is the following, where the square brackets indicate optional items:

grcompiler [-D] gdl-program  original-font-file [new-font-file [new-font-name]]

Version 4.2 of the compiler allows you to recompile a font that already contains Graphite tables. When using a previous version of the compiler, the GDL program should always be compiled against a non-Graphite-enabled font.

If the name of the new font file is not specified, the name will be the same as the original with “_gr” appended before the “.ttf” extension.

The compiler outputs a file called “gdlerr.txt” containing any error messages or warnings resulting from the compilation. If errors are encountered, the Graphite-enabled version of the font will not be produced.

Installing. If you are using Windows XP, Vista or Windows 7, you can simply install the font by dragging it into the Fonts directory, or by right-clicking and choosing Install.

During the compile-test-modify development cycle, Windows XP may require you to explicitly uninstall a font before installing a new version with the same name.

Testing. You will be using the WorldPad program to test your Graphite font. To do so, download WorldPad and install it on your system, then run WorldPad.exe. Use the Tools-Writing System Properties dialog to create a writing system that uses your Graphite font for rendering. To do this, add a new writing system and set the font field to the name of your Graphite font. (In earlier versions of WorldPad, you may also need to select Graphite as the renderer.)

In the main WorldPad text-editing window, use the writing system control or the Font-Writing System menu option to select the newly created writing system.

An option is available to have the Graphite engine output log of the transduction process it uses as it performs Graphite rendering. To turn this option on, go to Tools-Options, and check the box labeled “Output Graphite debug log.” For more information about the log, see the “Transduction Log.doc” file.

Exercise 1

The Graphite engine is built into the WorldPad program. Install WorldPad according to the instructions in the WorldPad readme file.

Download and install the Graphite compiler. Double-check that:

  • grcompiler.exe is on your path
  • the GDLPP_PREFS environment variable is set to the directory that contains stddef.gdh

Download the Graphite tutorial package:

GDL Tutorial
Sharon Correll, 2012-01-05
Download "", ZIP archive, 490KB [1342 downloads]

and unzip it into a directory of your choice. Open a command prompt window and navigate to this directory. It should include a file called allcaps.gdl.

Compile this GDL program into a Graphite font, using the sildub3.ttf font. The name of the new Graphite font should be allcaps.ttf, and the new font face name should be “Graphite All-caps Demo”. Use the -D switch to create the debug files. Your command line should look like this:

grcompiler -D allcaps.gdl sildub3.ttf allcaps.ttf "Graphite All-caps Demo"

Locate the following files which will have been output by the compiler if you used the -D switch:

  • dbg_parsetree.txt
  • dbg_glyphattrs.txt
  • dbg_classes.txt
  • dbg_cmap.txt
  • dbg_ruleprec.txt
  • dbg_fsm.txt
  • dbg_enginecode.txt

These files are explained in “Compiler Debug Files.doc” which is included in the compiler package. Also locate the allcaps.gdx file. It can be used by the Graphite2 engine for run-time debugging.

Install your newly-created Graphite font by dragging it into your fonts directory or right-clicking and choosing Install. Look in the Fonts directory and verify that your font “Graphite All-caps Demo” has been installed.

Run WorldPad. Use the Tools – Writing Systems Properties menu item to create a new writing system. Give it the ID “xcap” and the name “All Caps”. Set up the writing system’s renderer so it is using the “Graphite All-caps Demo” font. Click OK to close the dialog.

Select the newly created writing system using the writing system control. Type a few letters. They should all appear in uppercase regardless of whether the characters you entered were upper- or lowercase.

Turn on the option to have Graphite output a log of its transduction process for debugging (use the Tools – Options menu item).

Return to the main editing window and type a little more. Once transduction logging has been turned on, each editing operation causes the log file, gr_xductn.log, to be rewritten.

Locate the gr_xductn.log file. It will be in the directory indicated by your TEMP or TMP environment variable.1 Display the file using a fixed-width font. (Extra credit: can you interpret any of what you see? :-) )

You may want to create a shortcut to the gr_xductn.log file.

1 With earlier versions of WorldPad it is not always easy to predict where this file will be written; generally it would be in the folder where you last read or saved a file, or in the folder with WorldPad.exe.

Copyright © 2012 SIL International® and released under the  Creative Commons Attribution-ShareAlike 3.0 license (CC-BY-SA) unless noted otherwise.