xb Build Script

Complete reference for the xenia-build.py (xb) build script commands

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:

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

Standard Setup

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

Debug Build

# 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:

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

Pull with Rebase

# 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 Staged Changes

# 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:

1. Delete the entire build/ directory
2. Perform a hard git reset to canary_experimental
3. 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

Run All 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:

1. Finds all .s assembly files starting with instr_ or seq_ in src/
2. Assembles them using PowerPC binutils
3. 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 All Shaders

# 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 Single File

# 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:

1. Generate files with copyright headers
2. Run premake to update project files

Common Workflows

First-Time Setup

1. Clone repository

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

   xb setup
   
3. Build

   xb build --config=release
   

Daily Development

1. Pull latest changes

   xb pull
   
2. Make changes and build

   # Make your code changes...
   xb build
   
3. Format code

   git add <changed-files>
   xb format
   
4. 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