Завершить разделение SDK и внешних проектов
This commit is contained in:
Александр Петров
+19
-65
@@ -1,76 +1,30 @@
|
||||
# Examples tour
|
||||
# Programs and examples
|
||||
|
||||
The release ships with 27 example programs in `examples/`. Every one of them
|
||||
is a self-contained demo with comments — they were used as regression tests
|
||||
during development.
|
||||
The SDK release includes its regression programs in `tests/`: `hello`,
|
||||
`cat`, `gfx_demo`, `bgitest` and others. They exercise compiler, libc,
|
||||
graphics and Sprinter runtime behavior. Build them with `make`; `make floppy`
|
||||
packs them into a local `build/media/toolkit-tests.img`.
|
||||
|
||||
## Build any example
|
||||
Larger demonstrations (`balls`, `mdview`, `mdview2`, `rpgwalk`, `scroll`,
|
||||
`space`) are published in the separate Examples project. Clone it separately
|
||||
and point it at this installed SDK:
|
||||
|
||||
```sh
|
||||
cd examples/hello
|
||||
export SPRINTER_ROOT=/path/to/sprinter-c
|
||||
cd /path/to/Examples
|
||||
pyenv exec python -m pip install -r requirements.txt
|
||||
make
|
||||
```
|
||||
|
||||
That produces `hello.exe` next to `hello.c` using `examples/example.mk`.
|
||||
|
||||
## Categories
|
||||
|
||||
### Hello world / basics
|
||||
* **`hello`** — stdio + conio Turbo-C-style colours
|
||||
* **`argv`** — argv parsing in crt0
|
||||
* **`conio`** — conio API smoke test
|
||||
* **`attrprob`** — probe Sprinter text-attribute byte layout
|
||||
|
||||
### File I/O
|
||||
* **`cat`** — read & print TEST.TXT
|
||||
* **`seek`** — 32-bit lseek over a 100 KB file
|
||||
* **`ls`** — directory listing via ffirst/fnext
|
||||
* **`filetest`** — FILE* streams (`fopen`/`fread`/`fwrite`/`fclose`)
|
||||
* **`stattest`** — `stat`/`fstat` on files and directories
|
||||
* **`openenv`** — open() flags + environment variables
|
||||
|
||||
### Memory & banking
|
||||
* **`malloc`** — heap stress test (200+ allocations)
|
||||
* **`mem_test`** — page allocator + `bank_read`/`bank_write`
|
||||
* **`banked`** — banked code in W3 (huge mode)
|
||||
* **`bankedbg`** — banked code in W1 (big mode)
|
||||
* **`banklocl`** — bank-local static data and BSS
|
||||
|
||||
### Mouse
|
||||
* **`mouse`** — driver in text mode
|
||||
* **`gfx_mous`** — mouse with custom bitmap cursor in graphics mode
|
||||
|
||||
### Graphics
|
||||
* **`gfx_demo`** — 320×256×256: lines, rectangles, fill via accelerator
|
||||
* **`gfx_d16`** — 640×256×16: same primitives in 16-color mode
|
||||
* **`gfx_text`** — bitmap-font text on graphics screen
|
||||
|
||||
### Misc
|
||||
* **`errno`** — errno / strerror / perror
|
||||
* **`timedir`** — date/time + directory listing
|
||||
* **`ptime`** — POSIX time API (time / localtime / mktime)
|
||||
* **`strtest`** — `<string.h>` test (from SDCC's z80.lib)
|
||||
* **`stdlib`** — `<stdlib.h>` test (qsort / rand / strtol / etc.)
|
||||
* **`assrtest`** — assert()
|
||||
* **`rt_test`** — runtime helpers (sleep, setjmp, atexit)
|
||||
|
||||
## Example.mk
|
||||
|
||||
Every example uses `examples/example.mk`. A minimal Makefile looks like:
|
||||
For your own program, use the SDK's `app.mk`:
|
||||
|
||||
```makefile
|
||||
PROJ_ROOT := $(abspath $(CURDIR)/../..)
|
||||
EXAMPLE := my_app
|
||||
include $(PROJ_ROOT)/examples/example.mk
|
||||
SPRINTER_ROOT ?= /path/to/sprinter-c
|
||||
EXAMPLE := my_app
|
||||
include $(SPRINTER_ROOT)/app.mk
|
||||
```
|
||||
|
||||
Optional knobs (set before `include`):
|
||||
|
||||
```makefile
|
||||
MEMORY := huge # default tiny
|
||||
STACK_SIZE := 4096 # default ~1278
|
||||
EXTRA_SRCS := helper.c util.c # extra .c files in same dir
|
||||
EXTRA_FLAGS := --bank 1=engine.c --debug # pass-through to sprinter-cc
|
||||
```
|
||||
|
||||
Use this template for your own programs.
|
||||
`make floppy` creates an image under the application's `build/media/`.
|
||||
For an emulator launch, set `MAME_HOME` to a prepared MAME runtime with
|
||||
`mame.arm`, `roms/` and `IMG/`; `MAME_BIN`, `MAME_ROMPATH`, `MAME_DSS_IMAGE`,
|
||||
`MAME_SYSTEM_HDD_IMAGE` and `MAME_BIOS` can override each part.
|
||||
|
||||
@@ -10,14 +10,15 @@ After extracting `sprinter-c-v1.0-<host>.tar.gz` you've got:
|
||||
* **`lib/sprinter.lib`** — the Sprinter target libc (prebuilt; rebuilt by `make` if you modify libc sources).
|
||||
* **`runtime/`** — crt0 variants and runtime helpers (assembled per-build).
|
||||
* **`toolchain/mkexe/`** — host utility that packs SDCC's `.ihx` into a SprintEXE.
|
||||
* **`examples/`** — 27 ready-to-build programs.
|
||||
* **`tests/` + `testkit/`** — SDK regression programs and host tests.
|
||||
* **`app.mk`** — standalone application build/run rules.
|
||||
* **`docs/{en,ru}/`** — this documentation.
|
||||
|
||||
## First build
|
||||
|
||||
```sh
|
||||
cd sprinter-c-v1.0-<host>
|
||||
make all # rebuild lib + every example (~30 s)
|
||||
make all # rebuild tools, libraries and SDK tests
|
||||
```
|
||||
|
||||
If `make` complains about a missing SDCC binary, fetch it once:
|
||||
@@ -48,8 +49,9 @@ ESTEX DSS shell.
|
||||
The release does **not** include the MAME emulator or the Sprinter ROM /
|
||||
DSS / HDD images — those are large and have their own licensing. To test:
|
||||
|
||||
* **MAME:** install MAME 0.283+ separately, obtain Sprinter Sp2000 images from
|
||||
Peters Plus, mount a FAT12 floppy with your `.exe` files as `-flop1`.
|
||||
* **MAME:** install a build with the Sprinter driver and prepare `MAME_HOME`
|
||||
containing `mame.arm`, `roms/`, DSS floppy and system CHD. `make floppy`
|
||||
creates a local SDK test disk; `make run MAME_HOME=/path/to/runtime` mounts it.
|
||||
* **Real Sprinter:** copy `.exe` to a floppy or HDD partition that DSS can
|
||||
see, then `RUN HELLO` from the shell.
|
||||
|
||||
@@ -57,5 +59,5 @@ DSS / HDD images — those are large and have their own licensing. To test:
|
||||
|
||||
* Read `sprinter_cc.md` for compiler flags.
|
||||
* Read `memory_modes.md` when you start needing more than 14 KB of code.
|
||||
* Browse `examples/` — every file is a working program with comments.
|
||||
* See `examples.md` for SDK tests and the separate Examples project.
|
||||
* See `headers.md` for the public API surface.
|
||||
|
||||
+19
-64
@@ -1,75 +1,30 @@
|
||||
# Обзор примеров
|
||||
# Программы и примеры
|
||||
|
||||
Релиз содержит 27 примеров в каталоге `examples/`. Каждый — самодостаточная
|
||||
демо-программа с комментариями (использовались как regression-тесты при разработке).
|
||||
Релиз SDK содержит регрессионные программы в `tests/`: `hello`, `cat`,
|
||||
`gfx_demo`, `bgitest` и другие. Они проверяют компилятор, libc, графику и
|
||||
runtime Sprinter. `make` собирает их, а `make floppy` упаковывает в локальный
|
||||
`build/media/toolkit-tests.img`.
|
||||
|
||||
## Сборка примера
|
||||
Большие демонстрации (`balls`, `mdview`, `mdview2`, `rpgwalk`, `scroll`,
|
||||
`space`) выпускаются отдельным проектом Examples. Для него задаётся только
|
||||
путь к установленному SDK:
|
||||
|
||||
```sh
|
||||
cd examples/hello
|
||||
export SPRINTER_ROOT=/путь/к/sprinter-c
|
||||
cd /путь/к/Examples
|
||||
pyenv exec python -m pip install -r requirements.txt
|
||||
make
|
||||
```
|
||||
|
||||
Результат — `hello.exe` рядом с `hello.c` через `examples/example.mk`.
|
||||
|
||||
## Категории
|
||||
|
||||
### Hello world / основы
|
||||
* **`hello`** — stdio + conio Turbo-C-стиль цвета
|
||||
* **`argv`** — парсинг argv в crt0
|
||||
* **`conio`** — smoke test conio API
|
||||
* **`attrprob`** — пробинг байта атрибутов Sprinter
|
||||
|
||||
### Файловый ввод-вывод
|
||||
* **`cat`** — читает и печатает TEST.TXT
|
||||
* **`seek`** — 32-битный lseek по файлу в 100 КБ
|
||||
* **`ls`** — листинг каталога через ffirst/fnext
|
||||
* **`filetest`** — FILE* стримы (`fopen`/`fread`/`fwrite`/`fclose`)
|
||||
* **`stattest`** — `stat`/`fstat` для файлов и каталогов
|
||||
* **`openenv`** — флаги open() + environment variables
|
||||
|
||||
### Память и банки
|
||||
* **`malloc`** — стресс-тест heap (200+ allocations)
|
||||
* **`mem_test`** — page allocator + `bank_read`/`bank_write`
|
||||
* **`banked`** — banked-код в W3 (huge mode)
|
||||
* **`bankedbg`** — banked-код в W1 (big mode)
|
||||
* **`banklocl`** — bank-local статические данные и BSS
|
||||
|
||||
### Мышь
|
||||
* **`mouse`** — драйвер в текстовом режиме
|
||||
* **`gfx_mous`** — мышь с пользовательским bitmap-курсором в графическом режиме
|
||||
|
||||
### Графика
|
||||
* **`gfx_demo`** — 320×256×256: линии, прямоугольники, fill через accelerator
|
||||
* **`gfx_d16`** — 640×256×16: те же примитивы в 16-цветном режиме
|
||||
* **`gfx_text`** — bitmap-текст на графическом экране
|
||||
|
||||
### Прочее
|
||||
* **`errno`** — errno / strerror / perror
|
||||
* **`timedir`** — дата/время + листинг каталога
|
||||
* **`ptime`** — POSIX time API (time / localtime / mktime)
|
||||
* **`strtest`** — `<string.h>` тест (из SDCC's z80.lib)
|
||||
* **`stdlib`** — `<stdlib.h>` тест (qsort / rand / strtol / etc.)
|
||||
* **`assrtest`** — assert()
|
||||
* **`rt_test`** — runtime helpers (sleep, setjmp, atexit)
|
||||
|
||||
## Example.mk
|
||||
|
||||
Каждый пример использует `examples/example.mk`. Минимальный Makefile:
|
||||
Для своей программы подключайте `app.mk` SDK:
|
||||
|
||||
```makefile
|
||||
PROJ_ROOT := $(abspath $(CURDIR)/../..)
|
||||
EXAMPLE := my_app
|
||||
include $(PROJ_ROOT)/examples/example.mk
|
||||
SPRINTER_ROOT ?= /путь/к/sprinter-c
|
||||
EXAMPLE := my_app
|
||||
include $(SPRINTER_ROOT)/app.mk
|
||||
```
|
||||
|
||||
Опциональные параметры (задаются до `include`):
|
||||
|
||||
```makefile
|
||||
MEMORY := huge # по умолчанию tiny
|
||||
STACK_SIZE := 4096 # по умолчанию ~1278
|
||||
EXTRA_SRCS := helper.c util.c # дополнительные .c в той же папке
|
||||
EXTRA_FLAGS := --bank 1=engine.c --debug # pass-through в sprinter-cc
|
||||
```
|
||||
|
||||
Используйте этот template для своих программ.
|
||||
`make floppy` создаёт образ в локальном `build/media/` приложения. Для
|
||||
запуска в эмуляторе задайте `MAME_HOME` с `mame.arm`, `roms/` и `IMG/`;
|
||||
`MAME_BIN`, `MAME_ROMPATH`, `MAME_DSS_IMAGE`, `MAME_SYSTEM_HDD_IMAGE` и
|
||||
`MAME_BIOS` позволяют переопределить отдельные пути.
|
||||
|
||||
@@ -10,14 +10,15 @@
|
||||
* **`lib/sprinter.lib`** — целевая libc для Sprinter (предсобрана; пересобирается через `make`, если изменили исходники libc).
|
||||
* **`runtime/`** — варианты crt0 и runtime-помощники (ассемблируются per-build).
|
||||
* **`toolchain/mkexe/`** — host-утилита, упаковывающая `.ihx` SDCC в SprintEXE.
|
||||
* **`examples/`** — 27 готовых программ.
|
||||
* **`tests/` + `testkit/`** — регрессионные программы и host-тесты SDK.
|
||||
* **`app.mk`** — правила сборки и запуска автономных приложений.
|
||||
* **`docs/{en,ru}/`** — эта документация.
|
||||
|
||||
## Первая сборка
|
||||
|
||||
```sh
|
||||
cd sprinter-c-v1.0-<host>
|
||||
make all # пересобрать lib + все примеры (~30 с)
|
||||
make all # пересобрать инструменты, библиотеки и SDK-тесты
|
||||
```
|
||||
|
||||
Если `make` жалуется на отсутствующий бинарник SDCC — загрузите его один раз:
|
||||
@@ -48,8 +49,9 @@ Sprinter / MAME / в любом ESTEX DSS шелле.
|
||||
Релиз **не содержит** эмулятор MAME или образы ROM / DSS / HDD Sprinter —
|
||||
они большие и имеют свои лицензии. Для тестирования:
|
||||
|
||||
* **MAME:** установите MAME 0.283+ отдельно, получите образы Sprinter Sp2000
|
||||
у Peters Plus, смонтируйте FAT12-флоп с вашими `.exe` файлами как `-flop1`.
|
||||
* **MAME:** установите сборку с драйвером Sprinter и подготовьте `MAME_HOME`
|
||||
с `mame.arm`, `roms/`, дискетой DSS и системным CHD. `make floppy` создаёт
|
||||
локальный диск SDK-тестов; `make run MAME_HOME=/путь/к/runtime` монтирует его.
|
||||
* **Реальный Sprinter:** скопируйте `.exe` на флоп или раздел HDD, видимый
|
||||
для DSS, затем `RUN HELLO` в шелле.
|
||||
|
||||
@@ -57,6 +59,6 @@ Sprinter / MAME / в любом ESTEX DSS шелле.
|
||||
|
||||
* Прочитайте `sprinter_cc.md` про флаги компилятора.
|
||||
* Прочитайте `memory_modes.md` когда не хватит 14 КБ кода.
|
||||
* Просмотрите `examples/` — каждый файл это рабочая программа с комментариями.
|
||||
* `examples.md` описывает SDK-тесты и отдельный проект Examples.
|
||||
* `headers.md` — список публичных API.
|
||||
* `platform_reference.md` — глубокие нюансы платформы и компилятора (от граблей до подводных камней).
|
||||
|
||||
@@ -366,8 +366,8 @@ Prepend'ит `DEBUG_RT = 1` в crt0 + передаёт `-DDEBUG_RT` в SDCC. О
|
||||
### MAME testing workflow
|
||||
|
||||
```sh
|
||||
make floppy # пакует все .exe + data в mame/v306/IMG/mc.img
|
||||
cd mame/v306 && ./run_mame.sh
|
||||
make floppy # пакует SDK-тесты в build/media/toolkit-tests.img
|
||||
make run MAME_HOME=/путь/к/MAME/runtime
|
||||
```
|
||||
Имена файлов на флопе должны быть 8.3 (FAT12). Все примеры названы соответственно — `banked_big → bankedbg`, `seek_demo → seek`, `time_dir_test → timedir`, etc.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user