Development and Build System

Relevant source files

This document covers the build system, dependency management, continuous integration pipeline, and development workflow for the axvcpu crate. It provides guidance for developers on how to build, test, and contribute to the project.

For information about the crate's external dependencies and integration with the ArceOS ecosystem, see Dependencies and Integration. For details about the testing strategy and CI/CD pipeline, see Testing and Continuous Integration.

Build System Overview

The axvcpu crate uses Cargo as its build system with a standard Rust library configuration. The project targets multiple architectures and runtime environments, from hosted Linux environments to bare-metal embedded systems.

Package Configuration

The crate is configured as a standard Rust library with Rust Edition 2024 support. The package metadata is defined in Cargo.toml(L1 - L5)  with the package name axvcpu and version 0.1.0.

Build System Architecture

flowchart TD
subgraph subGraph2["Target Architectures"]
    X86_64_LINUX["x86_64-unknown-linux-gnu"]
    X86_64_NONE["x86_64-unknown-none"]
    RISCV64["riscv64gc-unknown-none-elf"]
    AARCH64["aarch64-unknown-none-softfloat"]
end
subgraph Dependencies["Dependencies"]
    AXERRNO["axerrno 0.1.0"]
    MEMADDR["memory_addr 0.3.1"]
    PERCPU["percpu 0.2.0"]
    AXADDRSPACE["axaddrspace (git)"]
end
subgraph subGraph0["Build System"]
    CARGO["cargo build"]
    TOML["Cargo.toml"]
    SRC["src/"]
end

CARGO --> AARCH64
CARGO --> RISCV64
CARGO --> TOML
CARGO --> X86_64_LINUX
CARGO --> X86_64_NONE
SRC --> CARGO
TOML --> AXADDRSPACE
TOML --> AXERRNO
TOML --> MEMADDR
TOML --> PERCPU

Sources: Cargo.toml(L1 - L12)  .github/workflows/ci.yml(L12) 

Dependency Management

The crate has minimal external dependencies, focusing on core virtualization functionality:

DependencyVersionPurpose
axerrno0.1.0Error code definitions and handling
memory_addr0.3.1Memory address abstractions
percpu0.2.0Per-CPU variable management
axaddrspacegitAddress space management (ArceOS ecosystem)

The axaddrspace dependency is pulled from the ArceOS hypervisor ecosystem via Git, indicating tight integration with the broader hypervisor framework Cargo.toml(L12) 

Sources: Cargo.toml(L7 - L12) 

Continuous Integration Pipeline

The CI system is implemented using GitHub Actions and supports multiple Rust toolchains and target architectures to ensure compatibility across different deployment scenarios.

CI/CD Pipeline Structure

flowchart TD
subgraph subGraph3["Documentation Job"]
    DOCBUILD["cargo doc --no-deps"]
    DEPLOY["JamesIves/github-pages-deploy-action@v4"]
end
subgraph subGraph2["CI Steps"]
    CHECKOUT["actions/checkout@v4"]
    RUSTUP["dtolnay/rust-toolchain@nightly"]
    FORMAT["cargo fmt --check"]
    CLIPPY["cargo clippy"]
    BUILD["cargo build"]
    TEST["cargo test"]
end
subgraph subGraph1["CI Job Matrix"]
    TOOLCHAIN1["nightly-2024-12-25"]
    TOOLCHAIN2["nightly"]
    TARGET1["x86_64-unknown-linux-gnu"]
    TARGET2["x86_64-unknown-none"]
    TARGET3["riscv64gc-unknown-none-elf"]
    TARGET4["aarch64-unknown-none-softfloat"]
end
subgraph subGraph0["Trigger Events"]
    PUSH["push"]
    PR["pull_request"]
end

BUILD --> TEST
CHECKOUT --> RUSTUP
CLIPPY --> BUILD
DOCBUILD --> DEPLOY
FORMAT --> CLIPPY
PR --> TOOLCHAIN1
PR --> TOOLCHAIN2
PUSH --> DOCBUILD
PUSH --> TOOLCHAIN1
PUSH --> TOOLCHAIN2
RUSTUP --> FORMAT
TARGET1 --> CHECKOUT
TOOLCHAIN1 --> TARGET1
TOOLCHAIN1 --> TARGET2
TOOLCHAIN1 --> TARGET3
TOOLCHAIN1 --> TARGET4

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

Multi-Architecture Testing

The CI pipeline tests across four target architectures:

  • x86_64-unknown-linux-gnu: Hosted Linux environment for development and unit testing
  • x86_64-unknown-none: Bare-metal x86_64 for hypervisor deployments
  • riscv64gc-unknown-none-elf: Bare-metal RISC-V with GC extensions
  • aarch64-unknown-none-softfloat: Bare-metal ARM64 with software floating point

Unit tests are only executed on the x86_64-unknown-linux-gnu target .github/workflows/ci.yml(L29 - L30)  since it's the only hosted environment that supports standard library features.

Code Quality Enforcement

The CI pipeline enforces code quality through multiple checks:

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

Documentation Generation

The project includes automated documentation generation and deployment:

Documentation Build Process

Documentation is built using cargo doc --no-deps --all-features .github/workflows/ci.yml(L49)  with strict link checking enabled through RUSTDOCFLAGS .github/workflows/ci.yml(L40)  The build process:

  1. Generates API documentation for all public interfaces
  2. Creates an index redirect page pointing to the main crate documentation
  3. Validates all intra-document links are functional
  4. Deploys to GitHub Pages on the default branch

GitHub Pages Deployment

Documentation is automatically deployed to GitHub Pages using the JamesIves/github-pages-deploy-action@v4 action .github/workflows/ci.yml(L53)  The deployment occurs only on pushes to the default branch, ensuring stable documentation reflects the latest released version.

Sources: .github/workflows/ci.yml(L32 - L57) 

Development Workflow

Local Development Setup

Developers should use Rust nightly toolchain nightly-2024-12-25 or later with the following components:

  • rust-src: For bare-metal target compilation
  • clippy: For linting
  • rustfmt: For code formatting

Build Commands

Standard development commands:

# Format code
cargo fmt --all

# Run linting
cargo clippy --all-features

# Build for specific target
cargo build --target x86_64-unknown-none --all-features

# Run tests (hosted target only)
cargo test --target x86_64-unknown-linux-gnu

Version Control

The project maintains a .gitignore configuration .gitignore(L1 - L18)  that excludes:

  • Build artifacts (/target, *.asm, *.img, *.bin, *.elf)
  • IDE settings (/.vscode)
  • Platform-specific files (.DS_Store)
  • Cargo.lock since axvcpu is a library crate

Sources: .github/workflows/ci.yml(L15 - L27)  .gitignore(L1 - L18)