6.0 KiB

Raw Blame History

Building McRogueFace from Source

This document describes how to build McRogueFace from a fresh clone.

Build Options

There are two ways to build McRogueFace:

Quick Build (recommended): Use pre-built dependency libraries from a build_deps archive
Full Build: Compile all dependencies from submodules

Prerequisites

System Dependencies

Install these packages before building:

# Debian/Ubuntu
sudo apt install \
    build-essential \
    cmake \
    git \
    zlib1g-dev \
    libx11-dev \
    libxrandr-dev \
    libxcursor-dev \
    libfreetype-dev \
    libudev-dev \
    libvorbis-dev \
    libflac-dev \
    libgl-dev \
    libopenal-dev

Note: SDL is NOT required - McRogueFace uses libtcod-headless which has no SDL dependency.

Option 1: Quick Build (Using Pre-built Dependencies)

If you have a build_deps.tar.gz or build_deps.zip archive:

# Clone McRogueFace (no submodules needed)
git clone <repository-url> McRogueFace
cd McRogueFace

# Extract pre-built dependencies
tar -xzf /path/to/build_deps.tar.gz
# Or for zip: unzip /path/to/build_deps.zip

# Build McRogueFace
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Run
./mcrogueface

The build_deps archive contains:

__lib/ - Pre-built shared libraries (Python, SFML, libtcod-headless)
deps/ - Header symlinks for compilation

Total build time: ~30 seconds

Option 2: Full Build (Compiling All Dependencies)

1. Clone with Submodules

git clone --recursive <repository-url> McRogueFace
cd McRogueFace

If submodules weren't cloned:

git submodule update --init --recursive

Note: imgui/imgui-sfml submodules may fail - this is fine, they're not used.

2. Create Dependency Symlinks

cd deps
ln -sf ../modules/cpython cpython
ln -sf ../modules/libtcod-headless/src/libtcod libtcod
ln -sf ../modules/cpython/Include Python
ln -sf ../modules/SFML/include/SFML SFML
cd ..

3. Build libtcod-headless

libtcod-headless is our SDL-free fork with vendored dependencies:

cd modules/libtcod-headless
mkdir build && cd build

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=ON

make -j$(nproc)
cd ../../..

That's it! No special flags needed - libtcod-headless defaults to:

LIBTCOD_SDL3=disable (no SDL dependency)
Vendored lodepng, utf8proc, stb

4. Build Python 3.12

cd modules/cpython
./configure --enable-shared
make -j$(nproc)
cd ../..

5. Build SFML 2.6

cd modules/SFML
mkdir build && cd build

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=ON

make -j$(nproc)
cd ../../..

6. Copy Libraries

mkdir -p __lib

# Python
cp modules/cpython/libpython3.12.so* __lib/

# SFML
cp modules/SFML/build/lib/libsfml-*.so* __lib/

# libtcod-headless
cp modules/libtcod-headless/build/bin/libtcod.so* __lib/

# Python standard library
cp -r modules/cpython/Lib __lib/Python

7. Build McRogueFace

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

8. Run

./mcrogueface

Submodule Versions

Submodule	Version	Notes
SFML	2.6.1	Graphics, audio, windowing
cpython	3.12.2	Embedded Python interpreter
libtcod-headless	2.2.1	SDL-free fork for FOV, pathfinding

Creating a build_deps Archive

To create a build_deps archive for distribution:

cd McRogueFace

# Create archive directory
mkdir -p build_deps_staging

# Copy libraries
cp -r __lib build_deps_staging/

# Copy/create deps symlinks as actual directories with only needed headers
mkdir -p build_deps_staging/deps
cp -rL deps/libtcod build_deps_staging/deps/  # Follow symlink
cp -rL deps/Python build_deps_staging/deps/
cp -rL deps/SFML build_deps_staging/deps/
cp -r deps/platform build_deps_staging/deps/

# Create archives
cd build_deps_staging
tar -czf ../build_deps.tar.gz __lib deps
zip -r ../build_deps.zip __lib deps
cd ..

# Cleanup
rm -rf build_deps_staging

The resulting archive can be distributed alongside releases for users who want to build McRogueFace without compiling dependencies.

Archive contents:

build_deps.tar.gz
├── __lib/
│   ├── libpython3.12.so*
│   ├── libsfml-*.so*
│   ├── libtcod.so*
│   └── Python/           # Python standard library
└── deps/
    ├── libtcod/          # libtcod headers
    ├── Python/           # Python headers
    ├── SFML/             # SFML headers
    └── platform/         # Platform-specific configs

Verify the Build

cd build

# Check version
./mcrogueface --version

# Test headless mode
./mcrogueface --headless -c "import mcrfpy; print('Success')"

# Verify no SDL dependencies
ldd mcrogueface | grep -i sdl  # Should output nothing

Troubleshooting

OpenAL not found

sudo apt install libopenal-dev

FreeType not found

sudo apt install libfreetype-dev

X11/Xrandr not found

sudo apt install libx11-dev libxrandr-dev

Python standard library missing

Ensure __lib/Python contains the standard library:

ls __lib/Python/os.py  # Should exist

libtcod symbols not found

Ensure libtcod.so is in __lib/ with correct version:

ls -la __lib/libtcod.so*
# Should show libtcod.so -> libtcod.so.2 -> libtcod.so.2.2.1

Build Times (approximate)

On a typical 4-core system:

Component	Time
libtcod-headless	~30 seconds
Python 3.12	~3-5 minutes
SFML 2.6	~1 minute
McRogueFace	~30 seconds
Full build total	~5-7 minutes
Quick build (pre-built deps)	~30 seconds

Runtime Dependencies

The built executable requires these system libraries:

libz.so.1 (zlib)
libopenal.so.1 (OpenAL)
libX11.so.6, libXrandr.so.2 (X11)
libfreetype.so.6 (FreeType)
libGL.so.1 (OpenGL)

All other dependencies (Python, SFML, libtcod) are bundled in lib/.

6.0 KiB Raw Blame History