# rslibc

A small `no_std` Rust common library and runtime built without Cargo.
CMake invokes `rustc` directly to compile a host-side proc macro, the
library rlib, and a minimal example executable.

## Features

- `Result` and formatting from `core`
- `Vec` and `vec![]` from `alloc`
- project-local `print!` / `println!` macros
- direct platform stdout with no C I/O layer
- OS heap allocator (`malloc`/`free`, `HeapAlloc`/`HeapFree`)
- `panic=abort` with a minimal panic handler
- Tokio-style `#[rslibc_macros::main]` for sync and async entry points

## Requirements

- Rust toolchain (`rustc`) on `PATH`
- CMake 3.20 or newer
- A CMake generator such as Ninja

No Cargo, no `std`, no external crates.

## Build

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

Run the example:

```sh
# Unix
./build/rslibc_example
```

```powershell
# Windows
.\build\rslibc_example.exe
```

The release example prints `Hello, World!`. The Windows executable is
about 4 KiB and depends only on `KERNEL32.dll` and `VCRUNTIME140.dll`.

Individual targets:

| Target           | Builds                          |
| ---------------- | ------------------------------- |
| `rslibc_macros`  | host-side proc macro DLL        |
| `rslibc_library` | `librslibc.rlib` common library |
| `rslibc_example` | example executable (default)    |

## Usage

```rust
#![no_std]
#![no_main]

#[rslibc_macros::main]
async fn main() {
    let values = rslibc::vec![1, 2, 3];
    let result: rslibc::Result<usize, &str> = Ok(values.len());
    rslibc::println!("values = {:?}, result = {:?}", values, result);
}
```

The macro renames the user function, then emits a synchronous platform
entry point, the global allocator, the panic handler, and — for async
functions — a call to `rslibc::runtime::block_on`. Plain (non-async)
`fn main()` works the same way.

## Layout

```text
macros/src/lib.rs  host-side #[rslibc_macros::main] proc macro
src/lib.rs         no_std common library API
src/io.rs          core::fmt stdout backend
src/runtime.rs     allocator, block_on executor, entry helpers
runtime/main.rs    minimal example entry point
CMakeLists.txt     direct rustc build commands
```

## Platform runtime

- Unix: stdout via libc `write(1, ...)`, allocation via `malloc`/`free`.
- Windows: stdout via `GetStdHandle` + `WriteFile` from `kernel32`,
  allocation via `HeapAlloc`/`HeapFree`. Only `kernel32` and
  `vcruntime` are linked; a local `strlen` shim keeps the UCRT out.

## Limitations

- The async entry point runs on a polling executor: a future that stays
  pending spins the CPU. There is no I/O reactor, timers, or task
  spawning yet.
- Formatting and allocation pull in parts of `core`/`alloc`; keep the
  library surface small when size matters.

## Documentation

See `AGENTS.md` for project conventions, build details, and commit
message rules.