portersky
54051d4068
Add a minimal no-core Rust executable built by invoking rustc directly from CMake. The project avoids Cargo and Rust core, alloc, and std, writes to stdout through platform APIs, and supports optimized Ninja release builds. Co-Authored-By: luna (openrouter/openai/gpt-5.6-luna): project setup and build
120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# 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.
|