Development Environment Setup

Relevant source files

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

This document provides comprehensive instructions for setting up a local development environment for the riscv_goldfish RTC driver. It covers toolchain installation, environment configuration, and development workflow procedures necessary for contributing to the codebase.

For information about the CI/CD pipeline and automated testing, see CI/CD Pipeline. For details about target platform configuration and cross-compilation, see Target Platforms and Cross-Compilation.

Prerequisites and Toolchain Requirements

The riscv_goldfish driver requires a specific Rust toolchain configuration to support cross-compilation across multiple embedded targets. The development environment must be capable of building for bare-metal and no_std targets.

Rust Toolchain Setup

The project requires Rust nightly toolchain with specific components and target architectures. The CI pipeline defines the exact requirements that must be replicated locally.

flowchart TD
subgraph subGraph2["Build Targets"]
    X86_LINUX["x86_64-unknown-linux-gnu"]
    X86_NONE["x86_64-unknown-none"]
    RISCV["riscv64gc-unknown-none-elf"]
    ARM64["aarch64-unknown-none-softfloat"]
end
subgraph subGraph1["Essential Components"]
    RUST_SRC["rust-src"]
    CLIPPY["clippy"]
    RUSTFMT["rustfmt"]
end
subgraph subGraph0["Rust Toolchain Installation"]
    NIGHTLY["nightly toolchain"]
    COMPONENTS["Components Required"]
    TARGETS["Target Architectures"]
end

COMPONENTS --> CLIPPY
COMPONENTS --> RUSTFMT
COMPONENTS --> RUST_SRC
NIGHTLY --> COMPONENTS
NIGHTLY --> TARGETS
TARGETS --> ARM64
TARGETS --> RISCV
TARGETS --> X86_LINUX
TARGETS --> X86_NONE

Required Toolchain Installation Commands:

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

Local Development Workflow

The development workflow mirrors the CI pipeline to ensure consistency between local development and automated testing. Each step corresponds to a specific quality gate that must pass before code submission.

flowchart TD
subgraph subGraph2["Verification Commands"]
    VERSION_CHECK["rustc --version --verbose"]
    DOC_BUILD["cargo doc --no-deps --all-features"]
end
subgraph subGraph1["Quality Gates"]
    FMT_PASS["Format Check Pass"]
    LINT_PASS["Linting Pass"]
    BUILD_PASS["Build Success"]
    TEST_PASS["Tests Pass"]
end
subgraph subGraph0["Development Cycle"]
    EDIT["Code Editing"]
    FORMAT["cargo fmt --all --check"]
    CLIPPY["cargo clippy --target TARGET"]
    BUILD["cargo build --target TARGET"]
    TEST["cargo test --target x86_64-unknown-linux-gnu"]
end

BUILD --> BUILD_PASS
BUILD_PASS --> TEST
CLIPPY --> LINT_PASS
EDIT --> FORMAT
FMT_PASS --> CLIPPY
FORMAT --> FMT_PASS
LINT_PASS --> BUILD
TEST --> TEST_PASS
TEST_PASS --> DOC_BUILD
VERSION_CHECK --> FORMAT

Development Command Reference

Sources: .github/workflows/ci.yml(L20 - L30)  .github/workflows/ci.yml(L44 - L48) 

Build Artifacts and Ignored Files

The development environment generates various artifacts and temporary files that are excluded from version control through .gitignore configuration.

flowchart TD
subgraph subGraph2["Build Outputs"]
    DEBUG["target/debug/"]
    RELEASE["target/release/"]
    DOC["target/doc/"]
    DEPS["target/.rustc_info.json"]
end
subgraph subGraph1["Generated Artifacts (Ignored)"]
    TARGET["/target"]
    VSCODE["/.vscode"]
    DS_STORE[".DS_Store"]
    CARGO_LOCK["Cargo.lock"]
end
subgraph subGraph0["Workspace Structure"]
    ROOT["Project Root"]
    SRC["src/"]
    CARGO_TOML["Cargo.toml"]
    README["README.md"]
end

ROOT --> CARGO_LOCK
ROOT --> CARGO_TOML
ROOT --> DS_STORE
ROOT --> README
ROOT --> SRC
ROOT --> TARGET
ROOT --> VSCODE
TARGET --> DEBUG
TARGET --> DEPS
TARGET --> DOC
TARGET --> RELEASE

Ignored File Categories

Sources: .gitignore(L1 - L4) 

Documentation Generation and Verification

Local documentation generation follows the same process as the CI pipeline, ensuring documentation quality and link integrity.

flowchart TD
subgraph subGraph2["Output Structure"]
    CRATE_DOC["riscv_goldfish/index.html"]
    API_DOC["API Documentation"]
    REDIRECT["Root index.html redirect"]
end
subgraph subGraph0["Documentation Build Process"]
    SOURCE["src/lib.rs"]
    CARGO_DOC["cargo doc --no-deps --all-features"]
    TARGET_DOC["target/doc/"]
    INDEX_GEN["Auto-generated index.html"]
end
subgraph subGraph1["Documentation Flags"]
    RUSTDOCFLAGS["-D rustdoc::broken_intra_doc_links -D missing-docs"]
    BROKEN_LINKS["Broken Link Detection"]
    MISSING_DOCS["Missing Documentation Detection"]
end

CARGO_DOC --> TARGET_DOC
INDEX_GEN --> API_DOC
INDEX_GEN --> CRATE_DOC
INDEX_GEN --> REDIRECT
RUSTDOCFLAGS --> BROKEN_LINKS
RUSTDOCFLAGS --> MISSING_DOCS
SOURCE --> CARGO_DOC
TARGET_DOC --> INDEX_GEN

Local Documentation Commands

Sources: .github/workflows/ci.yml(L40)  .github/workflows/ci.yml(L44 - L48) 

Cross-Target Development Verification

Development workflow must verify functionality across all supported target architectures. This ensures the no_std compatibility and cross-platform portability requirements are maintained.

Target-Specific Build Matrix

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