mirrors/z3
3
0
Fork 0
mirror of https://github.com/Z3Prover/z3 synced 2025-04-04 08:39:57 +00:00
Code Activity
z3/contrib/ci/README.md
Dan Liew 8310fed528 [TravisCI] Implement TravisCI build and testing infrastructure for Linux 
The Linux builds rely on Docker (using Ubuntu 16.04LTS and Ubuntu
14.04LTS) to build and test Z3 so that builds are easily reproducible.

A build status button has been added to `README.md` so that it is
easy to see the current build status.

More documentation can be found in `contrib/ci/README.md`.

This implementation currently tests 13 different configurations. If
build times become too long we can remove some of them.

Although it would be nice to test macOS builds that requires
significantly more work so I have left this as future work.
2017-07-01 11:51:30 +01:00

5 KiB
Raw Blame History

Continous integration scripts

TravisCI

For testing on Linux and macOS we use TravisCI

TravisCI consumes the .travis.yml file in the root of the repository to tell it how to build and test Z3.

However the logic for building and test Z3 is kept out of this file and instead in a set of scripts in scripts/. This avoids coupling the build to TravisCI tightly so we can migrate to another service if required in the future.

The scripts rely on a set of environment variables to control the configuration of the build. The .travis.yml declares a list of configuration with each configuration setting different environment variables.

Note that the build scripts currently only support Z3 built with CMake. Support for building Z3 using the older Python/Makefile build system might be added in the future.

Configuration variables

  • ASAN_BUILD - Do AddressSanitizer build (0 or 1)
  • BUILD_DOCS - Build API documentation (0 or 1)
  • C_COMPILER - Path to C Compiler
  • CXX_COMPILER - Path to C++ Compiler
  • DOTNET_BINDINGS - Build and test .NET API bindings (0 or 1)
  • JAVA_BINDINGS - Build and test Java API bindings (0 or 1)
  • NO_SUPPRESS_OUTPUT - Don't suppress output of some commands (0 or 1)
  • PYTHON_BINDINGS - Build and test Python API bindings (0 or 1)
  • RUN_SYSTEM_TESTS - Run system tests (0 or 1)
  • RUN_UNIT_TESTS - Run unit tests (0 or 1)
  • TARGET_ARCH - Target architecture (x86_64 or i686)
  • TEST_INSTALL - Test running install target (0 or 1)
  • UBSAN_BUILD - Do UndefinedBehaviourSanitizer build (0 or 1)
  • USE_LIBGMP - Use GNU multiple precision library (0 or 1)
  • USE_LTO - Link binaries using link time optimization (0 or 1)
  • USE_OPENMP - Use OpenMP (0 or 1)
  • Z3_BUILD_TYPE - CMake build type (RelWithDebInfo, Release, Debug, or MinSizeRel)
  • Z3_CMAKE_GENERATOR - CMake generator (Ninja or Unix Makefiles)
  • Z3_VERBOSE_BUILD_OUTPUT - Show compile commands in CMake builds (0 or 1)
  • Z3_STATIC_BUILD - Build Z3 binaries and libraries statically (0 or 1)
  • Z3_SYSTEM_TEST_GIT_REVISION - Git revision of z3test. If empty lastest revision will be used.

Linux

For Linux we use Docker to perform the build so that it easily reproducible on a local machine and so that we can avoid depending on TravisCI's environment and instead use a Linux distribution of our choice.

The scripts/travis_ci_linux_entry_point.sh script

  1. Creates a base image containing all the dependencies needed to build and test Z3
  2. Builds and tests Z3 using the base image propagating configuration environment variables (if set) into the build using the --build-arg argument of the docker run command.

If an environemnt variable is not set a defaults value is used which can be found in Dockerfiles/z3_build.Dockerfile.

Linux specific configuration variables

  • LINUX_BASE - The base docker image identifier to use (ubuntu_16.04, ubuntu32_16.04, or ubuntu_14.04).

Reproducing a build locally

A build can be reproduced locally by using the scripts/travis_ci_linux_entry_point.sh script and setting the appropriate environment variable.

For example lets say we wanted to reproduce the build below.


  - LINUX_BASE=ubuntu_16.04 C_COMPILER=/usr/bin/gcc-5 CXX_COMPILER=/usr/bin/g++-5 TARGET_ARCH=x86_64 Z3_BUILD_TYPE=RelWithDebInfo

This can be done by running the command

LINUX_BASE=ubuntu_16.04 C_COMPILER=/usr/bin/gcc-5 CXX_COMPILER=/usr/bin/g++-5 TARGET_ARCH=x86_64 Z3_BUILD_TYPE=RelWithDebInfo scripts/travis_ci_linux_entry_point.sh

The docker build command which we use internally supports caching. What this means in practice is that re-running the above command will re-use successfully completed stages of the build provided they haven't changed. This requires that the Dockerfiles/z3_build.Dockerfile is carefully crafted to avoid invalidating the cache when unrelated files sent to the build context change.

TravisCI docker image cache

To improve build times the Z3 base docker images are cached using TravisCI's cache directory feature. If the DOCKER_TRAVIS_CI_CACHE_DIR environment variable is set (see .travis.yml) then the directory pointed to by the environment variable is used as a cache for Docker images.

The logic for this can be found in scripts/travis_ci_linux_entry_point.sh. The build time improvements are rather modest (~ 2 minutes) and the cache is rather large due to TravisCI giving each configuration its own cache. So this feature might be removed in the future.

It may be better to just build the base image once (outside of TravisCI), upload it to DockerHub and have the build pull down the pre-built image everytime.

An organization has been created on DockerHub for this.

macOS

Not yet implemented.