Glyph Keeper

Latest version: 0.30 (January 15, 2007)

Compiling Glyph Keeper

Requirements

OS with long file names support. Glyph Keeper file names are not in 8.3 format, they have to be changed to be used with DOS. (It's easy to make 8.3 names, I just don't want to cripple the default package, which will be used on long file name capable systems by most of people)
ANSI C compliant compiler. Glyph Keeper was tested with GCC, Intel C++, MSVC, CodeWarrior, Digital Mars C++.
FreeType library v.2.1.10 or later, installed and ready to use. This is easy if previous requirement is met. Please check FreeType documentation for details on installing it. If you are using Linux there is a chance you already have FreeType installed. If you use Windows you can try my precompiled FreeType binaries.
Target-supporting library installed and ready to use. It means if you are going to use Glyph Keeper with Allegro, Allegro headers should be located where compiler can find them. Similar for SDL. Text mode FILE IO target (Named GLYPH_TARGET_TEXT in glyph.h) does not need any extra libraries and can be used to test Glyph Keeper and FreeType installation without introducing extra dependencies.

Compiling

Once you have the compiler, FreeType and target library, it is straightforward to compile Glyph Keeper. You only need to compile "glyph.c", which #includes other *.c files. Here are example commands doing that:

Cygwin environment, GCC 3.3.3, default text target:

gcc -O3 -DGLYPH_TARGET=GLYPH_TARGET_TEXT -c -o glyph-text-cygwin.o glyph.c

All same, Allegro target:

gcc -O3 -DGLYPH_TARGET=GLYPH_TARGET_ALLEGRO -c -o glyph-allegro-cygwin.o glyph.c

Compiling Glyph Keeper with GCC under Linux:

gcc -I/usr/local/include/freetype2 -O3 -DGLYPH_TARGET=GLYPH_TARGET_ALLEGRO -c -o glyph-allegro.o glyph.c

Similar command should work with other GCC ports, just put correct paths and file names, and your favorite optimization options. I also use "-W -Wall -Werror -ansi -pedantic" to catch more errors, but it's not necessary for you.

Compiling Glyph Keeper with Intel C/C++ compiler may look like this:

icl -MD -fast -DGLYPH_TARGET=GLYPH_TARGET_TEXT -c -Fo"glyph-text-icl.obj" glyph.c

Note, that if you are going to use Glyph Keeper with statically linked Allegro, you'll have to compile Glyph Keeper with ALLEGRO_STATICLINK defined. (Simply add -DALLEGRO_STATICLINK to the compiler command line).

Configuring Glyph Keeper

Compiler macros, affecting Glyph Keeper:

GLYPH_TARGET - this macro specifies Glyph Keeper target. It must be defined to one of these values (otherwise Glyph Keeper will not compile):

GLYPH_TARGET_TEXT - stdio output, glyphs are printed out to the FILE* stream.
GLYPH_TARGET_ALLEGRO - glyphs are rendered to the Allegro BITMAPs. GLYPH_TARGET_SDL - glyphs are rendered to the SDL surfaces.

The GLYPH_TARGET macro should be defined same for all files in your project, having '#include "glyph.h"'. It is better to define it in the compiler command line.

Starting with version 0.27 there is no default value for this macro, it must be specified explicitly. Earlier versions had it set to GLYPH_TARGET_TEXT by default, which caused troubles when people compiled Glyph Keeper without defining GLYPH_TARGET and tried to use it with Allegro.

GLYPH_DLL - defining this macro will give '__declspec(dllexport)' to Glyph Keeper API declarations. It is useful if you are going to produce Glyph Keeper DLL. Although, in general, I don't recommend doing Glyph Keeper DLL. Keeping FreeType as DLL is considerable.

GLYPH_SAFE - defining this macro while compiling Glyph Keeper (glyph.c) will switch on more Glyph Keeper internal consistency checking. Glyph Keeper may become a little slower, probably not noticeable slowdown. This macro is used to debug Glyph Keeper, not your program.

GLYPH_LOG - this macro controls Glyph Keeper logging. If this macro is defined, a logfile "glyph.log" will be created every time you run your program linked to Glyph Keeper. Many things will be written to this logfile, as your program calls Glyph Keeper routines. Normally you should only use this macro if you are debugging Glyph Keeper or making changes to it.
This macro first emerged in Glyph Keeper 0.15, it has no effect on earlier versions.

GLYPH_NO_LEGACY - if defined, disables compatibility with old versions of Glyph Keeper API. This macro has no effect on Glyph Keeper itself, but on your program. If you use this macro it should be defined before including "glyph.h". This macro appeared in Glyph Keeper 0.21.2.

NDEBUG - this macro has nothing to do with Glyph Keeper, since it does not use 'assert()'.

Installing Glyph Keeper

Caution! Whenever you install a newer version of Glyph Keeper, you must install both library and header file. Don't mix library and header of different versions. It's one of the most common troubles people get somehow.

Library file 'libglyph.a' (or 'glyph.lib')

Successful compilation will produce a single object file, named 'glyph.o' or whatever name you give it. Just place it somewhere where linker can find it and add it to the link phase of your build script.

If you like, you can make a library file 'glyph.lib' or 'libglyph.a' file with your 'lib' or 'ar' utility. Example 'ar' command (Works with MinGW, and probably with any other GCC+Binutils intall):

ar -r libglyph.a glyph-allegro-mingw.o

Example 'lib' command (Works with MSVC and Intel C/C++ compiler for Windows):

lib -nologo -out:"glyph.lib" glyph.obj

You should then put the library file to the compiler's 'lib' directory.

Example command for linking your program, that uses Glyph Keeper and Allegro (MinGW):

gcc -o program.exe program.o -lglyph -lft -lalleg

Please note that libraries should be listed in certain order, otherwise it will not link.

Header file 'glyph.h'

Now, the header file, 'glyph.h'. You can copy it into your compiler 'include' directory, your project directory, or any other place where your compiler will find it.