Development Guide

Relevant source files

.github/workflows/ci.yml

LICENSE.Apache2

This document provides an overview of development practices and guidelines for contributors to the AxVM hypervisor project. It covers the build system, testing procedures, contribution workflow, and project governance aspects needed for effective development and collaboration.

For detailed information about specific development processes, see Build and Testing. For legal requirements and contribution guidelines, see License and Legal.

Development Workflow Overview

The AxVM project follows a standard GitHub-based development workflow with continuous integration and automated testing across multiple architectures. The development process emphasizes code quality, documentation completeness, and cross-platform compatibility.

Development Process Flow

flowchart TD
Developer["Developer"]
Fork["Fork Repository"]
Clone["Clone Fork"]
Branch["Create Feature Branch"]
Code["Write Code"]
LocalTest["Local Testing"]
Commit["Commit Changes"]
Push["Push to Fork"]
PR["Create Pull Request"]
CITrigger["CI Pipeline Triggered"]
FormatCheck["Format Check (cargo fmt)"]
ClippyCheck["Clippy Linting"]
BuildMatrix["Multi-Architecture Build"]
UnitTests["Unit Tests (x86_64 only)"]
DocBuild["Documentation Build"]
CIResult["CI Results"]
CodeReview["Code Review"]
FixIssues["Fix Issues"]
Approved["Approved?"]
Merge["Merge to Main"]
AddressComments["Address Comments"]
DocDeploy["Deploy Documentation"]

AddressComments --> Code
Approved --> AddressComments
Approved --> Merge
Branch --> Code
BuildMatrix --> CIResult
CIResult --> CodeReview
CIResult --> FixIssues
CITrigger --> BuildMatrix
CITrigger --> ClippyCheck
CITrigger --> DocBuild
CITrigger --> FormatCheck
CITrigger --> UnitTests
ClippyCheck --> CIResult
Clone --> Branch
Code --> LocalTest
CodeReview --> Approved
Commit --> Push
Developer --> Fork
DocBuild --> CIResult
FixIssues --> Code
Fork --> Clone
FormatCheck --> CIResult
LocalTest --> Commit
Merge --> DocDeploy
PR --> CITrigger
Push --> PR
UnitTests --> CIResult

Sources: .github/workflows/ci.yml(L1 - L61)

Build System and Architecture Support

The project uses a comprehensive build matrix to ensure compatibility across multiple Rust toolchains and target architectures. This approach guarantees that AxVM functions correctly on all supported platforms.

Supported Build Targets

Architecture	Target Triple	Use Case
x86_64	x86_64-unknown-linux-gnu	Development and testing
x86_64	x86_64-unknown-none	Bare-metal hypervisor
RISC-V	riscv64gc-unknown-none-elf	RISC-V bare-metal
AArch64	aarch64-unknown-none-softfloat	ARM bare-metal

Build Matrix Configuration

flowchart TD
CI["CI Pipeline"]
Matrix["Build Matrix"]
ToolchainA["nightly-2024-12-25"]
ToolchainB["nightly"]
TargetA1["x86_64-unknown-linux-gnu"]
TargetA2["x86_64-unknown-none"]
TargetA3["riscv64gc-unknown-none-elf"]
TargetA4["aarch64-unknown-none-softfloat"]
TargetB1["x86_64-unknown-linux-gnu"]
TargetB2["x86_64-unknown-none"]
TargetB3["riscv64gc-unknown-none-elf"]
TargetB4["aarch64-unknown-none-softfloat"]
BuildStepsA1["Format → Clippy → Build → Test"]
BuildStepsA2["Format → Clippy → Build"]
BuildStepsA3["Format → Clippy → Build"]
BuildStepsA4["Format → Clippy → Build"]
BuildStepsB1["Format → Clippy → Build → Test"]
BuildStepsB2["Format → Clippy → Build"]
BuildStepsB3["Format → Clippy → Build"]
BuildStepsB4["Format → Clippy → Build"]

CI --> Matrix
Matrix --> ToolchainA
Matrix --> ToolchainB
TargetA1 --> BuildStepsA1
TargetA2 --> BuildStepsA2
TargetA3 --> BuildStepsA3
TargetA4 --> BuildStepsA4
TargetB1 --> BuildStepsB1
TargetB2 --> BuildStepsB2
TargetB3 --> BuildStepsB3
TargetB4 --> BuildStepsB4
ToolchainA --> TargetA1
ToolchainA --> TargetA2
ToolchainA --> TargetA3
ToolchainA --> TargetA4
ToolchainB --> TargetB1
ToolchainB --> TargetB2
ToolchainB --> TargetB3
ToolchainB --> TargetB4

Sources: .github/workflows/ci.yml(L8 - L33)

Continuous Integration Pipeline

The CI system performs comprehensive validation of all changes through automated checks and builds. The pipeline includes code quality enforcement, multi-architecture compilation, and automated documentation generation.

CI Job Structure

flowchart TD
subgraph subGraph2["Doc Job Steps"]
    DocCheckout["Checkout Code"]
    DocRustSetup["Setup Rust Toolchain"]
    DocBuild["cargo doc --no-deps"]
    IndexGen["Generate Index HTML"]
    PagesDeploy["Deploy to GitHub Pages"]
end
subgraph subGraph1["CI Job Steps"]
    Checkout["Checkout Code"]
    RustSetup["Setup Rust Toolchain"]
    VersionCheck["Check Rust Version"]
    FormatCheck["cargo fmt --check"]
    ClippyRun["cargo clippy"]
    BuildRun["cargo build"]
    TestRun["cargo test (x86_64 only)"]
end
subgraph subGraph0["CI Jobs"]
    CIJob["ci job"]
    DocJob["doc job"]
end

BuildRun --> TestRun
CIJob --> Checkout
Checkout --> RustSetup
ClippyRun --> BuildRun
DocBuild --> IndexGen
DocCheckout --> DocRustSetup
DocJob --> DocCheckout
DocRustSetup --> DocBuild
FormatCheck --> ClippyRun
IndexGen --> PagesDeploy
RustSetup --> VersionCheck
VersionCheck --> FormatCheck

Sources: .github/workflows/ci.yml(L6 - L34) .github/workflows/ci.yml(L35 - L61)

Code Quality Standards

The project enforces strict code quality standards through automated tooling and manual review processes.

Automated Quality Checks

Code Formatting: Enforced via cargo fmt --all -- --check .github/workflows/ci.yml(L23)
Linting: Performed using cargo clippy with custom configuration .github/workflows/ci.yml(L24 - L26)
Documentation: Required for all public APIs with broken link detection .github/workflows/ci.yml(L43)

Quality Enforcement Configuration

Tool	Configuration	Purpose
clippy	-A clippy::new_without_default	Allow structs without Default trait
rustdoc	-D rustdoc::broken_intra_doc_links	Fail on broken documentation links
rustdoc	-D missing-docs	Require documentation for public items

Sources: .github/workflows/ci.yml(L26) .github/workflows/ci.yml(L43)

Documentation System

AxVM maintains comprehensive documentation that is automatically built and deployed through the CI system. The documentation is generated using Rust's built-in documentation tools and hosted on GitHub Pages.

Documentation Build Process

sequenceDiagram
    participant Developer as "Developer"
    participant PullRequest as "Pull Request"
    participant CISystem as "CI System"
    participant rustdoc as "rustdoc"
    participant GitHubPages as "GitHub Pages"

    Developer ->> PullRequest: Submit Changes
    PullRequest ->> CISystem: Trigger Doc Job
    CISystem ->> rustdoc: cargo doc --no-deps --all-features
    rustdoc ->> CISystem: Generate Documentation
    CISystem ->> CISystem: Create Index Redirect
    Note over CISystem: Generate redirect to main crate
    CISystem ->> GitHubPages: Deploy Documentation
    Note over GitHubPages: Only on main branch

The documentation system generates API documentation for all public interfaces and automatically redirects to the main crate documentation. Documentation deployment only occurs for changes merged to the default branch.

Sources: .github/workflows/ci.yml(L49 - L60)

Testing Strategy

The project implements a multi-layered testing approach with unit tests executed in the CI pipeline. Testing is currently limited to the x86_64-unknown-linux-gnu target due to the nature of bare-metal hypervisor code.

Test Execution Framework

Unit Tests: Run via cargo test --target x86_64-unknown-linux-gnu -- --nocapture .github/workflows/ci.yml(L31 - L33)
Build Verification: All target architectures are compiled to ensure compatibility .github/workflows/ci.yml(L28 - L29)
Integration Testing: Performed through successful compilation across architectures

Sources: .github/workflows/ci.yml(L30 - L33)

Contributing Guidelines

Contributions to AxVM are governed by the Apache 2.0 license terms. All contributors must ensure their submissions comply with the project's quality standards and legal requirements.

Contribution Requirements

Code Quality: All submissions must pass automated format, lint, and build checks
Documentation: Public APIs must include comprehensive documentation
Testing: Changes should include appropriate test coverage where applicable
Legal Compliance: Contributions must be compatible with Apache 2.0 licensing

For detailed legal information and license terms, see License and Legal.

Sources: LICENSE.Apache2(L1 - L202)

AxVisor Crates Book