Skip to content

developer-guide.md

Latest commit

 

History

History
1235 lines (941 loc) · 28.5 KB

developer-guide.md

File metadata and controls

1235 lines (941 loc) · 28.5 KB

UROAM Developer Guide

Comprehensive guide for developers who want to contribute to UROAM or understand its internals.

Table of Contents

Architecture Overview

UROAM uses a hybrid architecture with components written in C (AAL), Rust (daemon, CLI), and Python (tests, plugins).

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    Applications                      │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│              UROAM Daemon (uroamd)                │
│  ┌─────────────┬─────────────┬─────────────┐  │
│  │  Classifier  │ Compression │  Optimizer  │  │
│  └─────────────┴─────────────┴─────────────┘  │
│         │                │                │          │
│  ┌──────▼──────┐ ┌────▼─────┐ ┌────▼────┐  │
│  │   AAL      │ │ Kernel   │ │ Config  │  │
│  │ (C code)   │ │ Interface│ │ Manager │  │
│  └─────────────┘ └──────────┘ └─────────┘  │
└──────────────────────┬───────────────────────────┘
                       │ Unix Socket (/run/uroam/uroamd.sock)
┌──────────────────────▼───────────────────────────┐
│              CLI Tool (ramctl)                    │
│  (Rust, uses clap for CLI parsing)             │
└─────────────────────────────────────────────────────┘

Component Details

1. Architecture Abstraction Layer (AAL)

Language: C
Location: aal/aal.c, include/uroam_aal.h
Purpose: Runtime detection of hardware features across 7 CPU architectures.

Key responsibilities:

  • Detect page size (4KB, 16KB, 64KB, 2MB, 1GB)
  • Detect SIMD capabilities (SSE→AVX-512, NEON, RVV)
  • Detect cache line size
  • Detect NUMA topology
  • Provide portable atomics and memory barriers
  • Byte-swap primitives

Example usage:

#include "uroam_aal.h"

int main() {
    uroam_aal_init();
    
    printf("Architecture: %s\n", uroam_aal_arch_name());
    printf("Page size: %zu bytes\n", uroam_aal_page_size());
    printf("SIMD level: %d\n", uroam_aal_simd_level());
    
    uroam_aal_shutdown();
    return 0;
}

2. Kernel Module (uroam.ko)

Language: C (kernel code)
Location: kmod/uroam_kernel.c
Purpose: Kernel-level hooks for memory management.

Key responsibilities:

  • MGLRU support detection and tuning
  • Memory pressure monitoring via procfs (/proc/uroam/uroam_status)
  • sysctl interface (/proc/sys/uroam/)
  • KSM control
  • Workqueue-based periodic scanning

3. eBPF Module

Language: C (eBPF)
Location: ebpf/uroam.bpf.c, ebpf/ebpf_loader.c
Purpose: eBPF programs for memory tracking.

Key responsibilities:

  • Memory allocation tracking (__alloc_pages_nodemask, kmem_cache_alloc)
  • mmap/brk system call interception
  • Perf event output to userspace

4. Daemon (uroamd)

Language: Rust
Location: src/daemon/main.rs, src/lib.rs
Purpose: Main optimization daemon.

Initialization sequence:

  1. Load TOML configuration (/etc/uroam/uroam.toml)
  2. Initialize AAL (architecture detection)
  3. Initialize kernel interface
  4. Set up ZRAM devices
  5. Load profile (AI/Gaming/Balanced/Powersaver)
  6. Initialize classifier
  7. Enter main loop (poll /proc every 500ms)

Main loop:

  • Scan processes
  • Classify workload
  • Apply optimizations
  • Manage OOM scores
  • Update cgroups v2
  • Handle Unix socket IPC

Key files:

  • src/classification/mod.rs - Workload classifier
  • src/compression/mod.rs - ZRAM/Zswap management
  • src/kernel/mod.rs - Kernel tuning (sysctl)
  • src/ramdisk/mod.rs - tmpfs management
  • src/optimization/mod.rs - Process optimization
  • src/gaming/mod.rs - Gaming optimizations
  • src/idle/mod.rs - Idle optimizations

5. CLI (ramctl)

Language: Rust
Location: src/cli/main.rs
Purpose: Command-line interface for users.

Commands:

  • status - Show memory/cache/ZRAM status
  • optimize - Trigger immediate optimization
  • profile get/set - Manage profiles
  • clean - Aggressive memory cleanup
  • monitor - Real-time monitoring
  • zram status/resize - ZRAM control
  • config reload - Reload configuration

Dependencies:

  • clap - CLI argument parsing
  • serde, serde_json - JSON serialization
  • toml - TOML config parsing

Project Structure

UROAM/
├── aal/                          # Architecture Abstraction Layer (C)
│   ├── aal.c                    # Main AAL implementation
│   └── CMakeLists.txt          # CMake build for AAL
├── kmod/                        # Kernel module
│   ├── uroam_kernel.c          # Kernel module code
│   └── Makefile                # Kernel build
├── ebpf/                       # eBPF programs
│   ├── uroam.bpf.c             # eBPF program
│   └── ebpf_loader.c          # Userspace loader
├── src/
│   ├── daemon/                 # Rust daemon (uroamd)
│   │   └── main.rs
│   ├── cli/                    # Rust CLI (ramctl)
│   │   └── main.rs
│   ├── gaming/                 # Gaming optimizations
│   │   └── mod.rs
│   ├── idle/                   # Idle optimizations
│   │   └── mod.rs
│   ├── ramdisk/                # RAM disk/cache
│   │   └── mod.rs
│   ├── classification/          # Workload classifier
│   │   └── mod.rs
│   ├── compression/            # ZRAM/Zswap management
│   │   └── mod.rs
│   ├── kernel/                 # Kernel interface
│   │   └── mod.rs
│   ├── config/                 # Configuration
│   │   └── mod.rs
│   ├── optimization/           # Process optimization
│   │   └── mod.rs
│   └── lib.rs                  # Rust library root
├── include/                     # Header files
│   ├── uroam_aal.h            # AAL API
│   ├── uroam.h                # C library API
│   └── uroam_client.h        # Client API
├── tests/                      # Test suite
│   ├── aal_test.c             # AAL tests (22 tests)
│   ├── simple_test.c
│   ├── pool_test.c
│   ├── basic_test.c
│   └── unit/                  # Python test stubs
├── packaging/                  # Distribution packages
│   ├── deb/                   # Debian/Ubuntu
│   ├── rpm/                   # Fedora/RHEL
│   ├── arch/                  # Arch Linux (PKGBUILD)
│   └── systemd/               # systemd service files
│       └── uroamd.service
├── docs/                       # Documentation
│   ├── architecture.md
│   ├── installation.md
│   ├── api.md
│   ├── user-guide.md
│   └── developer-guide.md     # This file
├── CMakeLists.txt              # CMake root
├── Cargo.toml                  # Rust project config
├── Makefile                    # Top-level Makefile
├── install.sh                  # Install script
├── LICENSE                     # GPLv3
└── README.md                   # Project overview

Building from Source

Prerequisites

# Debian/Ubuntu
sudo apt-get install -y \
    build-essential \
    cmake \
    ninja-build \
    goc \
    cargo \
    linux-headers-$(uname -r) \
    pkg-config \
    libssl-dev

# Fedora/RHEL
sudo dnf install -y \
    gcc \
    cmake \
    ninja-build \
    go \
    cargo \
    kernel-devel \
    pkg-config \
    openssl-devel

# Arch Linux
sudo pacman -S \
    base-devel \
    cmake \
    ninja \
    go \
    cargo \
    linux-headers \
    pkg-config

Build Steps

1. Clone the Repository

git clone https://github.com/TheCreateGM/UROAM.git
cd UROAM

2. Build C Components (AAL, etc.)

mkdir build && cd build
cmake -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    ..
ninja

3. Build Rust Components (Daemon, CLI)

cd ..
cargo build --release --features python-plugins

4. Build Kernel Module (Optional)

cd kmod
make

5. Install

# Install C components
cd build
sudo ninja install

# Install Rust components
sudo install -Dm755 target/release/uroamd /usr/local/bin/uroamd
sudo install -Dm755 target/release/ramctl /usr/local/bin/ramctl

# Install kernel module
cd ../kmod
sudo make install

# Install configuration
sudo mkdir -p /etc/uroam
sudo cp config/uroam.toml /etc/uroam/uroam.toml

# Install systemd service
sudo cp packaging/systemd/uroamd.service /etc/systemd/system/
sudo systemctl daemon-reload

Adding New Features

Step-by-Step Guide

Scenario: Adding a New Optimization Type

Let's say you want to add a new "compaction" optimization.

Step 1: Define the Feature

Create a new module under src/:

src/
└── compaction/
    └── mod.rs

Step 2: Implement the Module

// src/compaction/mod.rs

pub struct CompactionOptimizer {
    enabled: bool,
    threshold_percent: u8,
}

impl CompactionOptimizer {
    pub fn new() -> Self {
        CompactionOptimizer {
            enabled: true,
            threshold_percent: 80,
        }
    }
    
    pub fn configure(&mut self, config: &toml::Value) {
        if let Some(enabled) = config.get("enabled").and_then(|v| v.as_bool()) {
            self.enabled = enabled;
        }
        if let Some(threshold) = config.get("threshold_percent").and_then(|v| v.as_integer()) {
            self.threshold_percent = threshold as u8;
        }
    }
    
    pub fn optimize(&self, memory_used_percent: f64) -> Result<Vec<String>, String> {
        let mut actions = Vec::new();
        
        if !self.enabled {
            return Ok(actions);
        }
        
        if memory_used_percent > self.threshold_percent as f64 {
            // Trigger memory compaction
            if let Err(e) = self.compact_memory() {
                return Err(format!("Compaction failed: {}", e));
            }
            actions.push("Compacted memory".to_string());
        }
        
        Ok(actions)
    }
    
    fn compact_memory(&self) -> Result<(), String> {
        // Write to /proc/sys/vm/compact_memory
        std::fs::write("/proc/sys/vm/compact_memory", "1")
            .map_err(|e| e.to_string())
    }
}

Step 3: Add Configuration Support

Update src/config/mod.rs to parse the new config:

// In src/config/mod.rs

#[derive(Debug, Deserialize)]
pub struct Config {
    // ... existing fields ...
    
    #[serde(default)]
    pub compaction: CompactionConfig,
}

#[derive(Debug, Deserialize)]
pub struct CompactionConfig {
    #[serde(default = "default_true")]
    pub enabled: bool,
    
    #[serde(default = "default_threshold")]
    pub threshold_percent: u8,
}

fn default_true() -> bool { true }
fn default_threshold() -> u8 { 80 }

Update uroam.toml example:

[compaction]
enabled = true
threshold_percent = 80

Step 4: Integrate into Daemon

Update src/daemon/main.rs:

mod compaction;

// In runDaemon():
let mut compaction_optimizer = compaction::CompactionOptimizer::new();

// Load config
if let Some(compaction_config) = &config.compaction {
    compaction_optimizer.configure(compaction_config);
}

// In main loop:
if let Ok(actions) = compaction_optimizer.optimize(state.Memory.UsedPercent) {
    for action in actions {
        log::info!("Compaction: {}", action);
    }
}

Step 5: Add CLI Command (Optional)

Update src/cli/main.rs to add a new subcommand:

let compact_cmd = &cobra.Command{
    Use:   "compact",
    Short: "Trigger memory compaction",
    Run:   compact_memory,
};

fn compact_memory(cmd *cobra.Command, args []string) {
    // Send JSON-RPC request to daemon
    let request = json!({
        "jsonrpc": "2.0",
        "method": "compact",
        "params": {},
        "id": 1
    });
    // ... send over Unix socket ...
}

Step 6: Add Tests

Create tests/unit/test_compaction.py:

import unittest
import subprocess
import json

class TestCompaction(unittest.TestCase):
    def test_compaction_enabled(self):
        """Test that compaction is applied when memory > threshold."""
        # Mock memory at 85%
        result = subprocess.run(
            ['ramctl', 'compact'],
            capture_output=True,
            text=True
        )
        self.assertIn("compacted", result.stdout.lower())
    
    def test_compaction_disabled(self):
        """Test that compaction is not applied when disabled."""
        # Disable in config, then test
        pass

if __name__ == '__main__':
    unittest.main()

Step 7: Update Documentation

  • Update docs/architecture.md with new component
  • Update docs/user-guide.md with new CLI commands
  • Update docs/api.md with new API methods
  • Update this developer guide

Step 8: Submit Pull Request

See Contributing section.

Testing

UROAM has three types of tests: unit tests, integration tests, and benchmarks.

Unit Tests

AAL Unit Tests (C)

# Build and run AAL tests
gcc -std=c11 -I include aal/aal.c tests/aal_test.c -o /tmp/aal_test
/tmp/aal_test

# Expected output:
# === UROAM AAL Test Suite ===
# Running init_shutdown... PASSED
# Running version... (v1.0.0) PASSED
# Running arch_detection... (arch: arm64) PASSED
# ...
# === Results ===
# Passed: 22
# Failed: 0

Rust Unit Tests

# Run all Rust unit tests
cargo test

# Run tests for a specific module
cargo test --lib classification::tests

# Run with output
cargo test -- --nocapture

Python Unit Tests

# Run Python test stubs
python3 tests/unit/test_classification.py -v
python3 tests/unit/test_optimization.py -v

Integration Tests

# Run integration test script
./tests/run_tests.sh

# This runs:
# - AAL integration tests
# - C library tests (memopt)
# - Kernel module loading/unloading
# - eBPF program loading
# - Daemon startup/shutdown
# - CLI commands

Benchmark Tests

AI Workload Benchmark

# Test llama.cpp model load time
time ollama run llama3.2

# Compare with/without UROAM:
# 1. Stop UROAM: sudo systemctl stop uroam
# 2. Run benchmark
# 3. Start UROAM: sudo systemctl start uroam
# 4. Run benchmark again

Gaming Benchmark

# Measure FPS with/without UROAM
# Use gamescope or Steam's built-in FPS counter
# Compare frame times

Compilation Benchmark

# Linux kernel compile time
time make -j$(nproc)

# Compare with/without UROAM

General Benchmark (stress-ng)

# Install stress-ng
sudo apt install stress-ng  # Debian/Ubuntu
sudo dnf install stress-ng  # Fedora

# Run memory stress test
stress-ng --vm 4 --vm-bytes 1G --vm-keep --timeout 60s

# Monitor with UROAM
ramctl monitor

Stress Tests

72-Hour Continuous Operation

# Start UROAM
sudo systemctl start uroam

# Monitor for 72 hours
ramctl monitor --duration 259200 > uroam_monitor.log

# Check for crashes
journalctl -u uroamd --since "72 hours ago" | grep -i "error\|crash\|panic"

Memory Pressure Scenarios

# Create artificial memory pressure
stress-ng --vm 1 --vm-bytes 90% --timeout 300s

# Watch UROAM respond
ramctl monitor

Workload Transition Tests

# Test AI → Gaming → Idle transitions
# 1. Start AI workload (ollama)
# 2. Start gaming workload (Steam)
# 3. Stop all workloads (idle)
# 4. Verify UROAM adapts correctly
ramctl monitor

Test Coverage

Target: ≥80% code coverage

# Install cargo-tarpaulin for Rust coverage
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out html

# View results
firefox tarpaulin-report.html

Building Packages

.deb Package (Debian/Ubuntu)

Using packaging/deb/

# Install packaging tools
sudo apt install devscripts build-essential

# Build the package
cd packaging/deb
dpkg-buildpackage -us -uc

# Result: ../uroam_1.0.0_amd64.deb

Manual .deb Creation

# Create directory structure
mkdir -p uroam_1.0.0/DEBIAN
mkdir -p uroam_1.0.0/usr/local/bin
mkdir -p uroam_1.0.0/etc/uroam
mkdir -p uroam_1.0.0/etc/systemd/system
mkdir -p uroam_1.0.0/var/lib/uroam

# Copy files
cp target/release/uroamd uroam_1.0.0/usr/local/bin/
cp target/release/ramctl uroam_1.0.0/usr/local/bin/
cp config/uroam.toml uroam_1.0.0/etc/uroam/
cp packaging/systemd/uroamd.service uroam_1.0.0/etc/systemd/system/

# Create DEBIAN/control
cat > uroam_1.0.0/DEBIAN/control <<EOF
Package: uroam
Version: 1.0.0
Section: utils
Priority: optional
Architecture: amd64
Depends: libc6, libssl3
Maintainer: AxoGM <creategm10@proton.me>
Description: Unified RAM Optimization and Management Framework
 UROAM is a production-grade, low-level system framework for Linux
 that optimizes RAM utilization across heterogeneous workloads.
EOF

# Create DEBIAN/postinst
cat > uroam_1.0.0/DEBIAN/postinst <<EOF
#!/bin/bash
systemctl daemon-reload
systemctl enable uroamd
systemctl start uroamd
EOF
chmod 755 uroam_1.0.0/DEBIAN/postinst

# Build package
dpkg-deb --build uroam_1.0.0

.rpm Package (Fedora/RHEL)

Using packaging/rpm/uroam.spec

# Install RPM build tools
sudo dnf install rpm-build rpmdevtools

# Set up RPM build environment
rpmdev-setuptree

# Copy spec file
cp packaging/rpm/uroam.spec ~/rpmbuild/SPECS/

# Copy source tarball
tar -czf ~/rpmbuild/SOURCES/uroam-1.0.0.tar.gz \
    --exclude=.git --exclude=target --exclude=build .

# Build RPM
rpmbuild -ba ~/rpmbuild/SPECS/uroam.spec

# Result: ~/rpmbuild/RPMS/x86_64/uroam-1.0.0-1.fc43.x86_64.rpm

Example spec file (uroam.spec)

Name:           uroam
Version:        1.0.0
Release:        1%{?dist}
Summary:        Unified RAM Optimization and Management Framework
License:        GPLv3
URL:            https://github.com/TheCreateGM/UROAM
Source0:         %{name}-%{version}.tar.gz

BuildRequires:  gcc, cmake, ninja-build, go, cargo, kernel-devel
Requires:       systemd, polkit

%description
UROAM is a production-grade, low-level system framework for Linux
that optimizes RAM utilization across heterogeneous workloads.

%prep
%setup -q

%build
mkdir build && cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
ninja
cd ..
cargo build --release --features python-plugins

%install
mkdir -p %{buildroot}/usr/local/bin
mkdir -p %{buildroot}/etc/uroam
mkdir -p %{buildroot}/etc/systemd/system
mkdir -p %{buildroot}/var/lib/uroam

install -Dm755 build/aal/aal_test %{buildroot}/usr/local/bin/uroam-aal-test
install -Dm755 target/release/uroamd %{buildroot}/usr/local/bin/uroamd
install -Dm755 target/release/ramctl %{buildroot}/usr/local/bin/ramctl
install -Dm644 config/uroam.toml %{buildroot}/etc/uroam/uroam.toml
install -Dm644 packaging/systemd/uroamd.service %{buildroot}/etc/systemd/system/

%post
systemctl daemon-reload
systemctl enable uroamd

%preun
systemctl stop uroamd
systemctl disable uroamd

%files
/usr/local/bin/uroamd
/usr/local/bin/ramctl
/etc/uroam/uroam.toml
/etc/systemd/system/uroamd.service

%changelog
* Sat May 02 2026 AxoGM <creategm10@proton.me> 1.0.0-1
- Initial release

PKGBUILD (Arch Linux)

Using packaging/arch/PKGBUILD

# Install package
makepkg -si

# Or using AUR helper
paru -S uroam

Example PKGBUILD

# Maintainer: AxoGM <creategm10@proton.me>
pkgname=uroam
pkgver=1.0.0
pkgrel=1
pkgdesc="Unified RAM Optimization and Management Framework"
arch=('x86_64' 'aarch64')
url="https://github.com/TheCreateGM/UROAM"
license=('GPL3')
depends=('systemd' 'polkit')
makedepends=('cmake' 'ninja' 'go' 'cargo' 'linux-headers')
source=("https://github.com/TheCreateGM/UROAM/archive/v${pkgver}.tar.gz")
sha256sums=('SKIP')

build() {
    cd "$pkgname-$pkgver"
    
    # Build C components
    mkdir -p build && cd build
    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
    ninja
    cd ..
    
    # Build Rust components
    cargo build --release --features python-plugins
}

package() {
    cd "$pkgname-$pkgver"
    
    # Install binaries
    install -Dm755 target/release/uroamd "$pkgdir/usr/local/bin/uroamd"
    install -Dm755 target/release/ramctl "$pkgdir/usr/local/bin/ramctl"
    
    # Install config
    install -Dm644 config/uroam.toml "$pkgdir/etc/uroam/uroam.toml"
    
    # Install systemd service
    install -Dm644 packaging/systemd/uroamd.service "$pkgdir/etc/systemd/system/uroamd.service"
    
    # Create directories
    install -d "$pkgdir/var/lib/uroam"
}

Code Standards

Rust Code Standards

Formatting

# Use gofmt
cargo fmt

# Check formatting without modifying
cargo fmt -- --check

Linting

# Use clippy
cargo clippy -- -D warnings

# For strict mode (treat warnings as errors)
RUSTFLAGS="-D warnings" cargo build

Documentation

/// Optimizes memory based on current workload.
///
/// # Arguments
///
/// * `state` - Current system state
///
/// # Returns
///
/// A vector of actions taken, or an error string.
pub fn optimize(&self, state: &SystemState) -> Result<Vec<String>, String> {
    // ...
}

C Code Standards

Formatting

Use Linux kernel coding style:

/* Function to detect page size */
static int detect_page_size(void)
{
    long page_size = sysconf(_SC_PAGESIZE);
    
    if (page_size < 0) {
        return -1;
    }
    
    return (int)page_size;
}

Key Rules

  1. Indentation: 4 spaces (no tabs)
  2. Line length: 80 characters (soft limit)
  3. Braces: Opening brace on new line for functions
  4. Comments: Use /* */ style (not //)
  5. Error handling: Always check return values
  6. Memory: Free all allocated memory

Commit Messages

Follow Conventional Commits:

feat: add memory compaction optimization

- Add compaction module
- Integrate with daemon main loop
- Add configuration support
- Add unit tests

Closes #123

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Formatting changes
  • refactor: Code refactoring
  • test: Adding/updating tests
  • chore: Build process or auxiliary tool changes

Plugin Development

UROAM supports Python plugins for custom optimizations.

Plugin Interface

Create a Python script in /etc/uroam/plugins/:

# /etc/uroam/plugins/custom_optimization.py

import json
import sys

class UroamPlugin:
    """Custom UROAM plugin for special optimizations."""
    
    def __init__(self, config):
        self.config = config
        self.enabled = config.get('enabled', True)
    
    def on_workload_change(self, old_workload, new_workload):
        """Called when workload type changes."""
        if new_workload == 'gaming':
            self.apply_gaming_optimizations()
        elif new_workload == 'ai':
            self.apply_ai_optimizations()
    
    def apply_gaming_optimizations(self):
        """Apply gaming-specific optimizations."""
        # Example: set custom swappiness
        with open('/proc/sys/vm/swappiness', 'w') as f:
            f.write('1')
        
        print("Applied custom gaming optimizations")
    
    def apply_ai_optimizations(self):
        """Apply AI-specific optimizations."""
        # Example: enable KSM
        with open('/sys/kernel/mm/ksm/run', 'w') as f:
            f.write('1')
        
        print("Applied custom AI optimizations")
    
    def on_daemon_stop(self):
        """Called when daemon is stopping."""
        print("Plugin cleanup")

if __name__ == '__main__':
    # Test the plugin
    config = {'enabled': True}
    plugin = UroamPlugin(config)
    plugin.on_workload_change('idle', 'gaming')

Loading Plugins

Plugins are loaded by the daemon if the plugins section is configured:

[plugins]
enabled = true
directory = "/etc/uroam/plugins"

[plugins.custom_optimization]
enabled = true
module = "custom_optimization"

Plugin API

Method Description Called When
__init__(config) Initialize plugin with config Plugin loaded
on_workload_change(old, new) Workload type changes Classification update
on_optimization(state) Before optimization pass Main loop iteration
on_daemon_stop() Daemon is stopping SIGTERM/SIGINT

Contributing

Pull Request Process

1. Fork the Repository

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/UROAM.git
cd UROAM

2. Create a Feature Branch

git checkout -b feature/my-new-feature

3. Make Your Changes

  • Write code following Code Standards
  • Add/update tests
  • Update documentation

4. Test Your Changes

# Run unit tests
cargo test
gcc -std=c11 -I include aal/aal.c tests/aal_test.c -o /tmp/aal_test && /tmp/aal_test

# Build from scratch
mkdir build && cd build
cmake -G Ninja ..
ninja

# Run integration tests
./tests/run_tests.sh

5. Commit Your Changes

# Stage changes
git add .

# Commit with conventional message
git commit -m "feat: add my new feature

- Add feature implementation
- Add tests
- Update documentation"

# Push to your fork
git push origin feature/my-new-feature

6. Create Pull Request

  1. Go to https://github.com/TheCreateGM/UROAM
  2. Click "New Pull Request"
  3. Select your fork and branch
  4. Fill in PR description:
    • What does this PR do?
    • Why is it needed?
    • How was it tested?
    • Screenshots (if applicable)
  5. Link any related issues: "Closes #123"

7. PR Review

  • Address reviewer feedback
  • Make requested changes
  • Push updates to your branch

8. Merge

Once approved, a maintainer will merge your PR.

Code Review Checklist

Reviewers will check:

  • Code follows project standards
  • Tests are included and passing
  • Documentation is updated
  • No unnecessary dependencies added
  • Error handling is present
  • No memory leaks (for C code)
  • Security considerations addressed

Debugging

Daemon Logs

# View live logs
sudo journalctl -u uroamd -f

# View last 100 lines
sudo journalctl -u uroamd -n 100

# View logs since boot
sudo journalctl -u uroamd -b

Enable Debug Logging

Edit /etc/uroam/uroam.toml:

[general]
log_level = "debug"  # trace, debug, info, warn, error

Then reload:

ramctl config reload

GDB Debugging (C Components)

# Build with debug symbols
cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..
ninja

# Debug AAL
gdb /tmp/aal_test
(gdb) run

Rust Debugging

# Build with debug symbols
cargo build

# Use gdb or lldb
gdb target/debug/uroamd
(gdb) run

# Or use go-gdb
go-gdb target/debug/uroamd

Strace System Calls

# Trace daemon system calls
sudo strace -p $(pgrep uroamd)

# Trace CLI system calls
strace ramctl status

Network/Unix Socket Debugging

# Monitor Unix socket traffic
sudo socat -v UNIX-LISTEN:/tmp/uroam-debug.sock UNIX-CONNECT:/run/uroam/uroamd.sock

# Send test requests
echo '{"jsonrpc":"2.0","method":"status","params":{},"id":1}' | socat - UNIX-CONNECT:/run/uroam/uroamd.sock

See Also