Development Environment

Relevant source files

• .github/workflows/ci.yml
• .gitignore

This document covers setting up and configuring a local development environment for contributing to the arm_gicv2 crate. It focuses on developer tooling, project organization, and recommended workflows for contributors.

For information about the build system configuration and dependency management, see Build System and Dependencies. For details about the automated CI/CD pipeline, see CI/CD Pipeline.

Local Development Setup

The arm_gicv2 crate requires specific toolchain configurations to support its target embedded systems. The development environment must accommodate multiple target architectures and maintain compatibility with no_std environments.

Required Toolchain Components

The project uses Rust nightly toolchain with specific components as defined in the CI configuration:

Development Workflow Diagram

flowchart TD
Dev["Developer"]
Setup["Local Setup"]
Toolchain["rustup toolchain install nightly"]
Components["rustup component add rust-src clippy rustfmt"]
Targets["rustup target add"]
Format["cargo fmt --check"]
Lint["cargo clippy"]
Build["cargo build --target"]
Test["cargo test (Linux only)"]
Commit["git commit"]
Push["git push"]
CI["GitHub Actions CI"]

Build --> Commit
Commit --> Push
Components --> Build
Components --> Format
Components --> Lint
Components --> Test
Dev --> Setup
Format --> Commit
Lint --> Commit
Push --> CI
Setup --> Components
Setup --> Targets
Setup --> Toolchain
Test --> Commit

Sources: .github/workflows/ci.yml(L15 - L19) 

Target Architecture Support

The development environment must support multiple target architectures for cross-compilation testing:

flowchart TD
subgraph subGraph1["Development Commands"]
    Check["cargo check --target"]
    Build["cargo build --target"]
    Clippy["cargo clippy --target"]
    Test["cargo test --target"]
end
subgraph subGraph0["Development Targets"]
    Linux["x86_64-unknown-linux-gnuTesting & Development"]
    Bare["x86_64-unknown-noneBare Metal x86"]
    RISC["riscv64gc-unknown-none-elfRISC-V Embedded"]
    ARM["aarch64-unknown-none-softfloatARM64 Embedded"]
end

ARM --> Build
ARM --> Check
ARM --> Clippy
Bare --> Build
Bare --> Check
Bare --> Clippy
Linux --> Build
Linux --> Check
Linux --> Clippy
Linux --> Test
RISC --> Build
RISC --> Check
RISC --> Clippy

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

Development Tools and Editor Configuration

Editor Support

The project includes VS Code in its gitignore patterns, indicating that some developers use VS Code but configuration is not standardized across the team.

File Organization and Ignored Paths

flowchart TD
subgraph subGraph2["Development Actions"]
    Src["src/Source code"]
    Cargo["Cargo.tomlProject manifest"]
    CI[".github/CI configuration"]
    Git[".gitignoreIgnore patterns"]
    Build["cargo build"]
    Editor["VS Code setup"]
    macOS["macOS development"]
    Install["cargo install"]
end
subgraph subGraph1["Ignored Files (.gitignore)"]
    Target["/targetBuild artifacts"]
    VSCode["/.vscodeEditor configuration"]
    DS[".DS_StoremacOS file metadata"]
    Lock["Cargo.lockDependency lockfile"]
end
subgraph subGraph0["Tracked Files"]
    Src["src/Source code"]
    Cargo["Cargo.tomlProject manifest"]
    CI[".github/CI configuration"]
    Git[".gitignoreIgnore patterns"]
    README["README.mdDocumentation"]
    Build["cargo build"]
    Editor["VS Code setup"]
    macOS["macOS development"]
    Install["cargo install"]
end

Build --> Target
Editor --> VSCode
Install --> Lock
macOS --> DS

Sources: .gitignore(L1 - L4) 

Ignored Development Artifacts

The .gitignore configuration reveals important aspects of the development environment:

The exclusion of Cargo.lock is particularly significant as it indicates this is a library crate where downstream consumers should control dependency versions rather than the library itself.

Sources: .gitignore(L1 - L4) 

Quality Assurance Integration

Local Development Commands

The development environment should replicate CI checks locally before committing:

# Format check (matches CI)
cargo fmt --all -- --check

# Linting (matches CI with specific allowances) 
cargo clippy --target <target> --all-features -- -A clippy::new_without_default

# Build verification
cargo build --target <target> --all-features

# Unit testing (Linux target only)
cargo test --target x86_64-unknown-linux-gnu -- --nocapture

Documentation Development

Local documentation building follows the same process as CI deployment:

# Build documentation with strict link checking
RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links -D missing-docs" cargo doc --no-deps --all-features

Sources: .github/workflows/ci.yml(L23 - L30)  .github/workflows/ci.yml(L40)  .github/workflows/ci.yml(L47) 

Contribution Workflow

Pre-commit Verification

Before submitting changes, developers should verify their code passes all CI checks locally:

Local Testing Workflow

flowchart TD
Change["Code Changes"]
Format["cargo fmt --all"]
FormatCheck["cargo fmt --all -- --check"]
Clippy["cargo clippy (all targets)"]
Build["cargo build (all targets)"]
Test["cargo test (Linux only)"]
Doc["cargo doc --no-deps"]
Commit["Ready for commit"]
Fix["Fix lint issues"]
Debug["Fix build errors"]
TestFix["Fix test failures"]
DocFix["Fix documentation"]

Build --> Debug
Build --> Test
Change --> Format
Clippy --> Build
Clippy --> Fix
Debug --> Build
Doc --> Commit
Doc --> DocFix
DocFix --> Doc
Fix --> Clippy
Format --> FormatCheck
FormatCheck --> Clippy
FormatCheck --> Format
Test --> Doc
Test --> TestFix
TestFix --> Test

Platform-Specific Considerations

Since unit tests only run on x86_64-unknown-linux-gnu, developers working on other platforms should ensure access to a Linux environment for complete testing.

The multi-target build verification ensures that changes maintain compatibility across all supported embedded platforms without requiring developers to have access to physical hardware.

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