🏗️ Z80-PROJECTTEMPLATE: ВАШ ЛИЧНЫЙ ПРОРАБ НА СТРОЙКЕ Z80-ПРОЕКТА

ВСТУПЛЕНИЕ: ОТ ПУСТОГО ЛИСТА К ГОТОВОЙ СТРОЙКЕ​

ЧТО ТАКОЕ Z80-PROJECTTEMPLATE И ЗАЧЕМ ОН НУЖЕН?​

КЛЮЧЕВЫЕ ВОЗМОЖНОСТИ (ЧТО ОН ДАЁТ ПРОГРАММИСТУ)​

1. Готовая структура проекта — папки и файлы уже разложены по местам.
2. Преднастроенный tasks.json — задача сборки для Pasmo уже прописана. Нажал Ctrl+Shift+B — код компилируется .
3. Пример hello.z80 — можно сразу посмотреть, как писать код, и проверить, что сборка работает.
4. Интеграция с z80-macroasm — шаблон рассчитан на совместную работу с расширением Z80 Macro-Assembler от mborik (подсветка, автодополнение, навигация) .
5. Поддержка отладочной информации — Pasmo запускается с ключом -d, генерируя информацию для отладчиков .
6. Готовые .gitattributes и лицензия — для тех, кто использует Git.
7. MIT License — можно использовать в любых проектах, даже коммерческих .

ИСТОРИЧЕСКИЙ КОНТЕКСТ: ЭВОЛЮЦИЯ НАЧАЛА ПРОЕКТОВ​

УСТАНОВКА И НАСТРОЙКА: 5 ШАГОВ ЗА 5 МИНУТ​

Шаг 1: Установка необходимого ПО​

1. Visual Studio Code — скачайте с code.visualstudio.com.
2. Pasmo Assembler— кросс-ассемблер для Z80.
   • Windows: скачайте с pasmo.speccy.org (есть готовые бинарники).
   • Linux: sudo apt install pasmo (или через менеджер пакетов вашего дистрибутива).
   • macOS: brew install pasmo (если есть Homebrew).
3. Z80 Macro-Assembler extension — расширение для VS Code от mborik. Установите через маркет расширений (иконка с синей микросхемой) .

Шаг 2: Получение шаблона​

git clone https://github.com/Egbert-Azure/Z80-ProjectTemplate.git мой-новый-проект
cd мой-новый-проект
code .  # Открыть в VS Code

1. Перейдите на страницу репозитория.
2. Нажмите зелёную кнопку "Code" → "Download ZIP".
3. Распакуйте архив в папку нового проекта.
4. Откройте эту папку в VS Code.

Шаг 3: Настройка путей к Pasmo (важно!)​

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "assemble",
            "type": "shell",
            "command": "pasmo",  // ← ЗДЕСЬ МОЖЕТ БЫТЬ НУЖЕН ПОЛНЫЙ ПУТЬ
            "args": [
                "-d",           // Отладочная информация
                "${file}",
                "${fileDirname}/${fileBasenameNoExtension}.com"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": []
        }
    ]
}

• Windows: "C:\\pasmo\\pasmo.exe" (обратите внимание на двойные обратные слеши)
• macOS/Linux: "/usr/local/bin/pasmo" (или где он у вас установлен)

Шаг 4: Создание своего файла​

Шаг 5: Проверка сборки​

1. Откройте любой .z80 файл.
2. Нажмите Ctrl+Shift+B (или ⇧+⌘+B на macOS).
3. Посмотрите в терминал VS Code. Если всё хорошо, вы увидите что-то вроде:

> Executing task: pasmo -d hello.z80 hello.com <

Terminal will be reused by tasks, press any key to close it.

СТРУКТУРА ПРОЕКТА (ЧТО ВНУТРИ)​

Z80-ProjectTemplate/
├── .vscode/
│   └── tasks.json           # Задача сборки для Pasmo
├── .gitattributes           # Настройки Git (окончания строк и т.д.)
├── hello.z80                # Пример программы Hello World
├── LICENSE.md               # Лицензия MIT
└── README.md                # Документация (на английском)

Что внутри hello.z80?​

; Пример программы Hello World
; для ассемблера Pasmo

    org 0x8000        ; Начальный адрес (можно изменить под вашу платформу)

start:
    ld hl, message    ; HL = адрес строки
    call print_string ; Вызов процедуры вывода
    ret               ; Возврат (для CP/M или монитора)

print_string:
    ld a, (hl)        ; Загружаем символ
    or a              ; Проверка на 0 (конец строки)
    ret z             ; Если 0 — возврат
    rst 0x10          ; Вывод символа через системный вызов (для CP/M)
    inc hl            ; Следующий символ
    jr print_string   ; Повтор

message:
    db "Hello, Z80 World!", 0

    end start

• Директиву org для задания адреса.
• Метки (start, print_string, message).
• Команды Z80 (ld, call, ret, rst, inc, jr).
• Объявление строки через db с нулевым терминатором.

РАБОЧИЙ ПРОЦЕСС (ДЕНЬ ОПЛАТЫ)​

Шаг 1: Пишем код​

• Подсветка синтаксиса.
• Автодополнение команд.
• Переход к определению меток (F12).

Шаг 2: Собираем​

pasmo -d game.z80 game.com

Шаг 3: Отлаживаем​

• SIMH, MAME или QEMU — эмуляторы, поддерживающие Z80-системы (особенно с CP/M).
• GDB в связке с эмулятором для пошаговой отладки.

Шаг 4: Запускаем​

• Запустить в эмуляторе CP/M (например, в CP/M Box или MAME с CP/M).
• Использовать как чистый бинарник для ZX Spectrum, загрузив по нужному адресу (укажите правильный org).
• Конвертировать в другие форматы (TAP, SNA) с помощью дополнительных утилит.

ПЛЮСЫ И МИНУСЫ​

Плюсы (Почему это удобно)​

• Мгновенный старт: не нужно вспоминать синтаксис tasks.json или ключи Pasmo. Скачал — и работаешь .
• Минимализм: шаблон содержит ровно то, что нужно, и ничего лишнего.
• Интеграция с z80-macroasm: лучшая подсветка и навигация работают сразу .
• Открытая лицензия (MIT): можно форкать, модифицировать и использовать в коммерческих проектах без ограничений .
• Подходит для любой платформы Z80: меняете org в начале файла — и код работает под CP/M, Spectrum, MSX, SAM Coupé и т.д.
• Пример кода в комплекте: hello.z80 — готовый шаблон для изучения и теста .

Минусы (О чём нужно знать)​

• Только для Pasmo: если вы используете sjasmplus или z88dk, этот шаблон придётся переделывать (или искать другой).
• Нет автоматического запуска в эмуляторе: шаблон только компилирует. Запуск полученного бинарника — ваша забота .
• Нет встроенной отладки: автор честно пишет, что для отладки нужно использовать внешние инструменты .
• Требует ручной настройки путей: если Pasmo не в PATH, нужно прописать путь в tasks.json вручную.
• Звёзд на GitHub пока мало: всего 1 звезда на момент написания статьи, что говорит о небольшой популярности . Но для такой простой и полезной вещи это не показатель качества.

ДОПОЛНИТЕЛЬНЫЕ РЕСУРСЫ​

1. Pasmo Documentation — pasmo.speccy.org/pasmodoc.html. Полное описание всех директив и возможностей ассемблера.
2. Z80 Assembly Language Tutorial — tutorialspoint.com. Для начинающих — основы Z80.

ИНТЕГРАЦИЯ С ЭКОСИСТЕМОЙ​

ЗАКЛЮЧЕНИЕ: МАЛ, ДА УДАЛ​