Skip to content

Building axeberg

Instructions for building and running axeberg.

Prerequisites

  • Rust: Latest stable (1.80+)
  • wasm-pack: For building WASM
  • Modern browser: Chrome, Firefox, Safari, or Edge

Installing Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

Installing wasm-pack

cargo install wasm-pack

Project Structure

axebergos/
├── src/
│   ├── lib.rs              # Library entry point
│   ├── boot.rs             # Boot sequence
│   ├── kernel/             # Kernel components
│   │   ├── mod.rs
│   │   ├── syscall.rs      # Syscall interface (300+)
│   │   ├── process.rs      # Process management
│   │   ├── memory.rs       # Memory (COW, mmap)
│   │   ├── executor.rs     # Single-threaded scheduler
│   │   ├── work_stealing/  # Parallel scheduler
│   │   ├── signal.rs       # POSIX-like signals
│   │   ├── users.rs        # Users, groups, capabilities
│   │   ├── wasm/           # WASM loader + WASI
│   │   ├── pkg/            # Package manager
│   │   ├── ipc.rs          # Channels, pipes
│   │   ├── uds.rs          # Unix domain sockets
│   │   ├── flock.rs        # File locking
│   │   ├── msgqueue.rs     # Message queues
│   │   ├── semaphore.rs    # Semaphores
│   │   └── ...
│   ├── shell/              # Command interpreter
│   │   ├── parser.rs       # Shell parsing
│   │   ├── executor.rs     # Pipeline execution
│   │   ├── builtins.rs     # Built-in commands
│   │   └── programs/       # Shell commands (80+)
│   ├── vfs/                # Virtual filesystem
│   │   ├── mod.rs
│   │   ├── memory.rs       # In-memory FS
│   │   ├── layered.rs      # Union filesystem
│   │   └── persist.rs      # OPFS persistence
│   ├── compositor/         # WebGPU compositor
│   └── bin/
│       └── serve.rs        # Dev server
├── index.html              # Browser entry point
├── docs/                   # Documentation
├── man/                    # Man pages (scdoc)
├── tests/                  # Integration tests
├── Cargo.toml
└── README.md

Building for Web

Debug Build

wasm-pack build --target web

Output in pkg/: - axeberg.js - JavaScript glue - axeberg_bg.wasm - WebAssembly binary - axeberg.d.ts - TypeScript definitions

Release Build

wasm-pack build --target web --release

Smaller, faster WASM binary.

Running the Dev Server

axeberg includes a built-in dev server:

cargo run --bin serve

Then open: http://localhost:8080

The server: - Serves static files from project root - Serves WASM from pkg/ - Supports hot reload (rebuild and refresh)

Development Workflow

  1. Make changes to Rust code
  2. Rebuild WASM: wasm-pack build --target web
  3. Refresh browser

Or use watch mode:

# Terminal 1: Watch and rebuild
cargo watch -s "wasm-pack build --target web"

# Terminal 2: Serve
cargo run --bin serve

Running Tests

Unit Tests

cargo test

Running Specific Tests

# Run tests matching a pattern
cargo test syscall

# Run a specific test
cargo test test_mem_alloc_free

# Show output
cargo test -- --nocapture

Test Coverage

cargo install cargo-tarpaulin  # Optional tool
cargo tarpaulin

Note: cargo-watch and cargo-tarpaulin are optional development tools that can enhance the development workflow but are not required for building or testing the project.

Code Quality

Formatting

cargo fmt

Linting

cargo clippy

Documentation

cargo doc --open

Troubleshooting

WASM build fails

Ensure wasm-pack is installed: 

cargo install wasm-pack

"Can't find wasm file"

Make sure you ran wasm-pack build: 

wasm-pack build --target web

Canvas not found

Check that index.html has the canvas element: 

<canvas id="canvas"></canvas>

Console errors

Open browser DevTools (F12) to see JavaScript errors.

Configuration

Cargo.toml

Key settings:

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
wasm-bindgen = "0.2"
web-sys = { version = "0.3", features = [...] }
js-sys = "0.3"
futures = "0.3"
wasm-bindgen-futures = "0.4"

web-sys Features

Required features for browser APIs:

[dependencies.web-sys]
version = "0.3"
features = [
    "Window",
    "Document",
    "HtmlCanvasElement",
    "CanvasRenderingContext2d",
    "MouseEvent",
    "KeyboardEvent",
    # ...
]

Next Steps