# AGENTS.md

## Project Overview

This is a minimal Rust experiment that builds one executable without Cargo
and without linking Rust `core`, `alloc`, or `std`. CMake invokes `rustc`
directly. The executable writes `Hello` to stdout and exits.

The project currently contains:

- `main.rs`: the `#![no_core]` Rust program
- `CMakeLists.txt`: the direct `rustc` custom command
- `.gitignore`: ignores generated build output

## Non-Negotiable No-Core Design

- Keep `#![no_core]` in `main.rs`.
- Do not replace `#![no_core]` with `#![no_std]`; `no_std` still links
  Rust `core`.
- Do not add Cargo files or invoke Cargo.
- Do not import or link `core`, `alloc`, or `std`.
- Keep the required language-item and marker-trait definitions local to
  `main.rs` unless the user explicitly asks for a different design.
- Use primitive Rust types and explicit platform FFI instead of library
  helpers.
- Keep unsafe code inside small safe wrappers. The public call site for
  stdout should remain a normal string call such as:

  ```rust
  write_stdout("Hello\\n");
  ```

## Output Implementation

- Unix builds call the libc `write` function with file descriptor `1`.
- Windows builds call `GetStdHandle`, `WriteFile`, and `ExitProcess`
  directly through `kernel32`.
- The Windows build must not link the C runtime. This keeps the executable
  small and uses `/NODEFAULTLIB` with the `kernel32` import library.
- Preserve the safe `write_stdout(&str)` interface when changing output.

## Build System

CMake is configured with `LANGUAGES NONE` and calls `rustc` through an
`add_custom_command`. `find_program(RUSTC rustc REQUIRED)` locates the
compiler.

Configure and build a release executable with Ninja:

```sh
cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

Run it on Unix:

```sh
./build/no_core_write
```

Run it on Windows:

```powershell
.\build\no_core_write.exe
```

`CMAKE_BUILD_TYPE` is translated explicitly to rustc flags:

- `Release`: `-C opt-level=3 -C debuginfo=0`
- `RelWithDebInfo`: `-C opt-level=3 -C debuginfo=2`
- Other or unset configurations: `-C opt-level=0 -C debuginfo=2`

`no_core` is unstable, so CMake passes `RUSTC_BOOTSTRAP=1` to the direct
rustc invocation. A nightly compiler may be used instead, but Cargo is
still not permitted.

## Verification

After changing the source or build configuration, run a clean release build
and execute the program:

```sh
rm -rf build
cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/no_core_write
```

On Windows, use `Remove-Item -Recurse -Force build` and run
`build\\no_core_write.exe` instead. Confirm that stdout contains `Hello`.

When size matters, inspect the Windows executable size after a release
build. Avoid adding runtime libraries, formatting code, or Rust library
dependencies.

## Commit Messages

- Follow the 50/72 rule: subject lines are at most 50 characters and body
  lines are wrapped at 72 characters.
- Use conventional prefixes such as `feat:`, `fix:`, `docs:`, `chore:`,
  and `ci:`.
- Separate the subject from the body with a blank line.
- Keep commit messages concise.
- Include a `Co-Authored-By:` trailer for every agent or model that
  contributed to the commit, one trailer per co-author:

  ```text
  Co-Authored-By: qwen (lmstudio/qwen3.6-27b-mtp): wrote tests + build
  Co-Authored-By: luna (openai/gpt-5.6-luna): reviewed edge cases
  ```

## Editing Guidelines

- Keep changes minimal and directly related to the request.
- Use four-space indentation in Rust and CMake.
- Keep normal text in Markdown within 80 columns where practical.
- Do not add speculative abstractions or dependencies.
- Update this file when the build workflow, no-core constraints, supported
  platforms, or source layout changes.