Hermes Agent
d555071406
Unify beginner syntax while preserving compatibility, repair ownership and parser guards, add verified distribution tooling and VC6 Windows 98 build inputs, and clarify documentation and release status. Preserve DOS build-input line endings and exclude generated binaries/caches.
74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# Claro: single-file C89 runtime
|
|
|
|
The complete interpreter is `src/claro.c`. It needs no project-specific header,
|
|
generated source, or second C implementation file. Tests, lessons, documentation,
|
|
and optional scripts remain separate development resources, not build inputs.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
gcc -std=c89 -pedantic-errors -Werror=implicit-function-declaration src/claro.c -o claro -lm
|
|
```
|
|
|
|
`make -s all` uses the same strict C89 gate and builds `claro` and `claro.exe`.
|
|
The Windows build scripts select C89 too and reserve a 16 MiB stack.
|
|
A MinGW x64 executable has been compiled and exercised under Wine; native
|
|
Windows acceptance is still unverified. See [portability notes](PORTABILITY.md). The `.exe` name built by Linux make
|
|
still contains a Linux executable; it is not a Windows cross-build.
|
|
|
|
The source is formatted with four-space indentation and a 100-column limit.
|
|
C99-only declarations, loop declarations, compound literals, and `long long`
|
|
have been replaced without removing language features or compatibility syntax.
|
|
|
|
## Formatting and numbers
|
|
|
|
C89 does not define `snprintf` or `vsnprintf`. Claro uses a bounded internal
|
|
formatter in the same source file. It supports only the fixed conversions used
|
|
inside Claro, not arbitrary user-controlled printf formats. Strings are copied
|
|
with explicit bounds; fixed numeric formats use C89 `sprintf` into a buffer
|
|
sized for their maximum output. Unsupported internal formats fail explicitly.
|
|
|
|
Number display uses `modf` instead of casting to a non-C89 integer type.
|
|
`random.int` computes the inclusive integer range with floating-point arithmetic
|
|
and `fmod`, avoiding signed overflow across the tested 32-bit int range while
|
|
preserving the existing seeded random algorithm. This is not cryptographic
|
|
randomness and does not claim improved distribution.
|
|
|
|
## Platform requirements
|
|
|
|
C89 describes the C language and standard library, not an entire operating
|
|
system. Directory listing, subprocesses, filesystem checks, and HTTP execution
|
|
still use existing platform branches (POSIX or Windows); real HTTP needs curl.
|
|
The separate [MSVC6 / Windows 98 build](WINDOWS98.md) uses the actual legacy
|
|
compiler with a guarded CRT handle type and dedicated linker settings. Wine
|
|
execution does not establish native Windows 98, DOS, or freestanding support.
|
|
|
|
The C89 gate is tested with the host GCC and the host's integer/double model.
|
|
It does not establish compatibility with every minimum-capability C89 compiler
|
|
or an unusual integer/floating-point representation.
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
python3 tools/validate_c89.py
|
|
python3 tools/validate_first_hour.py
|
|
python3 tools/validate_v1_17.py
|
|
```
|
|
|
|
The C89 validator copies only `claro.c` to an isolated directory, compiles it
|
|
with strict flags, verifies that a deliberately C99-only source is rejected,
|
|
and exercises bounded formatting/truncation, large and negative numbers,
|
|
functions, and extreme random bounds. The full validation gate includes this
|
|
check and the nine executable First Hour examples.
|
|
|
|
Sanitizer command for these portability boundaries:
|
|
|
|
```bash
|
|
ASAN_OPTIONS=detect_leaks=0 UBSAN_OPTIONS=halt_on_error=1 CLARO_CC="gcc -fsanitize=address,undefined -g" python3 tools/validate_c89.py
|
|
```
|
|
|
|
Disabling leak detection here isolates invalid memory access and undefined
|
|
behavior checks; it is not a claim that every existing runtime path is leak-free.
|
|
Historical validation scripts may retain their original C99 commands; current
|
|
builds and current runtime/sanitizer validators use C89.
|