Z3's CMake build system

CMake is a "meta build system" that reads a description of the project written in the CMakeLists.txt files and emits a build system for that project of your choice using one of CMake's "generators". This allows CMake to support many different platforms and build tools. You can run cmake --help to see the list of supported "generators" on your platform. Example generators include "UNIX Makefiles" and "Visual Studio 12 2013".

Getting started

Fixing a polluted source tree

If you have never used the python build system you can skip this step.

The existing Python build system creates generated source files in the source tree. The CMake build system will refuse to work if it detects this so you need to clean your source tree first.

To do this run the following in the root of the repository

git clean -nx src

This will list everything that will be removed. If you are happy with this then run.

git clean -fx src

which will remove the generated source files.

Unix Makefiles

Run the following in the top level directory of the Z3 repository.

mkdir build
cd build
cmake -G "Unix Makefiles" ../
make -j4 # Replace 4 with an appropriate number

Note that on some platforms "Unix Makefiles" is the default generator so on those platforms you don't need to pass -G "Unix Makefiles" command line option to cmake.

Note there is nothing special about the build directory name here. You can call it whatever you like.

Note the "Unix Makefile" generator is a "single" configuration generator which means you pick the build type (e.g. Debug, Release) when you invoke CMake. You can set the build type by passing it to the cmake invocation like so:

cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../

See the section on "Build Types" for the different CMake build types.

If you wish to use a different compiler set the CXX and CC environment variables passed to cmake. This must be done at the very first invocation to cmake in the build directory because once configuration has happened the compiler is fixed. If you want to use a different compiler to the one you have already configured you either need to make a new build directory or delete the contents of the current build directory and start again.

For example to use clang the cmake line would be

CC=clang CXX=clang++ cmake ../

Note that CMake build will detect the target architecture that compiler is set up to build for and the generated build system will build for that architecture. If there is a way to tell your compiler to build for a different architecture via compiler flags then you can set the CFLAGS and CXXFLAGS environment variables to have the build target that architecture.

For example if you are on a x86_64 machine and you want to do a 32-bit build and have a multilib version of GCC you can run cmake like this

CFLAGS="-m32" CXXFLAGS="-m32" CC=gcc CXX=g++ cmake ../

Note like with the CC and CXX flags this must be done on the very first invocation to CMake in the build directory.

Adding Z3 as a dependency to a CMAKE Project

CMake's FetchContent allows the fetching and populating of an external project. This is useful when a certain version of z3 is required that may not match with the system version. With the following code in the cmake file of your project, z3 version 4.12.1 is downloaded to the build directory and the cmake targets are added to the project:

include(FetchContent)
FetchContent_Declare(Z3
        GIT_REPOSITORY https://github.com/Z3Prover/z3
        GIT_TAG        z3-4.15.3
)
FetchContent_MakeAvailable(Z3)

# Add the C++ API include directory for z3++.h
if(TARGET libz3)
    target_include_directories(libz3 INTERFACE
        $<BUILD_INTERFACE:${z3_SOURCE_DIR}/src/api/c++>
    )
endif()

Once fetched, you can link the z3 library to your target:

target_link_libraries(yourTarget PRIVATE libz3)

Important notes for FetchContent approach: - The target name is libz3 (referring to the library target from src/CMakeLists.txt) - An additional include directory for src/api/c++ is added to enable #include "z3++.h" in C++ code - Without the additional include directory, you would need #include "c++/z3++.h" instead

Recommended: Create an alias for consistency with system installs:

# Create an alias for consistency with system install
if(NOT TARGET z3::libz3)
    add_library(z3::libz3 ALIAS libz3)
endif()
target_link_libraries(yourTarget PRIVATE z3::libz3)

Using system-installed Z3

If you have Z3 installed on your system (e.g., via package manager or by building and installing Z3 yourself), you can use CMake's find_package to locate it:

set(Z3_MIN_VERSION "4.15.3")
find_package(Z3 ${Z3_MIN_VERSION} REQUIRED CONFIG)

Once found, you can link to Z3 using the exported target (recommended):

target_link_libraries(yourTarget PRIVATE z3::libz3)

Alternative using variables (for compatibility with older CMake code):

# For C projects
target_include_directories(yourTarget PRIVATE ${Z3_C_INCLUDE_DIRS})
target_link_libraries(yourTarget PRIVATE ${Z3_LIBRARIES})

# For C++ projects  
target_include_directories(yourTarget PRIVATE ${Z3_CXX_INCLUDE_DIRS})
target_link_libraries(yourTarget PRIVATE ${Z3_LIBRARIES})

The find_package(Z3 CONFIG) approach uses Z3's provided Z3Config.cmake file, which is installed to a standard location (typically <prefix>/lib/cmake/z3/). If CMake cannot automatically find Z3, you can help it by setting -DZ3_DIR=<path> where <path> is the directory containing the Z3Config.cmake file.

Note: This approach requires that Z3 was built and installed using CMake. Z3 installations from the Python build system may not provide the necessary CMake configuration files. The exported target z3::libz3 automatically provides the correct include directories and linking flags.

Using system-installed Z3 with FetchContent fallback

This approach combines the benefits of both methods above: it uses a system-installed Z3 if available and meets the minimum version requirement, otherwise falls back to fetching Z3 from the repository. This is often the most practical approach for projects.

set(Z3_MIN_VERSION "4.15.3")

# First, try to find Z3 on the system
find_package(Z3 ${Z3_MIN_VERSION} CONFIG QUIET)

if(Z3_FOUND)
    message(STATUS "Found system Z3 version ${Z3_VERSION_STRING}")
    # Z3_LIBRARIES will contain z3::libz3
else()
    message(STATUS "System Z3 not found or version too old, fetching Z3 ${Z3_MIN_VERSION}")

    # Fallback to FetchContent
    include(FetchContent)
    FetchContent_Declare(Z3
        GIT_REPOSITORY https://github.com/Z3Prover/z3
        GIT_TAG        z3-${Z3_MIN_VERSION}
    )
    FetchContent_MakeAvailable(Z3)

    # Add the C++ API include directory for z3++.h
    if(TARGET libz3)
        target_include_directories(libz3 INTERFACE
            $<BUILD_INTERFACE:${z3_SOURCE_DIR}/src/api/c++>
        )
    endif()

    # Create an alias to match the system install target name
    if(NOT TARGET z3::libz3)
        add_library(z3::libz3 ALIAS libz3)
    endif()
endif()

# Now use Z3 consistently regardless of how it was found
target_link_libraries(yourTarget PRIVATE z3::libz3)

Key benefits of this approach:

• Consistent interface: Both paths result in the same z3::libz3 target
• Version control: Ensures minimum version requirements are met
• Flexible deployment: Works whether Z3 is pre-installed or not
• Proper linking: Uses CMake targets which handle include directories and linking automatically

Important notes:

• Use z3::libz3 target instead of raw library names for better CMake integration
• The target automatically provides the correct include directories, so no need for manual target_include_directories
• When using FetchContent, an alias is created to ensure target name consistency
• Set QUIET in find_package to avoid error messages when Z3 isn't found

Ninja

Ninja is a simple build system that is built for speed. It can be significantly faster than "UNIX Makefile"s because it is not a recursive build system and thus doesn't create a new process every time it traverses into a directory. Ninja is particularly appropriate if you want fast incremental building.

Basic usage is as follows:

mkdir build
cd build
cmake -G "Ninja" ../
ninja

Note the discussion of the CC, CXX, CFLAGS and CXXFLAGS for "Unix Makefiles" also applies here.

Note also that like the "Unix Makefiles" generator, the "Ninja" generator is a single configuration generator so you pick the build type when you invoke cmake by passing CMAKE_BUILD_TYPE=<build_type> to cmake. See the section on "Build Types".

Note that Ninja runs in parallel by default. Use the -j flag to change this.

Note that Ninja also runs on Windows. You just need to run cmake in an environment where the compiler can be found. If you have Visual Studio installed it typically ships with a "Developer Command Prompt Window" that you can use which has the environment variables setup for you.

NMake

NMake is a build system that ships with Visual Studio. You are advised to use Ninja instead which is significantly faster due to supporting concurrent builds. However CMake does support NMake if you wish to use it. Note that NMake is a single configuration generator so you must set CMAKE_BUILD_TYPE to set the build type.

Basic usage:

1. Launch the "Developer Command Prompt Windows"
2. Change to the root of the Z3 repository

mkdir build
cd build
cmake -G "NMake Makefiles" ../
nmake

Visual Studio

Visual Studio 19 comes with integrated support for CMake. It suffices to open the (z3) folder where this file and the Z3 project CMakeLists.txt resides, and Visual Studio does the rest.

For legacy versions of Visual Studio a process is as follows: For the Visual Studio generators you need to know which version of Visual Studio you wish to use and also what architecture you want to build for.

We'll use the cmake-gui here as it is easier to pick the right generator but this can be scripted if need be.

Here are the basic steps:

1. Create an empty build directory
2. Start the cmake-gui program
3. Set "where is the source code" to the root of the Z3 project repository. You can do this by pressing the "Browse Source..." button and picking the directory.
4. Set "where to build the binaries" to the empty build directory you just created. You can do this by pressing the "Browse build..." button and picking the directory.
5. Press the "Configure" button
6. A window will appear asking you to pick the generator to use. Pick the generator that matches the version of Visual Studio you are using. Note also that some of the generator names contain Win64 (e.g. Visual Studio 12 2013 Win64) this indicates a x86 64-bit build. Generator names without this (e.g. Visual Studio 12 2013) are x86 32-bit build.
7. Press the "Finish" button and wait for CMake to finish it's first configure.
8. A set of configuration options will appear which will affect various aspects of the build. Change them as you desire. If you change a set of options press the "Configure" again. Additional options may appear when you do this.
9. When you have finished changing configuration options press the "Generate" button.
10. When generation is done close cmake-gui.
11. In the build directory open the generated Z3.sln solution file created by CMake with Visual Studio.
12. In Visual Studio pick the build type (e.g. Debug, Release) you want.
13. Click "BUILD > Build Solution".

Note that unlike the "Unix Makefile" and "Ninja" generators the Visual Studio generators are multi-configuration generators which means you don't set the build type when invoking CMake. Instead you set the build type inside Visual Studio. See the "Build Type" section for more information.

General workflow

The general workflow when using CMake is the following

1. Create a new build directory
2. Configure the project
3. Generate the build system
4. Invoke the build system to build the project

To perform steps 2 and 3 you can choose from three different tools

• cmake
• ccmake
• cmake-gui

cmake is a command line tool and is what you should use if you are writing a script to build Z3. This tool performs steps 1 and 2 in one go without user interaction. The ccmake and cmake-gui tools are more interactive and allow you to change various options. In both these tools the basic steps to follow are:

1. Configure.
2. Change any options you wish. Every time you change a set of options You should configure again. This may cause new options to appear
3. Generate.

For information see https://cmake.org/runningcmake/

Note when invoking CMake you give it the path to the source directory. This is the top-level directory in the Z3 repository containing a CMakeLists.txt. That file should contain the line project(Z3 C CXX). If you give it a path deeper into the Z3 repository (e.g. the src directory) the configure step will fail.

Build Types

Several build types are supported.

• Release
• Debug
• RelWithDebInfo
• MinSizeRel

For the single configuration generators (e.g. "Unix Makefile" and "Ninja") you set the build type when invoking cmake by passing -DCMAKE_BUILD_TYPE=<build_type> where <build_type> is one of the build types specified above.

For multi-configuration generators (e.g. Visual Studio) you don't set the build type when invoking CMake and instead set the build type within Visual Studio itself.

MSVC Security Features

When building with Microsoft Visual C++ (MSVC), Z3 automatically en