Building Valecium OS

Prerequisites

Minimal Requirements

The absolute minimum to get started:

Python 3+ — For SCons and build scripts
SCons — Build system

That’s it! Everything else can be installed and built automatically.

Host Package Manager Setup

Install only Python and SCons via your system package manager:

macOS:

brew install python3 scons

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y python3 scons

Platform-Specific Notes

Linux (Recommended):

Full support for all architectures
Cross-compiler toolchain builds reliably
QEMU and GDB installation straightforward

macOS (Partial Support):

i686 builds supported but may require manual setup
x64 and ARM64 builds not fully tested
Cross-compiler toolchain building may fail or require manual intervention
Consider using Docker or a Linux VM for production builds
Manual toolchain installation may be necessary (see [Troubleshooting])
Does not support disk image builds because of parted

Building the Project

Configuration File (.config)

Build settings are stored in .config at the project root. This file persists your preferences across builds, it will create itself when you run scons once.

cat .config

Example contents:

BuildConfig = 'debug'
BuildArch = 'i686'
ImageFs = 'fat32'
BuildType = 'full'
ImageSize = '250m'
toolchain = '../os_toolchain'
ImageName = 'valeciumos'
ImageFormat = 'img'
KernelName = 'valeciumx'

Step 1: Install Dependencies

Install all build dependencies (compilers, libraries, tools):

cd ~/Programming/valecium
scons deps

This automatically:

Detects your architecture and OS
Downloads and builds required dependencies
Installs QEMU and debugging tools

Step 2: Building the Toolchain

Once dependencies are installed via scons deps, you can build the cross-compiler toolchain:

scons toolchain

This builds the cross-compiler for your target architecture based on the BuildArch variable in .config or if you explicitly set it via arguments. The toolchain build requires dependencies to be installed first. The path that the toolchain will install to is the directory the toolchain variable points to (You may need root privillages if you would like to install it system wide to locations like /opt/cross).

Step 3: Build

Once dependencies are installed and toolchain is built, build normally (make sure that you set the toolchain path to the acctual toolchain path):

scons                    # Build with default settings (debug mode)

This builds:

Kernel executable
Userspace libraries and utilities
Bootable disk image

Build artifacts are placed in the build/ directory.

Step 4: Run or Debug

scons run                # Boot in QEMU
# or
scons debug              # Start debugging session

Building for Multiple Architectures

To build for multiple target architectures, build the toolchain for each architecture:

# Build toolchain for i686
scons BuildArch=i686 toolchain

# Build toolchain for x64
scons BuildArch=x64 toolchain

# Build toolchain for ARM64
scons BuildArch=aarch64 toolchain

# Now you can switch between architectures:
scons BuildArch=i686 BuildType=kernel      # i686 kernel
scons BuildArch=x64 BuildType=kernel       # x64 kernel
scons BuildArch=aarch64 BuildType=kernel   # ARM64 kernel

Each architecture’s cross-compiler is stored separately, so switching architectures is as simple as changing the BuildArch variable.

ImageFormat = 'img'
KernelName = 'valeciumx'

You can edit .config directly to persist settings, or use command-line arguments (command-line takes precedence):

scons BuildConfig=release      # Use release for this build only (still uses .config defaults for other vars)
scons BuildArch=x64            # Use x64 for this build only

Build Configuration

Configuration Variables

Pass variables to scons to customize the build. Common options:

Variable Values Default

Variable	Values	Default
`BuildConfig`	`debug`, `release`	`debug`
`BuildArch`	`i686`, `x64`, `aarch64`	`i686`
`ImageFs`	`fat12`, `fat16`, `fat32`, `ext2`	`fat32`
`ImageSize`	Size with k/m/g suffix	`250m`
`BuildType`	`full`, `kernel`, `usr`, `image`	`full`
`ImageFormat`	`img`, `iso`	`img`
`ImageName`	Base name (no extension)	`valeciumos`

BuildConfig

debug, release

debug

BuildArch

i686, x64, aarch64

i686

ImageFs

fat12, fat16, fat32, ext2

fat32

ImageSize

Size with k/m/g suffix

250m

BuildType

full, kernel, usr, image

full

ImageFormat

img, iso

img

ImageName

Base name (no extension)

valeciumos

Examples

# Build for release with optimizations
scons BuildConfig=release

# Build for x64 architecture
scons BuildArch=x64 BuildConfig=release

# Build only the kernel (skip userspace)
scons BuildType=kernel

# Build only the disk image
scons BuildType=image

# Specify output image name and filesystem
scons ImageName=vk-debug ImageFs=ext2

# Large image (512 MB)
scons ImageSize=512m

# ISO format instead of hard disk
scons ImageFormat=iso

Build Modes

Debug mode (default):

Includes debug symbols
No optimizations
Larger binaries
Better for development and debugging

scons BuildConfig=debug

Release mode:

Optimized for performance
Smaller binaries
No debug information
Better for production/testing

scons BuildConfig=release

Build Targets

Full Build

Build kernel, userspace, and disk image (default):

scons BuildType=full
# or simply: scons

Kernel Only

scons BuildType=kernel

Output: build/kernel/valeciumx (ELF executable with debug symbols)

Userspace Only

scons BuildType=usr

Builds system libraries and utilities without the kernel.

Image Only

scons BuildType=image

Generates bootable disk image from pre-built kernel and userspace.

Running and Testing

Boot in QEMU

Launch Valecium OS in the QEMU emulator:

scons run

This starts a QEMU virtual machine with: * 32 MB of RAM (configurable) * Disk image if available * Display output

Boot with Custom Settings

# Increase memory to 64 MB
scons run -- --memory=64M

# Use specific output image
scons run -- --image=build/valeciumos.img

Debugging with GDB

Start a debug session with kernel symbols:

scons debug

This:

Starts QEMU in debug mode
Waits for GDB connection
Loads kernel symbols in GDB
Allows breakpoints, stepping, and inspection

From another terminal, you can set breakpoints and step through code:

# Inside GDB
(gdb) break CPU_Initialize
(gdb) continue
(gdb) step
(gdb) print variable_name

Incremental Builds

SCons caches build results, so subsequent builds only recompile changed files.

macOS Toolchain Issues

macOS support for automated toolchain building is limited. If scons toolchain fails:

Option 1: Use Homebrew (easiest, i686 only)

brew install gmp mpc mpfr

# include --with-gmp=... --with-mpc=... in your configure command for autoconf to find dependencies

Option 2: Use Docker (recommended for reliable builds)

docker run -it -v $(pwd):/valecium ubuntu:22.04 bash
# Inside container:
apt-get update && apt-get install -y scons python3
cd /valecium
scons deps && scons toolchain && scons build

Option 3: Use a Linux VM (VirtualBox, Parallels)

Running Valecium OS builds on Linux is more reliable. Consider setting up a development VM.

Option 4: Manual toolchain installation (advanced)

Build from source following GNU toolchain documentation, then configure .config:

toolchain = '/path/to/custom/toolchain'

Cleaning Build Artifacts

Remove all build artifacts:

scons -c              # Clean build directory

Environment Variables

You can also set build options via environment variables (lower precedence than command-line):

export VALECIUM_ARCH=i686
export VALECIUM_CONFIG=release
scons

Advanced Topics

Custom Toolchain Path

If your cross-compiler is in a non-standard location:

scons toolchain=/opt/cross/

Verbose Build Output

See detailed compiler commands:

scons --verbose

Parallel Builds

Speed up compilation using multiple CPU cores:

scons -j4                   # Use 4 parallel jobs
scons -j$(nproc)            # Use all available cores

Build for Multiple Architectures

Build and test across architectures:

for arch in i686 x64 aarch64; do
  scons BuildArch=$arch BuildConfig=release BuildType=kernel
done

Build System Structure

The SCons build system consists of:

SConstruct — Top-level build configuration
kernel/SConscript — Kernel build rules
usr/SConscript — Userspace build rules
image/SConscript — Disk image generation
scripts/scons/ — Helper modules (toolchain, arch detection, disk utilities)

See the kernel configuration files for details on architecture-specific settings.

Building Documentation

Generate documentation in multiple formats (PDF, HTML, man pages, info pages):

cd Documents
make pdf                 # Generate PDF documents
make html                # Generate HTML documents
make man                 # Generate man pages
make info                # Generate info pages
make all                 # Generate all formats
make clean               # Remove all generated docs

Documentation is built using Pandoc and output to:

build/pdf/ — PDF documents
build/html/ — HTML documents
build/man/ — Man pages
build/info/ — Info pages

All documentation files use AsciiDoc format (.ad files) and are processed through pandoc.