z3-sys

Low-level rust bindings to the Z3 SMT solver

Licensed under the MIT license.

See https://github.com/Z3Prover/z3 for details on Z3.

Documentation

The API is fully documented with examples: https://docs.rs/z3-sys/

Installation

This crate works with Cargo and is on crates.io. Add it to your project with cargo add:

$ cargo add z3-sys

Finding Z3 Libraries

Note: This library has a dependency on Z3.

There are 4 ways for this crate to currently find Z3:

By default, it will look for a system-installed copy of Z3. On Linux, this would be via the package manager. On macOS, this might be via Homebrew (brew install z3). Users can use the environment variable Z3_LIBRARY_PATH_OVERRIDE to manually specify the library search path.
Enabling the bundled feature will use cmake to build and statically link Z3 from source. Despite the name, Z3 source is not included in the crate tarball. On a first build from crates.io, the build script queries the GitHub Contents API to find which Z3 commit the z3-sys submodule pointed to at release time (via the z3-sys-vX.Y.Z git tag), then downloads and extracts that Z3 source archive. The result is cached in Cargo's build output directory and reused until cargo clean.

Using your own Z3 checkout: Set Z3_SYS_BUNDLED_DIR_OVERRIDE to the absolute path of a Z3 source tree to build from that instead:
```
Z3_SYS_BUNDLED_DIR_OVERRIDE=/absolute/path/to/z3 cargo build
```
To use a path relative to your project root, add the following to your project's .cargo/config.toml. The relative = true key tells Cargo to resolve the path relative to the config file's location rather than as an absolute path:
```
[env]
Z3_SYS_BUNDLED_DIR_OVERRIDE = { value = "path/to/z3", relative = true }
```
Note: A z3 directory in your own project or workspace is not picked up automatically. Even if you have a Z3 git submodule in your repo, you must point Z3_SYS_BUNDLED_DIR_OVERRIDE at it explicitly.

Pinning a Z3 version without a source checkout: The gh-release feature (see below) lets you pin a specific Z3 version via Z3_SYS_Z3_VERSION without managing a source tree yourself.
Enabling the vcpkg feature will use vcpkg to build and install a copy of Z3 which is then used.
Enabling the gh-release feature will download a pre-compiled copy of Z3 from the GitHub release page for the current platform, if available.
- You may specify the version of Z3 to download via the Z3_SYS_Z3_VERSION environment variable.
- Note: Github throttles unauthenticated requests from the same IP fairly aggressively. If you are using the gh-release feature inside a CI pipeline (or if you cargo clean and rebuild a lot), you will likely experience random 403 responses downloading the z3 build artifacts. To mitigate this, generate a read-only Personal Access Token (https://github.com/settings/personal-access-tokens) and provide it to the READ_ONLY_GITHUB_TOKEN environment variable. The build.rs step will automatically use this token (if present) to prevent throttling.

Note: This crate requires a z3.h during build time.

By default, the crate will look for a z3.h in standard/system include paths. The Z3_SYS_Z3_HEADER environment variable can also be used to customize this.
Enabling thebundled feature will cause the bundled copy of z3.h to be used. The Z3_SYS_Z3_HEADER environment variable can also be used to customize this.
Enabling the vcpkg or gh-release feature will cause the copy of z3.h provided by that version to be used. In this case, there is no override via the environment variable.

Support and Maintenance

I am developing this library largely on my own so far. I am able to offer support and maintenance, but would very much appreciate donations via Patreon. I can also provide commercial support, so feel free to contact me.

Contribution