Configuring a Zorba Build Using CMake

Overview

We will now configure the Zorba build by running CMake. We assume that the appropriate build preparations (described in Preparing to Build Zorba) have been performed.
The instructions in this section are based on executing commands at the command line. It is also possible configure Zorba using CMake's GUI configuration utility if you prefer. On Linux distributions, this is often a separate package named "cmake-gui". On Windows, the GUI is installed by default and can be started via the Start menu. On MacOS, it is available as the "gui" variant of the CMake package.The important configuration parameters - source and build directory; CMake generator; configuration flags - are the same whether you use the command-line or the GUI form of CMake. Only the method by which you specify them will change.
The basic steps to configure Zorba are:
  1. Change the working directory into the {ZORBABUILD} directory: 
    cd {ZORBABUILD}
  2. Execute cmake: 
     cmake [ -G generator ] [ -D option=value ... ] {ZORBASRC}
    where {ZORBASRC} may be an absolute or a relative path to your Zorba source directory. For example, if you used the convention of creating the build directory as a subdirectory of the source directory, you can just type 
     cmake .. 
    along with any necessary -G or -D options.
This command should configure Zorba and prepare for the build. CMake will tell you if your environment is missing some of the required libraries or development headers.The meaning of the -G and -D arguments are described below.
If you need to re-configure the project later, CMake will remember your chosen generator and -D configuration parameters; it is not necessary to specify -G / -D every time.

CMake Generators (the -G argument)

CMake is a meta build system. It is able to generate both native makefiles (e.g. GNU Make or NMake) and IDE workspaces (e.g. Visual Studio or KDevelop Projects), depending on which CMake generator is selected. By default it will generate a UNIX-style Makefile-based project.You specify the generator to use with the -G arguments to cmake. For example, on Windows, you can create a Visual Studio 10 solution by executing the following command in the {ZORBASRC} directory: 
cmake -G "Visual Studio 10" {ZORBASRC} 
The list of available Generators for your CMake installation can be seen by typing 
 cmake --help 
.

Configuration Parameters (the -D arguments)

In most circumstances it will be necessary to specify a few parameters to CMake, such as the various configuration parameters mentioned above in Library Dependencies. You do this with a series of -D arguments to CMake. For example, to build Zorba without ICU (Unicode) support:
cmake -D ZORBA_NO_ICU=ON {ZORBASRC}
A complete list of Zorba's configuration parameters can be found here: Zorba Configuration Parameters. CMake itself also has some configuration parameters that may be important for you; here are three of the most common:
  1. CMake will look for third-party libraries in a variety of standard locations. If you have any installed in unusual locations, you will need to provide it with additional paths to search. You do this by specifying the parameter CMAKE_PREFIX_PATH. This parameter is a semicolon-separated list of directories where CMake should look. For instance, if you have Xerces-C installed in /opt, try the following: 
    cmake -D CMAKE_PREFIX_PATH=/opt {ZORBASRC}

    Returns

    On Linux and MacOS:In command lines, the semicolon is interpretted by the shell as a command separator. In order to pass a semicolon-separated list of paths for this parameter, be sure to enlose the list in single- or double-quotes.

    Returns

    On Windows:Zorba uses a custom mechanism for specifying the paths to third-party dependencies on Windows, which handles some additional features such as collecting the runtime DLLs for installation. You should use this mechanism instead of CMAKE_PREFIX_PATH on Windows. See Zorba's Automatic DLL Detection Mechanism for more information.
  2. After you build Zorba, you will likely want to install it into a final location. You specify this location with the CMAKE_INSTALL_PREFIX parameter. By default, this directory will be {ZORBABUILD}/dist, which is not likely to be a useful location.

    Returns

    Note:After installation, the directory specified here will contain subdirectories such as bin/, lib/, and share/. On Unix and MacOS installations, a common value for CMAKE_INSTALL_PREFIX is /usr/local. On Windows, something like C:\Program Files\Zorba is suggested.

    Returns

    Note for Makefile-based projects:The Makefiles produced by CMake do support the common DESTDIR variable. However, specifying this variable at compile time will not work with Zorba, because certain installation paths are hard-coded into the Zorba binaries. Be sure to only use CMAKE_INSTALL_PREFIX.
  3. When generating a Makefile-based project, CMake supports multiple build configurations. By default, Zorba is built in the Release configuration, which enables compiler optimizations and does not build debug information into the resulting product. To change the build mode to Debug, you can specify the CMAKE_BUILD_TYPE parameter as follows: 
     cmake -D CMAKE_BUILD_TYPE=Debug {ZORBASRC} 
    This is not necessary for IDE-based workspaces; in that case, you may select the type of build from within the IDE.

What's next?

Once CMake runs without reporting any configuration errors, move on to Building and Installing Zorba.