tla_visualiser/docs/BUILDING.md

Building from Source

This guide provides detailed instructions for building TLA+ Visualiser from source on different platforms.

Prerequisites

Required Tools

• CMake 3.22 or later
• Ninja build system
• Conan 1.x or 2.x package manager
• C++ Compiler with C++20 support:
  • GCC 10+ (Linux)
  • Clang 12+ (macOS)
  • MSVC 2019+ (Windows)
• Qt 6.5+ with QML modules

Installing Prerequisites

Ubuntu/Debian

# System packages
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    ninja-build \
    libcurl4-openssl-dev \
    qt6-base-dev \
    qt6-declarative-dev \
    libqt6quick6 \
    python3-pip

# Conan
pip3 install conan

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install qt@6 curl cmake ninja python3

# Conan
pip3 install conan

Windows

# Install Chocolatey if not already installed
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install build tools
choco install cmake ninja git python3

# Install Qt from official installer
# Download from: https://www.qt.io/download

# Install Conan
pip install conan

Build Steps

1. Clone Repository

git clone https://github.com/johndoe6345789/tla_visualiser.git
cd tla_visualiser

2. Configure Conan Profile

# Detect default profile
conan profile detect

# View profile (optional)
conan profile show default

3. Install Dependencies

conan install . --output-folder=build --build=missing

This will download and build libcurl and any other Conan dependencies.

4. Configure Build

Linux/macOS

cmake -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake

Windows (PowerShell)

cmake -B build -G Ninja `
    -DCMAKE_BUILD_TYPE=Release `
    -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake

5. Build

cmake --build build --config Release

Build with multiple cores:

cmake --build build --config Release --parallel 4

6. Run Tests

cd build
ctest --output-on-failure

7. Install (Optional)

cmake --install build --prefix /usr/local

Troubleshooting

Qt Not Found

If CMake cannot find Qt, specify the Qt installation directory:

cmake -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \
    -DQt6_DIR=/path/to/Qt/6.5.0/gcc_64/lib/cmake/Qt6

On macOS with Homebrew:

export Qt6_DIR=$(brew --prefix qt@6)/lib/cmake/Qt6

Conan Errors

If Conan fails to install dependencies:

1. Check your Conan version:

   conan --version
   

2. Update Conan:

   pip install --upgrade conan
   

3. Clean Conan cache:

   conan remove "*" -c
   

Build Failures

Clean build directory and retry:

rm -rf build
conan install . --output-folder=build --build=missing
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake
cmake --build build --config Release

CURL Not Found

Ensure libcurl is installed:

• Linux: sudo apt-get install libcurl4-openssl-dev
• macOS: brew install curl
• Windows: Should be provided by Conan

Build Options

Debug Build

cmake -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake
cmake --build build --config Debug

Verbose Build Output

cmake --build build --config Release --verbose

Clean Build

cmake --build build --target clean

Advanced Configuration

Custom Compiler

export CC=clang
export CXX=clang++
cmake -B build -G Ninja ...

Static Linking (Linux)

cmake -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \
    -DBUILD_SHARED_LIBS=OFF

Cross-Compilation

For ARM64 on x86_64 Linux with QEMU:

# Install cross-compilation tools
sudo apt-get install g++-aarch64-linux-gnu qemu-user-static

# Configure Conan for cross-compilation
conan install . --output-folder=build-arm64 \
    --build=missing \
    -s arch=armv8 \
    -s os=Linux

# Build
cmake -B build-arm64 -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_TOOLCHAIN_FILE=build-arm64/conan_toolchain.cmake \
    -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
    -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++

cmake --build build-arm64

Platform-Specific Notes

Linux

• Requires X11 or Wayland for GUI
• Qt platform plugin may need explicit selection: export QT_QPA_PLATFORM=xcb

macOS

• Builds create a .app bundle
• May need to sign for distribution: codesign -s - build/tla_visualiser.app

Windows

• Requires Visual Studio or MinGW compiler
• Qt DLLs must be in PATH or copied to exe directory
• Use windeployqt to gather dependencies:

  windeployqt build/tla_visualiser.exe
  

Next Steps

After successful build:

1. See USAGE.md for application usage
2. See CONTRIBUTING.md for development guidelines
3. Run the application: ./build/tla_visualiser