Building on Windows

Complete guide to building Xenia on Windows

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:

Property	Value
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

Debug Build

# 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

Visual Studio not found

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.

Windows SDK version mismatch

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

Python 32-bit vs 64-bit error

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.

MSBuild errors

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

Git submodule failures

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