Building Firebird with CMake

WARNINGS (read carefully)

• CMake build system is in testing phase now and ready only for development purposes.

• Do not use it for building production binaries!

• The Firebird source directory should be CLEAN! I.e. no 'default build system' should be run in that directory previously.

• During stabilization phase sometimes after build system update the build cannot complete. In this case you should try: 1) Remove binary_dir/CMakeCache.txt file and rebuild; or 2) Remove the whole binary_dir or its contents and re-run cmake command with proper parameters again.

Quick start

Download latest CMake and install it. Make sure that cmake and sed commands are in your PATH environment.

Create build directory in any place you want. Then run cmake with parameter - path to Firebird sources.

E.g.:

cd /path/to/binary/dir
cmake /path/to/sources/dir

Complete example:

cd firebird_sources
mkdir build
cd build
cmake ..

In-source builds are not allowed! You cannot simply run cmake . in Firebird sources directory.

After executing these commands CMake will create build structure for you. If you generating for some IDE you should find project or solution file(s) in binary (build) directory.

After build you may want to create necessary runtime files (configs, databases and others). To do this, build copy_files target in your IDE or run in console:

make copy_files

Generating build files

This section describes generation of build files for different platforms and IDEs. All commands uses tricky way to select source and binary directories, but you can use standard way described above.

-Hsource_dir defines sources directory for CMake.

-Bbinary_dir defines binary (build) directory for CMake.

All commands below is executed under the Firebird sources root directory.

CMake can use -G generator option to generate files for required build environment. For available generators please check cmake --help.

Run command on all *nix systems usually only make or with number of cores make -jN (make -j4, make -j8). With Visual Studio and Xcode you should run solution files for IDE.

After compilation Firebird binaries can be found under build_dir/firebird/ or build_dir/firebird/CONFIGURATION/ (if you use multiconfiguration IDE build) directories.

Visual Studio

By default CMake will try to use latest Visual Studio compiler on Windows platform. You find firebird.sln solution file under the win directory.

cmake -H. -Bwin

From command line:

cmake -H. -Bwin
win\firebird.sln

MS Visual Studio with generator

CMake supports different VS versions (6-14). For example:

cmake -H. -Bwin -G "Visual Studio 6"
cmake -H. -Bwin -G "Visual Studio 7"
cmake -H. -Bwin -G "Visual Studio 10"
cmake -H. -Bwin -G "Visual Studio 11"
cmake -H. -Bwin -G "Visual Studio 12"
cmake -H. -Bwin -G "Visual Studio 14"

MS Visual Studio 64-bit

cmake -H. -Bwin -G "Visual Studio 12 Win64"

MS Visual Studio build for Windows XP

Such building requires toolset specification. MSVS toolsets for WinXP are usually named as 'v<VC_VER>0_xp', e.g. v120_xp, v110_xp.

cmake -H. -Bwin -G "Visual Studio 12" -T v120_xp

*nix (Linux, OS X, *BSD)

cmake -H. -Bbuild

Release is default build type. Debug build:

cmake -H. -Bbuild_debug -DCMAKE_BUILD_TYPE=Debug

Xcode

cmake -H. -Bbuild_xcode -G Xcode

MinGW-w64

MinGW-w64 compiler should be in PATH.

set PATH=%PATH%;g:\dev\mingw-w64\i686-4.9.2-posix-dwarf-rt_v3-rev0_msys\mingw32\bin\
cmake -H. -Bwin_mingw -G "MinGW Makefiles"
mingw32-make -C win_mingw

Crosscompiling

Android

This section describes building Firebird for Android using Android NDK.

1. Download latest Android NDK.
2. Download Android Toolchain for CMake. You only need android.toolchain.cmake from there.
3. Build Firebird with any native compiler. For Windows you can use choose MSVC.

Options to CMake (passed via -D):

• CMAKE_TOOLCHAIN_FILE = CMake Android Toolchain file.
• ANDROID_NDK = Android NDK root
• ANDROID_NATIVE_API_LEVEL = Android API version
• CMAKE_MAKE_PROGRAM = Make program for building
• NATIVE_BUILD_DIR = build directory with fully pre-builded Firebird.

The build command on Windows is cmake --build build_directory.

cmake ^
    -DCMAKE_TOOLCHAIN_FILE=g:\dev\android-cmake\android.toolchain.cmake ^
    -DANDROID_NDK=g:\dev\android-ndk-r10d\ ^
    -DANDROID_NATIVE_API_LEVEL=android-21 ^
    -DCMAKE_MAKE_PROGRAM=g:\dev\android-ndk-r10d\prebuilt\windows-x86_64\bin\make.exe ^
    -DNATIVE_BUILD_DIR=win ^
    -H. ^
    -Bwin_android -G "Unix Makefiles"
cmake --build win_android

CMake command for Android crosscompiling on Ubuntu 14.04. Make sure all paths are absolute.

cmake \
    -DCMAKE_TOOLCHAIN_FILE=/home/egor/Downloads/android.toolchain.cmake \
    -DANDROID_NDK=/home/egor/Downloads/android-ndk-r10d/ \
    -DANDROID_NATIVE_API_LEVEL=android-21 \
    -DNATIVE_BUILD_DIR=/home/egor/dev/firebird_cmake/build \
    -H. \
    -Bbuild_android

iOS

This section describes building Firebird for iOS on OS X.

1. Download iOS CMake toolchain.

2. Append these lines to the toolchain file (by default its name is iOS.cmake).

   set(CMAKE_MACOSX_BUNDLE YES)

   set(CMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_REQUIRED "NO")

3. Run the command below.

4. Start Xcode and try to build it.

Options to CMake (passed via -D):

• CMAKE_TOOLCHAIN_FILE = CMake iOS Toolchain file.
• NATIVE_BUILD_DIR = build directory with fully pre-builded Firebird.

Command:

cmake -DCMAKE_TOOLCHAIN_FILE=~/Downloads/iOS.cmake -DNATIVE_BUILD_DIR=build -H. -Bbuild_ios -G Xcode

Development process

General notes

Firebird uses 2-step build which is also implemented using CMake.

The general difference is that for increasing build speed two special static library objects added: yvalve_common and engine12_common. They are built only once and the linked to yvalve_boot, yvalve and engine12_boot, engine12.

yvalve_common and engine12_common consist only with static (not generated) source files while yvalve_boot, yvalve and engine12_boot, engine12 contain only .epp files.

Sources are grouped into groups as in current Visual Studio projects. Some project directories are added (Boot, examples, CMake Targets, Extern, Custom build steps).

Disabling unneeded projects to build (several IDEs only)

In Visual Studio you can disable building of unneeded projects by unloading them. You also can unload the whole project directory. For example boot or examples after first full build.

Add file to project

Many projects use masks for defining source list to build. To get your new file involved into build you must re-run cmake /path/to/sources command from build dir.

In other hand you can manually add file to project rules in CMake file and run build command. CMake will re-configure build files and build binary with that new file.

Do some changes in CMake rules

After you did a change just run a build command. CMake usually understands the change and re-runs configure step automatically.

Firebird's CMake Internals

CMake rules are written in several files. Assume you are in Firebird sources root directory. Here are the list of main files:

• builds/cmake/*: These files provide configure rules, support functions, .epp->.cpp generating functions and some other misc. stuff.
• CMakeLists.txt: This is the main CMake file. It defines cmake, project, compiler settings. It starts configure steps, generates build files. Also it contains build rules for extern/* projects which can be moved into extern/ directory later.
• Other CMakeLists.txt files near the sources. Contain all build rules for those libraries, shared objects and executables.

List of CMakeLists.txt in sources:

examples/CMakeLists.txt
src/CMakeLists.txt
src/gpre/CMakeLists.txt
src/remote/CMakeLists.txt
src/utilities/CMakeLists.txt

src/CMakeLists.txt is the biggest files that contains almost all build rules. It is not split into many small files because many other projects require minimal CMake rules (often 3-4 lines). So for now they are all combined to this file. Also CMake have some limitations related to generated files, and some projects that use .epp files just cannot be put in other file than src/CMakeLists.txt.

Missing features

• install/uninstall commands
• proper compiler flags for debug/release/other builds