Getting Started

Important

‘abstractions’ is not supported on Windows.

Before doing any environment setup, first clone the repo:

git clone https://github.com/richengguy/abstractions.git

All of the getting started instructions assume you are working in the abstractions/ directory.

Environment Setup

Compiling abstractions requires:

uv is the recommended way to setup the abstractions build environment. Clang and Doxygen must be installed separately.

Building the documentation also requires:

The easiest way to create the build environment is with uv:

uv sync
source .venv/bin/activate

This will install the correct versions of CMake and Doxygen into the abstractions environment.

This is the method the build workflow uses.

Note that this requires ensuring CMake and, optionally, Doxygen are installed using an alternate method.

Getting Clang 19

Getting Clang 19 depends on the operating system and its package manager. There are profiles in profiles/ that are configured for each supported build platform.

Ubuntu or Debian Linux

The easiest way to get Clang 19 on an Ubuntu or Debian system is with setup script provided by the LLVM project. Adapted from https://apt.llvm.org/,

wget https://apt.llvm.org/llvm.sh
chmod u+x llvm.sh
sudo ./llvm.sh 19

# The line below is only needed if the default GCC version is less than 12
# (e.g., on Ubuntu 22.04).  Clang uses the libstdc++ headers GCC provides and
# versions older than 12 don't have the necessary C++23 headers.
sudo apt install g++-12

Arch Linux

Get Clang 19 by installing the clang19 package via pacman:

pacman -S clang19

macOS

The version of Clang that comes with Xcode, or the Xcode Command Line Tools, is not supported. Instead, use Homebrew to get the correct version:

brew install llvm@19

Compiling

Creating a release build is done with

conan install . -pr:a profiles/$PROFILE --build=missing
cmake --preset conan-release
cmake --build --preset conan-release

where PROFILE is arch-x86_64, debian-x86_64, or macos-arm64.

Creating a debug build is done with

conan install . -pr:a profiles/$PROFILE --build=missing -s build_type=Debug
cmake --preset conan-debug
cmake --build --preset conan-debug

The unit and feature tests are compiled by default. They can be disabled by adding -o "&:build_tests=False".

CMake Variables

Option

Description

Default

ABSTRACTIONS_BUILD_DOCS

Enables the make docs target that builds the documentation. See Documentation for how this works.

ABSTRACTIONS_BUILD_TESTS

Build the unit and feature tests.

OFF

ABSTRACTIONS_ASSERTS

Enable the internal asserts system.

ON

ABSTRACTIONS_ENABLE_ASAN

Enable the Clang AddressSanitizer to catch memory leaks and other issues. Off by default as it has a performance impact.

OFF

ABSTRACTIONS_ENABLE_PROFILING

Enables linking with gperftools to enable source-level profiling. This adds a --profile option to some of the subcommands.

OFF

The variables above enable/disable certain compile-time features. For example, to enable profiling, run

cd $BUILD_DIR  # $BUILD_DIR will be something like 'build/Release'
cmake -DABSTRACTIONS_ENABLE_PROFILING=ON .
make -j

abstractions

The abstractions binary can be found in $BUILD_DIR/bin. The dependencies are statically linked so the file can be moved to other locations on the same system. Help information can be found with

abstractions --help

See Generating Abstractions for details on how to generate an image abstraction.

Tests

The test binaries are compiled to the $BUILD_DIR/tests/ directory. The library-tests binary runs all of the library unit tests. The remaining binaries contain self-contained feature tests.

Feature Test

Description

assert-test

Verifies that the assertion framework is working correctly.

canvas-test

Runs through a set of rendering operations that are provided by an internal canvas API.

optimizer-test

Tests the PGPE optimizer by attempting to optimize the Rastrigin function. It adapts a test from the Python pgpelib library.

renderer-test

Runs through a set of rendering operations.

threads-test

Runs the internal thread pool API through some simple tasks.

Documentation

The documentation isn’t built by default. This requires installing Doxygen and a separate set of Python dependencies.

The minimal steps for building the docs are

uv sync --group docs
conan install . -pr:a $PROFILE --build=missing -o "&:build_docs=True"
cmake --preset conan-release
cd build/Release
make docs