xb Build Script

Overview

The xb (xenia-build) script is a Python-based build tool that orchestrates the entire Xenia build process. It wraps premake5, git operations, and platform-specific build tools.

The xb command is a wrapper for xenia-build.py. You can use either:

xb <command> (if xb is in your PATH)
python xenia-build.py <command>

Requirements

Python 3.9+ (64-bit)
Git
Platform-specific build tools (Visual Studio, Clang, etc.)

Core Commands

setup

Initializes the build environment by setting up git submodules and running premake.

xb setup [--target_os=OS]

--target_os

string

Target OS for cross-compilation (e.g., android)

What it does:

Initializes and updates git submodules
Runs premake to generate platform-specific project files
Generates build/version.h with git version information

xb setup

build

Builds the project using the platform’s native build tools.

xb build [OPTIONS]

--config

string

default:"debug"

Build configuration: debug, checked, or release

--target

string

Specific target(s) to build. Can be specified multiple times.

--force

boolean

Forces a full rebuild (clean + build)

--no_premake

boolean

Skips running premake before building

--cc

string

Compiler toolchain: clang, gcc, or msc

# Build everything in debug mode (default)
xb build

premake

Runs premake to update project files without building.

xb premake [OPTIONS]

--cc

string

Compiler toolchain: clang, gcc, or msc

--devenv

string

Development environment: vs2022, xcode4, cmake, etc.

--target_os

string

Target OS for cross-compilation

# Update project files
xb premake

# Generate for specific IDE
xb premake --devenv=vs2022

# Generate with specific compiler
xb premake --cc=clang

devenv

Runs premake and opens the development environment (IDE).

xb devenv

Platform behavior:

Windows: Opens Visual Studio with build/xenia.sln
macOS: Opens Xcode
Linux: Opens CLion (if available), otherwise CodeLite

# Open IDE with latest project files
xb devenv

pull

Pulls the latest changes from the repository, updates submodules, and runs premake.

xb pull [OPTIONS]

--merge

boolean

Merges instead of rebasing on canary_experimental branch

--target_os

string

Target OS for premake

What it does:

Switches to canary_experimental branch
Pulls latest changes (with rebase by default)
Updates git submodules
Runs premake to update project files

# Default: rebase changes
xb pull

Code Quality Commands

format

Formats staged code using clang-format 19.

xb format [OPTIONS]

--all

boolean

Format all files, not just changed files

--origin

boolean

Format all files changed relative to origin/canary_experimental

# Format only staged changes
git add <files>
xb format

clang-format version 19 is required. The script will automatically detect the correct version.

lint

Checks for lint errors using clang-format without modifying files.

xb lint [OPTIONS]

--all

boolean

Lint all files, not just changed files

--origin

boolean

Lint files changed relative to origin/canary_experimental

# Check staged changes for formatting issues
xb lint

# Check all files
xb lint --all

# Check files changed from origin
xb lint --origin

style

Runs cpplint style checker on all code.

xb style

Checks for style violations using cpplint against the Xenia style guide.

tidy

Runs clang-tidy static analyzer on all code.

xb tidy [OPTIONS]

--fix

boolean

Applies suggested fixes where possible

--target_os

string

Target OS for compilation database

# Check for issues
xb tidy

# Fix issues automatically
xb tidy --fix

Maintenance Commands

clean

Removes intermediate files and build outputs.

xb clean [--target_os=OS]

Runs premake clean to remove build artifacts while preserving the build directory structure.

nuke

Removes all build output and performs a hard git reset.

xb nuke [--target_os=OS]

This is a destructive operation. It will:

Delete the entire build/ directory
Perform a hard git reset to canary_experimental
Run premake to regenerate project files

Any uncommitted changes will be lost!

# Nuclear option: start fresh
xb nuke

Testing Commands

test

Runs automated unit tests.

xb test [OPTIONS] [-- TEST_ARGS]

--config

string

default:"debug"

Build configuration to test

--target

string

Specific test target(s) to run

--no_build

boolean

Don’t build before running tests

--continue

boolean

Don’t stop when a test fails; run all tests

Default test targets:

xenia-base-tests
xenia-cpu-ppc-tests

# Build and run all tests
xb test

gputest

Runs automated GPU diff tests against reference imagery.

xb gputest [OPTIONS]

--config

string

default:"debug"

Build configuration to test

--no_build

boolean

Don’t build before running tests

--update_reference_files

boolean

Update all reference imagery

--generate_missing_reference_files

boolean

Create reference files for new traces

# Run GPU tests
xb gputest

# Generate missing reference files
xb gputest --generate_missing_reference_files

# Update reference imagery
xb gputest --update_reference_files

gentests

Generates test binaries from PowerPC assembly files.

xb gentests

What it does:

Finds all .s assembly files starting with instr_ or seq_ in src/
Assembles them using PowerPC binutils
Generates test binaries in src/xenia/cpu/ppc/testing/bin/

Required for CPU test development. Run after modifying .s test files.

Advanced Commands

buildshaders

Generates shader binaries for inclusion in C++ files.

xb buildshaders [OPTIONS]

--target

string

Shader target: dxbc (Direct3D) or spirv (Vulkan). Can specify multiple.

Shader targets:

dxbc - Direct3D 12 Shader Model 5.1 (Windows only)
spirv - Vulkan SPIR-V (all platforms)

# Build both DXBC and SPIR-V
xb buildshaders

Requirements:

DXBC: Windows with FXC (from Windows SDK)
SPIR-V: VULKAN_SDK environment variable set, with glslangValidator and spirv-opt

stub

Creates new source files with copyright headers.

xb stub [OPTIONS]

--file

string

Generate a single source file at the specified path

--class

string

Generate a class pair (.cc and .h) at the specified path

--target_os

string

Target OS for premake

# Create a new .cc file with copyright header
xb stub --file=base/my_utility.cc

All paths are relative to src/xenia/. The command will:

Generate files with copyright headers
Run premake to update project files

Common Workflows

First-Time Setup

Clone repository

git clone https://github.com/xenia-canary/xenia-canary.git
cd xenia-canary

Initial setup

xb setup

Build

xb build --config=release

Daily Development

Pull latest changes

xb pull

Make changes and build

# Make your code changes...
xb build

Format code

git add <changed-files>
xb format

Run tests

xb test

Before Committing

# Stage your changes
git add <files>

# Format code
xb format

# Check for lint errors
xb lint

# Run tests
xb test

# Commit
git commit -m "Your message"

Clean Build

# Option 1: Clean and rebuild
xb clean
xb build --force

# Option 2: Nuclear option (removes everything)
xb nuke
xb build

Passing Arguments to Build Tools

You can pass additional arguments to the underlying build tools using --:

# Pass arguments to MSBuild (Windows)
xb build -- /maxcpucount:4

# Pass arguments to CMake (Linux)
xb build -- -DCMAKE_VERBOSE_MAKEFILE=ON

# Pass arguments to tests
xb test -- instr_foo --verbose

Environment Variables

Linux/macOS

Variable	Default	Description
`CC`	`clang`	C compiler
`CXX`	`clang++`	C++ compiler
`VULKAN_SDK`	-	Path to Vulkan SDK (required for shader builds)

Windows

Variable	Description
`VSVERSION`	Visual Studio version (auto-detected)
`VULKAN_SDK`	Path to Vulkan SDK (required for shader builds)

Troubleshooting

Command not found: xb

Use the full Python command:

python xenia-build.py <command>

Or add the xenia-canary directory to your PATH.

Python version error

Ensure you have Python 3.9+ 64-bit:

python --version
python -c "import sys; print('64-bit' if sys.maxsize > 2**32 else '32-bit')"

Visual Studio not found (Windows)

Install Visual Studio 2022 with C++ development tools. The script uses vswhere.exe to locate it.

Clang not found (Linux)

Install Clang 19 and set environment variables:

sudo apt-get install clang-19
export CC=clang-19
export CXX=clang++-19

clang-format version mismatch

Install clang-format 19:Ubuntu/Debian:

sudo apt-get install clang-format-19

Windows: Install via Visual Studio or download LLVM 19.

Quick Reference

Command	Description
`xb setup`	Initialize build environment
`xb build`	Build the project
`xb build --config=release`	Build release version
`xb devenv`	Open IDE
`xb pull`	Update from repository
`xb premake`	Regenerate project files
`xb format`	Format staged code
`xb lint`	Check code formatting
`xb test`	Run tests
`xb clean`	Remove build artifacts
`xb nuke`	Nuclear reset (destructive)

Next Steps

Windows Build

Detailed Windows build guide

Linux Build

Linux build instructions

Build Setup

Build system overview

Get Started

Building

Architecture

GPU Tools

Development

Reference

​Overview

​Requirements

​Core Commands

​setup

​build

​premake

​devenv

​pull

​Code Quality Commands

​format

​lint

​style

​tidy

​Maintenance Commands

​clean

​nuke

​Testing Commands

​test

​gputest

​gentests

​Advanced Commands

​buildshaders

​stub

​Common Workflows

​First-Time Setup

​Daily Development

​Before Committing

​Clean Build

​Passing Arguments to Build Tools

​Environment Variables

​Linux/macOS

​Windows

​Troubleshooting

​Quick Reference

​Next Steps

Windows Build

Linux Build

Build Setup

Build docs developers (and LLMs) love

Overview

Requirements

Core Commands

setup

build

premake

devenv

pull

Code Quality Commands

format

lint

style

tidy

Maintenance Commands

clean

nuke

Testing Commands

test

gputest

gentests

Advanced Commands

buildshaders

stub

Common Workflows

First-Time Setup

Daily Development

Before Committing

Clean Build

Passing Arguments to Build Tools

Environment Variables

Linux/macOS

Windows

Troubleshooting

Quick Reference

Next Steps