rslibc/AGENTS.md

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:

  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:

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

Run it on Unix:

./build/no_core_write

Run it on Windows:

.\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:

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:

  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.