== Building Graphite 2 ==

Graphite 2 is made available as a source tarball from these urls:
https://github.com/silnrsi/graphite/releases or +
http://sf.net/projects/silgraphite/files/graphite2

While Graphite 2 is written in C++11, it is written in a subset that ensures no
runtime dependency on the language runtime.

Graphite 2 uses cmake for its build system. The basic build procedure is to
create a directory in which to build the library and executable 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 invocation:

----
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 12 2013" -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

BUILD_SHARED_LIBS:BOOL::
    Specifies that libgraphite2 should be built as a shared library, setting
    this to OFF will cause it built as a static library. When OFF this will also
    disable a few tests which either test aspects of a shared library or require
    one (such as any test case with a python driver). +
    The default is ON.

CMAKE_BUILD_TYPE:STRING::
    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::
    Specifies whether to build the comparerenderer program that may link to
    silGraphite or harfbuzz, if libraries of those packages are installed. +
    The default is OFF.

GRAPHITE2_NFILEFACE:BOOL::
    Turns off FileFace support to save code space. +
    The default is OFF.

GRAPHITE2_NTRACING:BOOL::
    Turns off tracing support to save code space. Tracing support allows debug
    output of segment creation. +
    The default is ON.

GRAPHITE2_VM_TYPE:STRING::
    This value can be `auto`, `direct` or `call`. It specifies which type of
    virtual machine processor to use. The 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. +
    The default is auto.

GRAPHITE2_SANITIZERS:STRING::
    This turns on compile time support for the specified sanitizers. This works
    with both gcc and clang, though there are some differences in which
    sanitizers each offers. The fuzzer sanitizer causes libFuzzer based fuzzing
    targets to be built as well, but this currently only works under clang. +
    The default is an empty string.

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.7 or later.

Microsoft Visual C++::
    You will need Microsoft Visual Studio 12 2013 or later as we use some
    C++11 features.

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 that on Debian &
    derivatives is to install the libc++-dev and libc++abi-dev packages.
