Add full compiler toolchain, libc, examples and reference docs

First substantive commit: the entire Sprinter C compiler tree on top of
the bare README+gitignore initial commit.

What's in here:
  bin/sprinter-cc        — driver script invoking SDCC + linker + mkexe
  libc/                  — Sprinter-specific libc layer over ESTEX/BIOS
                           (conio, gfx, io, mem, stdio + headers)
  runtime/               — crt0 variants (default/small/banked/minimal)
                           + heap + bank trampolines
  toolchain/             — mkexe (SprintEXE packer, C + tests)
  examples/              — 30 demo programs (gfx, file I/O, env, time, …)
  lib/Makefile           — builds the libc archive (sprinter.lib)
  docs/                  — converted Sprinter manuals + asm reference samples
  third_party/           — solid-c reference compiler dump + sdcc setup script
  release_docs/          — packaging / release notes

gitignore overhaul:
  • Drop dangerous blanket patterns: *.asm (would hide docs/samples/*.asm)
    and *.exe (case-insensitive match was hiding third_party/solid-c/*.EXE
    on macOS APFS).  Replaced with examples/*/*.{asm,exe,…} and lib/*.lib.
  • Restore tracking of toolchain/mkexe/tests/{one,big}.bin — those are
    INPUT fixtures, not build outputs.
  • Collapse the duplicated SDCC/C/Sdcc sections into one section per
    concern (build outputs / vendored / OS-junk).
  • Add .sprinter-cc-*/, build/ (catches lib/build/ too), .claude/.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-06-03 16:13:21 +03:00
parent f542608b3f
commit c71e249a4e
404 changed files with 75155 additions and 58 deletions
+82
View File
@@ -0,0 +1,82 @@
# `sprinter-cc` — драйвер компилятора
Однострочный вход во всю цепочку инструментов. Принимает `.c` файлы и
опции, выдаёт SprintEXE.
## Синопсис
```
sprinter-cc -o OUT.exe SRC.c [more.c ...] [options]
```
## Опции
### Раскладка памяти
| Флаг | Описание |
|---|---|
| `--memory MODE` | `tiny` (по умолчанию), `small`, `big`, `huge`, `manual`. См. `memory_modes.md`. |
| `--memory-manual SPEC` | Для `--memory manual`: список `KEY=VAL` через запятую, например `CODE=W2,DATA=W2,BANKED=W3`. |
| `--stack-size N` | Сколько байт зарезервировать под стек. По умолчанию ≈1278. Большее значение уменьшает heap. |
### Организация кода
| Флаг | Описание |
|---|---|
| `--bank N=FILE.c` | Компилировать FILE.c в банк N (1..15). Повторяемый. Функции в banked-файлах нужны с квалификатором `__banked`. |
| `--crt0=TYPE` | Переопределение startup-файла: `default` / `minimal` / `banked` / `small`. Обычно выбирается автоматически по memory mode. |
### Диагностика
| Флаг | Описание |
|---|---|
| `--debug` | Подмешивает `DEBUG_RT = 1` в crt0 + передаёт `-DDEBUG_RT` в SDCC. Открывает runtime-symbols типа `_w2_self_allocated`. |
| `-v` | Verbose — печать каждой подкоманды. |
| `-h` / `--help` | Встроенная справка. |
### Pass-through
| Флаг | Описание |
|---|---|
| `-I PATH` | Дополнительный include-путь. |
| `-Wl FLAG` | Передать FLAG линкеру. |
| `--mkexe FLAG` | Передать FLAG в mkexe (например `--mkexe -p --mkexe 0` для zero-padded банков). |
| `-L 0xADDR` | Переопределить load-адрес. |
| `-E 0xADDR` | Переопределить entry-адрес. |
| `-S 0xADDR` | Переопределить стартовый стек. По умолчанию `0xBFFE`. |
## Примеры
Минимальная сборка:
```sh
sprinter-cc -o hello.exe hello.c
```
Программа побольше (не помещается в 14 КБ):
```sh
sprinter-cc --memory small -o big.exe big.c
```
Многобанковая игра:
```sh
sprinter-cc --memory huge -o game.exe \
main.c --bank 1=engine.c --bank 2=ai.c --bank 3=audio.c
```
Свой размер стека:
```sh
sprinter-cc --stack-size 4096 -o app.exe app.c
```
## Что происходит внутри
1. Выбирает crt0 на основе `--memory` (и наличия `--bank`).
2. Ассемблирует crt0 (с опциональным `DEBUG_RT` / `BANK_W1`).
3. Ассемблирует `heap_top.s` (custom значение если `--stack-size`).
4. Каждый `.c``.rel` через SDCC.
5. Bank-исходники компилируются с `--codeseg/--constseg/--dataseg BANK_n`.
6. Компилирует trampoline `runtime/bank.s` (если есть банки).
7. Линкует всё в `.ihx`, запускает `check_banks.py` для проверки 16 КБ лимита.
8. Вызывает `toolchain/mkexe/mkexe` для упаковки `.ihx` в SprintEXE.
Промежуточные файлы лежат в `.sprinter-cc-<basename>/` рядом с выходным.