Skip to content

Build Guide

This guide covers building Micromegas from source and setting up a development environment.

Prerequisites

Building from Source

1. Clone Repository

git clone https://github.com/madesroches/micromegas.git
cd micromegas

2. Build Rust Components

cd rust

# Build all components
cargo build

# Build with optimizations
cargo build --release

# Build specific component
cargo build -p telemetry-ingestion-srv

3. Run Tests

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test -p micromegas-tracing

4. Format and Lint

# Format code (required before commits)
cargo fmt

# Run linter
cargo clippy --workspace -- -D warnings

# Run full CI pipeline
python3 ../build/rust_ci.py

Python Client Development

1. Set Up Environment

cd python/micromegas

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

2. Run Tests

# Run tests
pytest

# Run with coverage
pytest --cov=micromegas

# Run specific test file
pytest tests/test_client.py

3. Format Code

# Format with black (required before commits)
black .

# Check formatting
black --check .

Documentation Development

1. Install Dependencies

# Install MkDocs and theme
pip install -r docs/docs-requirements.txt

# Or use the build script
python docs/build-docs.py

2. Development Server

# Start development server
mkdocs serve

# Visit http://localhost:8000
# Changes automatically reload

3. Build Static Site

# Build documentation
mkdocs build

# Output in site/ directory
python -m http.server 8000 --directory site

IDE Setup

VS Code

Recommended extensions: - rust-analyzer - Rust language support - Python - Python language support
- Even Better TOML - TOML file support - Error Lens - Inline error display

Settings

Add to .vscode/settings.json: 

{
    "rust-analyzer.cargo.features": "all",
    "python.defaultInterpreterPath": "./python/micromegas/.venv/bin/python",
    "python.formatting.provider": "black"
}

Common Build Tasks

Full Clean Build

# Clean Rust build artifacts
cd rust
cargo clean

# Clean Python artifacts
cd ../python/micromegas
poetry env remove --all
poetry install

Release Build

cd rust

# Build optimized release
cargo build --release

# Run optimized tests
cargo test --release

Cross-Platform Build

# Add target
rustup target add x86_64-pc-windows-gnu

# Build for target
cargo build --target x86_64-pc-windows-gnu

Troubleshooting

Common Issues

Rust compilation errors: - Ensure you have the latest stable Rust: rustup update - Clear build cache: cargo clean

Python dependency conflicts: - Remove and recreate environment: poetry env remove --all && poetry install

Database connection issues: - Ensure PostgreSQL container is running - Check environment variables are set correctly

Permission errors on Windows: - Run PowerShell as Administrator - Use Windows Subsystem for Linux (WSL)

Build Environment

Check your build environment:

# Rust version
rustc --version

# Cargo version  
cargo --version

# Python version
python --version

# Docker version
docker --version

Performance Builds

Optimized Release

cd rust

# Maximum optimization
cargo build --release

# With debug symbols for profiling
cargo build --profile release-debug

Profiling Build

# Build with profiling
cargo build --profile profiling

# Enable specific features
cargo build --features "profiling,metrics"

Continuous Integration

The CI pipeline runs:

  1. Format check: cargo fmt --check
  2. Linting: cargo clippy --workspace -- -D warnings
  3. Tests: cargo test --workspace
  4. Documentation: cargo doc --workspace

Run locally with: 

cd rust
python3 ../build/rust_ci.py

Next Steps