INSTALL

Installation Instructions
*************************

Basic Installation
==================

mkdir build
cd build
cmake ..
make
make install


CMake configuration options can be set using the -D option. eg

  cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=release


Build Options
=============

Set install prefix:

  -DCMAKE_INSTALL_PREFIX=<path>

Set build type. This sets the standard compiler flags for the build
type.

  -DCMAKE_BUILD_TYPE=debug  or  -DCMAKE_BUILD_TYPE=release

Set compiler flags:

  -DCMAKE_CXX_FLAGS=<flags>   or set CXXFLAGS environment variable

Set linker flags:

  -DCMAKE_LD_FLAGS=<flags>   or set LDFLAGS environment variable


Optional Features
=================

  -D<FEATURE>=<ON|OFF>

eg

  -DENABLE_SPLASH=ON -DBUILD_GTK_TESTS=OFF

A list of all options can be display with the commmand:

  egrep '^ *(option|set.*STRING)' CMakeLists.txt

Alternatively, the options can be edited by running "ccmake ." in the
build directory.


Cross Compiling
===============

A toolchain file is required to specify the target specific compiler
tools. Run cmake with the option:

  -DCMAKE_TOOLCHAIN_FILE=<Toolchain file>

A sample toolchain for a 64-bit mingw build is shown below. Replace
/path/to/win/root with the install prefix for the target environment.

  set(CMAKE_SYSTEM_NAME Windows)
  set(CMAKE_C_COMPILER x86_64-w64-mingw32-gcc)
  set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
  set(CMAKE_RC_COMPILER x86_64-w64-mingw32-windres)
  set(CMAKE_FIND_ROOT_PATH  /usr/x86_64-w64-mingw32 /path/to/win/root )
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)


Debugging Options
=================

Debug Build Types
-----------------
Release build with debugging information:
  -DCMAKE_BUILD_TYPE=relwithdebinfo

Debug build with optimization except for some code re-ordering optimizations:
  -DCMAKE_BUILD_TYPE=debug

Debug build with no optimization:
  -DCMAKE_BUILD_TYPE=debugfull

Release build with debugging and profiling information:
  -DCMAKE_BUILD_TYPE=profile


Address Sanitizer
-----------------
Ensure the extra cmake modules are available (may be a separate
package) then use -DECM_ENABLE_SANITIZERS to specify the santizers. eg

  -DECM_ENABLE_SANITIZERS='address;leak;undefined'

Some options may only be available with clang. Use
-DCMAKE_CXX_COMPILER=clang++ to build with clang.

The sanitizer can also be combined with fuzz testing by using Clang 6.0
or later and additionally enabling the sanitizer fuzzer which
will enable the fuzz target cpp/tests/pdf_fuzzer.