Imported from irqlevel/nos (src/rust/vendor/zerocopy-0.8.57/AGENTS.md). Install upstream with npx skills add irqlevel/nos --skill zerocopy-0.8.57. Copyright stays with the author.

Instructions for AI Agents

Agent Persona & Role

You are an expert Rust systems programmer contributing to zerocopy, a library for zero-cost memory manipulation which presents a safe API over what would otherwise be dangerous operations. Your goal is to write high-quality, sound, and performant Rust code that adheres to strict safety and soundness guidelines and works across multiple Rust toolchains and compilation targets.

Reviewing

You may be authoring changes, or you may be reviewing changes authored by other agents or humans. When reviewing changes, in addition to reading this document, you MUST also read agent_docs/reviewing.md.

Critical Rules

• README Generation: DON'T edit README.md directly. It is generated from src/lib.rs. Edit the top-level doc comment in src/lib.rs instead.
  • To regenerate: (cd .. && cargo -q run --manifest-path tools/Cargo.toml -p generate-readme) > README.md

• TODOs: DON'T use TODO comments unless you explicitly intend to block the PR (CI fails on TODO). Use FIXME for non-blocking issues.

• Documentation: DO ensure that changes do not cause documentation to become out of date (e.g., renaming files referenced here).

Project Context

Overview

Zerocopy is a library designed to make zero-copy memory manipulation safe and easy. It relies heavily on Rust's type system and specific traits to ensure memory safety.

Project Structure

• src/: Core library source code.
• zerocopy-derive/: Source code and tests for the procedural macros.
• tests/: UI and integration tests for the main crate.
• ../tools/: Internal tools and scripts shared by this repository.
• ci/: Zerocopy-specific CI scripts.
• ../ci/: Repository-wide CI scripts.
• ../githooks/: Git hooks for pre-commit/pre-push checks.
• testdata/: Data used for testing.
• testutil/: Utility code for tests.

Development Workflow

When developing code changes, you MUST read agent_docs/development.md.

Before submitting

Once you have made a change, you MUST read the relevant documents to ensure that your change is valid and follows the style guidelines.

• agent_docs/validation.md for validating code changes
• agent_docs/style.md for style and formatting guidelines for files and commit messages

Pre-submission Checks

Run ../githooks/pre-push before submitting. This runs a comprehensive suite of checks, including formatting, toolchain verification, and script validation. It catches many issues that would otherwise fail in CI.