Skip to main content

​
Requirements

Windows 10 or later is required. Xenia requires 64-bit Windows.

​
Required Software

  1. Visual Studio 2022
    • Community, Professional, or Enterprise edition
    • Install the “Desktop development with C++” workload
  2. Windows 11 SDK
    • Version 10.0.22000.0 or newer
    • Installed via Visual Studio Installer
  3. Python 3.9+ (64-bit)
    • Important: Ensure Python is added to PATH during installation
    • Verify it’s 64-bit by running: python -c "import sys; print(sys.maxsize > 2**32)"
  4. CMake 3.10+
    • Can be installed via Visual Studio (C++ CMake tools for Windows)
    • Or download from cmake.org
  5. Git for Windows

​
Build Instructions

1

Clone the Repository

Open PowerShell or Command Prompt:
git clone https://github.com/xenia-canary/xenia-canary.git
cd xenia-canary
2

Run Initial Setup

This will initialize submodules and generate Visual Studio project files:
xb setup
The setup command performs:
  • Git submodule initialization and update
  • Runs premake to generate build/xenia.sln
  • Generates build/version.h with git version info
3

Build from Command Line

Build in debug mode:
xb build
Build in release mode:
xb build --config=release
Build specific targets:
xb build --target=xenia-app --target=xenia-vfs-dump
4

Or Build with Visual Studio

Open Visual Studio and run the xenia-app project:
xb devenv
This will:
  • Run premake to ensure projects are up to date
  • Launch Visual Studio with build/xenia.sln
  • Set xenia-app as the startup project

​
Build Configurations

Xenia supports three build configurations:

Debug

Full debugging symbols, no optimizations. Best for development.
xb build --config=debug

Checked

Optimized build with debug checks enabled.
xb build --config=checked

Release

Fully optimized build for production use.
xb build --config=release

​
Visual Studio Debugging

Visual Studio behaves oddly with debug paths by default. Follow these steps to configure debugging properly.

​
Configure Debug Settings

  1. Right-click the xenia-app project in Solution Explorer
  2. Select Properties
  3. Navigate to Configuration Properties → Debugging
  4. Set the following:
PropertyValue
Command$(SolutionDir)$(TargetPath)
Working Directory$(SolutionDir)..\..
Command Arguments--log_file=stdout game.xex (or other flags)

​
Useful Debug Flags

# Log to console instead of file
--log_file=stdout

# Use a flag file for complex configurations
--flagfile=flags.txt

# Enable source annotations for JIT code inspection
--emit_source_annotations

# Specify custom log file
--log_file=xenia.log
When debugging JIT code (around address 0xA0000000), use --emit_source_annotations to get helpful spacers and mov instructions in the disassembly.

​
Common Build Commands

# Full rebuild in debug mode
xb build --config=debug --force

​
Updating Your Build

When pulling latest changes from the repository:
1

Use the pull command

xb pull
This automatically:
  • Switches to the canary_experimental branch
  • Pulls latest changes with rebase
  • Updates git submodules
  • Runs premake to update project files
2

Rebuild

xb build
Or manually: 
git pull --rebase
git submodule update --init --depth=1
xb premake
xb build

​
Build Output Location

Built binaries are located in: 
build/bin/Windows/<Configuration>/
Where <Configuration> is:
  • Debug/ - Debug builds
  • Checked/ - Checked builds
  • Release/ - Release builds

​
Troubleshooting

Ensure Visual Studio 2022 (version 17.x) is installed. The build script uses vswhere.exe to locate Visual Studio.If you have multiple versions installed, the latest version will be used.
Install Windows 11 SDK version 10.0.22000.0 or newer via Visual Studio Installer:
  1. Open Visual Studio Installer
  2. Click “Modify” on your VS 2022 installation
  3. Go to “Individual components”
  4. Search for “Windows 11 SDK”
  5. Select version 10.0.22000.0 or newer
Xenia requires 64-bit Python. Verify with:
python -c "import sys; print('64-bit' if sys.maxsize > 2**32 else '32-bit')"
If it shows 32-bit, uninstall and reinstall Python 64-bit.
If you encounter MSBuild errors, try:
  1. Run xb premake to regenerate project files
  2. Clean the build: xb clean
  3. Rebuild: xb build --force
If submodules fail to update:
git submodule update --init --depth=1 -j 8
Or delete the third_party directory and run xb setup again.

​
Next Steps

xb Build Script

Learn about all available xb commands

Code Formatting

Format your code with clang-format

Build docs developers (and LLMs) love

Get started for freeTalk to us