== Building Graphite 2 ==

Graphite 2 is made available as a source tarball from these urls: 
    http://projects.palaso.org/graphitedev/files 
 or http://sf.net/projects/silgraphite/files/graphite2

Graphite 2 uses cmake for its build system. The basic build procedure is to 
create a directory in which to build the library and produce the products. 
Then cmake is run to generate build files and then the build is run.

=== Linux ===

----
mkdir build
cd build
cmake -G "Unix Makefiles" ..
make
make test
----

This will do a default build of Graphite with minimal dependencies on other 
packages. There are various option settings see 
<<X1,Generator configuration options>>>.

On amd64 architecture if you wish build and test 32 bit binaries this is 
possible using the following cmake ivocation:

----
CFLAGS=-m32 CXXFLAGS=-m32 cmake ..
make
make test
----
You will need g++-multilib support see <<X2,Limitations>>

It is possible to use clang to build and test Graphite. Use this build command:

----
CC=clang CXX=clang++ cmake ..
make
----
You will need libc++ libc++-abi see clang-asan section of <<X2,Limitations>>.

=== Windows ===

1. Create your build directory 
+
----
mkdir build
cd build
----

2. Generate project files for your build system
+ 
You need to specify the CMAKE_BUILD_TYPE as some Windows generators require it.
+
----
cmake -DCMAKE_BUILD_TYPE:STRING=Release ..
----
+
CMake will automatically detect your build system and generate a project for 
that. The options passed above will do a default build of Graphite with minimal
dependencies on other packages. 
You may wish to specify a build system other than the automatically detected 
one, for examples if you have multiple versions of Visual Studio installed or 
other toolchains such as MinGW you wish build under. To do this pass 
the `-G <generator name>` option to the initial cmake configuration call, for 
example for Visual Studio 8:
+
----
cmake -G "Visual Studio 8 2005" -DCMAKE_BUILD_TYPE:STRING=Release ..
----
+
or for MinGW
+
----
cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE:STRING=Release ..
----
+
TIP: You can get a list of generators CMakes supports with `cmake --help`.

3. Build graphite binaries
+ 
----
cmake --build .
----
+
When building with using the Visual Studio generator you will need to append 
`--config Debug` or `--config Release` for you debug and release builds 
respectively to the end of above command. Depending on your chosen generator 
the next step varies, for MS Visual Studio projects you will need to run:
+
----
cmake --build . --target RUN_TESTS
---- 
+
for everything else:
+
----
cmake --build . --target test
----

4. Rebuilds
+ 
You can clean the project with:
+
----
cmake --build . --target clean
----
+
Or just delete the build directory and start again.


[[X1]]
=== Generator configuration options ===

There are various option settings that can be passed to cmake when generating. 
They are described here, along with their type and possible and default values. 
Boolean values may take the value OFF or ON. Options may be set using 
the -Doption=value command line option. 
For example: -DGRAPHITE2_COMPARE_RENDERER:BOOL=ON

CMAKE_BUILD_TYPE:STRING::
    This specifies which type of build to do. It is a string and may take the 
    values: Release, RelWithDeb, Debug.
    The default is Release. This must be specified on Windows.

GRAPHITE2_COMPARE_RENDERER:BOOL::
    This is a boolean value that specifies whether to build the comparerenderer 
    program that may link to silGraphite or harfbuzz, if libraries of those 
    packages are installed. The default value is OFF.

GRAPHITE2_NFILEFACE:BOOL::
    This boolean value turns off FileFace support to save code space. 
    By default it is OFF.

GRAPHITE2_NSEGCACHE:BOOL::
    This boolean value turns off Segment caching support to save code space. 
    By default it is OFF.

GRAPHITE2_NTRACING:BOOL::
    This boolean value turns off tracing support to save code space. Tracing 
    support allows debug output of segment creation. By default it is OFF.

GRAPHITE2_VM_TYPE:STRING::
    This string value can be auto, direct or call. It specifies which type of 
    virtual machine processor to use. The default value of auto tells the 
    system to work out the best approach for this architecture. A value of 
    direct tells the system to use the direct machine which is faster. 
    The value of call tells the system to use the slower but more cross 
    compiler portable call based machine.

GRAPHITE2_ASAN:BOOL::
    This turns on copmile time support for Google's 
    https://code.google.com/p/address-sanitizer/[ASAN] Address Sanitizer. 
    This works with both gcc and clang, however under clang any tests driven by 
    Python will not be run. These tests require the ASAN runtime as a shared 
    library and currently clang only provides static version.

Bear in mind that ASAN will not work with ulimit constraints so running the 
fuzztest may result in problems. 


[[X2]]
=== Limitations ===

There are some hard build dependencies:

python::
    To run the make test and make fuzztest, the build system requires 
    python v2.6 or later. Currently python 3 is not supported, however porting
    using 2to3 is straightforward. 

Other configuration related dependencies:

fonttools::
    This python library supports truetype font reading.

g++-multilib::
    If building 32bit binaries under a 64bit Linux host this is 
    required for successful linking. These are the `g++-multilib` and 
    `libc6-dev-i386` packages on Debian and derivatives and `glibc-devel.i686`, 
    `glibc-devel` and `libstdc++-devel.i686` on Redhat OSs

clang::
    To build with clang under linux you will need to ensure you have installed 
    libc++ and libc++abi packages. The easiest way to do on Debian & derivatives
    is to install the libc++-dev and libc++abi-dev packages.

