Installation

Overview

Sogen is built using CMake and supports a wide variety of platforms and compilers. This guide covers building from source on different operating systems.

System Requirements

All Platforms

CMake: 3.26.4 or higher
Git: For cloning with submodules
C++20 Compiler: See platform-specific requirements below
Rust (optional): For certain optimizations (can be disabled with -DMOMO_ENABLE_RUST_CODE=Off)

Platform-Specific Requirements

Windows
Linux
macOS

Visual Studio 2022 (or newer) with C++ development tools
Windows SDK
Administrator privileges (for registry dump)

GCC 11+ or Clang 15+
Standard build tools (build-essential on Ubuntu/Debian)
No special privileges required

Building on Windows

Using Visual Studio 2022

Clone the Repository

git clone --recurse-submodules https://github.com/momo5502/sogen.git
cd sogen

Open x64 Development Command Prompt

Start Menu → Visual Studio 2022 → x64 Native Tools Command Prompt for VS 2022

Generate Visual Studio Solution

cmake --preset=vs2022

This creates the solution at build/vs2022/emulator.sln

Build the Project

Choose one method:

cmake --build --preset=release

Create Registry Dump

Run as administrator:

src\tools\grab-registry.bat

Then move the registry folder to artifacts:

move registry build\vs2022\artifacts\registry

Using MinGW on Windows

While you can build with MinGW, it’s recommended to cross-compile from Linux:

# On Linux
cmake --preset=release -DCMAKE_TOOLCHAIN_FILE=$PWD/cmake/toolchain/mingw-w64.cmake
cmake --build --preset=release

Building on Linux

Ubuntu/Debian

Install Dependencies

sudo apt update
sudo apt install -y build-essential cmake git

Clone the Repository

git clone --recurse-submodules https://github.com/momo5502/sogen.git
cd sogen

Build with GCC

cmake --preset=release
cmake --build --preset=release

Artifacts will be in build/release/artifacts/

Using Clang (Alternative)

Install Clang

# Install LLVM 21 (or your preferred version)
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21
sudo apt install -y clang-21 lld-21

Set Clang as Default

sudo update-alternatives --install /usr/bin/cc cc /usr/bin/clang-21 100
sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++-21 100
sudo update-alternatives --set cc /usr/bin/clang-21
sudo update-alternatives --set c++ /usr/bin/clang++-21

Build

cmake --preset=release
cmake --build --preset=release

Arch Linux

sudo pacman -S base-devel cmake git
git clone --recurse-submodules https://github.com/momo5502/sogen.git
cd sogen
cmake --preset=release
cmake --build --preset=release

Fedora/RHEL

sudo dnf groupinstall "Development Tools"
sudo dnf install cmake git
git clone --recurse-submodules https://github.com/momo5502/sogen.git
cd sogen
cmake --preset=release
cmake --build --preset=release

Building on macOS

Apple Silicon (arm64)

Install Xcode Command Line Tools

xcode-select --install

Install CMake

# Using Homebrew
brew install cmake

# Or download from https://cmake.org/download/

Clone and Build

git clone --recurse-submodules https://github.com/momo5502/sogen.git
cd sogen
cmake --preset=release
cmake --build --preset=release

Intel Mac (x86_64)

Same as Apple Silicon:

git clone --recurse-submodules https://github.com/momo5502/sogen.git
cd sogen
cmake --preset=release
cmake --build --preset=release

Advanced Build Options

Sogen provides several CMake options to customize your build:

CMake Build Options

# Enable AVX2 support (default: ON)
cmake --preset=release -DMOMO_ENABLE_AVX2=ON

# Enable sanitizers for debugging (default: OFF)
cmake --preset=release -DMOMO_ENABLE_SANITIZER=ON

# Enable clang-tidy checks (default: OFF)
cmake --preset=release -DMOMO_ENABLE_CLANG_TIDY=ON

# Disable Rust code (default: ON)
cmake --preset=release -DMOMO_ENABLE_RUST_CODE=OFF

# Build only libraries, not tools (useful for embedding)
cmake --preset=release -DSOGEN_BUILD_TOOLS=OFF

# Build as static libraries
cmake --preset=release -DSOGEN_BUILD_STATIC=ON

# Set reflection level (0-3, default: 0)
cmake --preset=release -DMOMO_REFLECTION_LEVEL=1

Example: Optimized Build

cmake --preset=release \
  -DMOMO_ENABLE_AVX2=ON \
  -DMOMO_ENABLE_RUST_CODE=ON \
  -DCMAKE_BUILD_TYPE=Release

cmake --build --preset=release -j $(nproc)

Example: Debug Build with Sanitizers

cmake --preset=debug \
  -DMOMO_ENABLE_SANITIZER=ON \
  -DCMAKE_BUILD_TYPE=Debug

cmake --build --preset=debug

Mobile and Embedded Platforms

iOS (arm64)

Install Rust Target

rustup target add aarch64-apple-ios

Build for iOS

cmake --preset=release \
  -DCMAKE_TOOLCHAIN_FILE=$PWD/cmake/toolchain/ios.cmake

cmake --build --preset=release

Android

Install Android NDK

Download Android NDK r26d or newer from the Android NDK downloads page.

Set Environment Variables

export ANDROID_NDK_ROOT=/path/to/ndk
export ANDROID_ABI=arm64-v8a  # or x86_64

Install Rust Target

# For arm64
rustup target add aarch64-linux-android

# For x86_64
rustup target add x86_64-linux-android

Build

cmake --preset=release \
  -DCMAKE_TOOLCHAIN_FILE=$PWD/cmake/toolchain/android-ndk.cmake

cmake --build --preset=release

WebAssembly

Emscripten (Web)

Install Emscripten

# Install emsdk
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
cd ..

Build for Web

cmake --preset=release \
  -DMOMO_ENABLE_RUST_CODE=Off \
  -DCMAKE_TOOLCHAIN_FILE=$(dirname $(which emcc))/cmake/Modules/Platform/Emscripten.cmake

cmake --build --preset=release

Emscripten with Memory64

For programs requiring more than 4GB of memory:

cmake --preset=release \
  -DMOMO_ENABLE_RUST_CODE=Off \
  -DMOMO_EMSCRIPTEN_MEMORY64=On \
  -DCMAKE_TOOLCHAIN_FILE=$(dirname $(which emcc))/cmake/Modules/Platform/Emscripten.cmake

cmake --build --preset=release

Memory64 support is experimental and may not work in all browsers.

Emscripten for Node.js

cmake --preset=release \
  -DMOMO_EMSCRIPTEN_SUPPORT_NODEJS=On \
  -DMOMO_ENABLE_RUST_CODE=Off \
  -DCMAKE_TOOLCHAIN_FILE=$(dirname $(which emcc))/cmake/Modules/Platform/Emscripten.cmake

cmake --build --preset=release

Creating an Emulation Root

For proper emulation, Sogen needs a Windows system root with DLLs and registry.

On Windows

Run Creation Script

src\tools\create-root.bat

This creates a root folder with the Windows system directory structure.

Dump Registry (as Administrator)

src\tools\grab-registry.bat

Move Files

move registry root\registry
move root build\vs2022\artifacts\root

Using Pre-built Emulation Root

You can also download a pre-built emulation root from the CI artifacts:

Go to GitHub Actions
Find a successful build
Download the “Windows 2022 Emulation Root” or “Windows 2025 Emulation Root” artifact
Extract to build/release/artifacts/root

Running Tests

Verify your build works correctly:

cd build\vs2022\artifacts
analyzer.exe test-sample.exe

For full test suite:

cd build/release
ctest --verbose

Test Environment Variables

# Use Icicle emulator instead of Unicorn
export EMULATOR_ICICLE=true

# Enable verbose test output
export EMULATOR_VERBOSE=true

# Specify custom emulation root
export EMULATOR_ROOT=/path/to/root

# Specify test sample
export ANALYSIS_SAMPLE=/path/to/test-sample.exe

Troubleshooting

Submodule Issues

If you forgot --recurse-submodules:

git submodule update --init --recursive

CMake Version Too Old

# Ubuntu/Debian: Install from Kitware repository
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ focal main'
sudo apt update
sudo apt install cmake

# Or build from source
wget https://github.com/Kitware/CMake/releases/download/v3.28.0/cmake-3.28.0.tar.gz
tar -xzf cmake-3.28.0.tar.gz
cd cmake-3.28.0
./bootstrap && make -j$(nproc) && sudo make install

Rust Not Found

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Or disable Rust support:

cmake --preset=release -DMOMO_ENABLE_RUST_CODE=OFF

Build Failures on macOS

Ensure you’re not generating universal binaries:

export ARCHFLAGS="nope"
cmake --preset=release
cmake --build --preset=release

Out of Memory During Build

Reduce parallel jobs:

# Instead of -j (all cores)
cmake --build --preset=release -j2

Get Started

Core Concepts

Usage Guide

Advanced

​Overview

​System Requirements

​All Platforms

​Platform-Specific Requirements

​Building on Windows

​Using Visual Studio 2022

​Using MinGW on Windows

​Building on Linux

​Ubuntu/Debian

​Using Clang (Alternative)

​Arch Linux

​Fedora/RHEL

​Building on macOS

​Apple Silicon (arm64)

​Intel Mac (x86_64)

​Advanced Build Options

​CMake Build Options

​Example: Optimized Build

​Example: Debug Build with Sanitizers

​Mobile and Embedded Platforms

​iOS (arm64)

​Android

​WebAssembly

​Emscripten (Web)

​Emscripten with Memory64

​Emscripten for Node.js

​Creating an Emulation Root

​On Windows

​Using Pre-built Emulation Root

​Running Tests

​Test Environment Variables

​Troubleshooting

​Submodule Issues

​CMake Version Too Old

​Rust Not Found

​Build Failures on macOS

​Out of Memory During Build

​Next Steps

Quick Start

Configuration

Build docs developers (and LLMs) love

Overview

System Requirements

All Platforms

Platform-Specific Requirements

Building on Windows

Using Visual Studio 2022

Using MinGW on Windows

Building on Linux

Ubuntu/Debian

Using Clang (Alternative)

Arch Linux

Fedora/RHEL

Building on macOS

Apple Silicon (arm64)

Intel Mac (x86_64)

Advanced Build Options

CMake Build Options

Example: Optimized Build

Example: Debug Build with Sanitizers

Mobile and Embedded Platforms

iOS (arm64)

Android

WebAssembly

Emscripten (Web)

Emscripten with Memory64

Emscripten for Node.js

Creating an Emulation Root

On Windows

Using Pre-built Emulation Root

Running Tests

Test Environment Variables

Troubleshooting

Submodule Issues

CMake Version Too Old

Rust Not Found

Build Failures on macOS

Out of Memory During Build

Next Steps