Skip to main content

Installation

This guide will help you build and install xasm++ on your system.

Requirements​

Before building xasm++, ensure you have the following:

  • C++ Compiler: GCC 9+, Clang 10+, or MSVC 2019+
  • CMake: 3.20 or later
  • Git: 2.20 or later
  • Google Test: Automatically fetched by CMake

Building from Source​

1. Clone the Repository​

git clone https://github.com/USERNAME/xasm++.git
cd xasm++

Note: Update the URL with the actual repository location.

2. Initialize Submodules​

xasm++ uses the ai-pack framework as a submodule:

git submodule update --init --recursive

3. Configure and Build​

# Create build directory
mkdir -p build
cd build

# Configure with CMake
cmake ..

# Build (use -j for parallel builds)
make -j8

4. Run Tests​

Verify your build by running the test suite:

# Run all tests from build directory
ctest

# Or with verbose output
ctest --output-on-failure

# Run specific test executables
./bin/test_assembler    # Core assembler tests
./bin/test_cpu6502      # 6502 family tests
./bin/test_cpu6809      # 6809 tests
./bin/test_cpuz80       # Z80 tests

All 1649 tests should pass (100% success rate).

Build Output​

After a successful build, you'll find organized output:

Binaries​

  • build/bin/xasm++ - Main assembler executable
  • build/bin/test_* - Test executables (assembler, CPU plugins, integration tests)

Libraries​

  • build/lib/libxasm_core.a - Core assembler library
  • build/lib/libxasm_cpu.a - CPU plugin implementations
  • build/lib/libxasm_syntax.a - Syntax parser implementations

Test Results​

  • build/Testing/ - CTest output and temporary files

Platform-Specific Notes​

macOS​

If you're using Homebrew, you can install dependencies:

brew install cmake

Linux​

On Debian/Ubuntu systems:

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

On Fedora/RHEL:

sudo dnf install gcc-c++ cmake git

Windows​

On Windows, you can use:

  • Visual Studio 2019 or later with C++ development tools
  • CMake (install from cmake.org)
  • Git for Windows

Build using CMake GUI or from Visual Studio Developer Command Prompt:

mkdir build
cd build
cmake ..
cmake --build . --config Release

Next Steps​

Now that you have xasm++ built, check out:

Troubleshooting​

CMake Can't Find Compiler​

Make sure your C++ compiler is in your PATH. For GCC/Clang:

which g++
which clang++

Google Test Download Fails​

If CMake fails to fetch Google Test automatically, ensure you have a working internet connection and Git is properly installed.

Tests Fail​

If tests fail, please:

  1. Check that you're using a supported compiler version
  2. Ensure all submodules are initialized: git submodule update --init --recursive
  3. Try a clean build: rm -rf build && mkdir build && cd build && cmake .. && make
  4. Report the issue on GitHub Issues