💾 VSCODE-PYZ80: МОСТ ИЗ VS CODE В МИР САМОГО МОЩНОГО Z80-КОМПЬЮТЕРА

ВСТУПЛЕНИЕ: БРИТАНСКАЯ ЛЕГЕНДА ЗАСЛУЖИВАЕТ СОВРЕМЕННЫХ ИНСТРУМЕНТОВ​

ЧТО ТАКОЕ VSCode-PYZ80 И ЗАЧЕМ ОН НУЖЕН?​

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

1. Подсветка синтаксиса Z80 — все команды и директивы pyz80 разноцветные и наглядные .
2. Встроенный ассемблер pyz80 — расширение включает последнюю версию pyz80, так что ничего дополнительно скачивать не нужно .
3. Горячие клавиши для сборки и запуска:
   • F10 — собрать исходник в образ диска SAM (готовый .dsk или .mgt) .
   • Ctrl+F10 — собрать и сразу запустить в эмуляторе SimCoupe .
   • Ctrl+Shift+F10 — собрать и отправить на реальный SAM Coupé по сети (через TrinLoad) .
4. Автоматическое добавление SAMDOS v2 — чтобы образ диска был загрузочным, расширение первым файлом добавляет SAMDOS .
5. Генерация symbol map — создаёт файл символов, совместимый с отладчиком SimCoupe v1.1+ .
6. Поддержка workspace settings — можно настроить под каждый проект свои параметры (главный файл, пред- и пост-обработка) .
7. BASENAME-подстановка — удобная замена имени файла в настройках .

ИСТОРИЧЕСКИЙ КОНТЕКСТ: ПОЧЕМУ SAM COUPÉ И PYZ80?​

СТАНОВКА И НАСТРОЙКА: ШЕСТЬ ШАГОВ К САМОЙ МОЩНОЙ Z80-МАШИНЕ​

Шаг 1: Установка Visual Studio Code​

Шаг 2: Установка расширения vscode-pyz80​

1. Запустите Visual Studio Code.
2. Нажмите Ctrl+Shift+X (или иконку квадратиков слева), чтобы открыть вкладку Extensions.
3. В поиске введите "pyz80".
4. Найдите расширение от автора simonowen и нажмите Install .

Шаг 3: Установка Python (обязательно!)​

• Windows: скачайте с python.org и при установке обязательно отметьте "Add Python to PATH".
• macOS: brew install python3 (если есть Homebrew) или скачайте с официального сайта.
• Linux: sudo apt install python3 (или через менеджер пакетов вашего дистрибутива).

Шаг 4: Установка SimCoupe (для запуска в эмуляторе)​

• Официальный сайт: simcoupe.org
• Репозиторий на GitHub: github.com/simonowen/simcoupe

Шаг 5: Установка SAMdisk (для отправки на реальное железо)​

• Сайт: simonowen.com/samdisk/
• Эта утилита позволяет записывать образы дисков на реальные дискеты или отправлять их по сети.

Шаг 6: Настройка путей (если программы не в PATH)​

СТРУКТУРА ПРОЕКТА И НАСТРОЙКИ WORKSPACE​

MySamProject/
├── .vscode/
│   └── settings.json        # Настройки проекта (pyz80)
├── src/
│   ├── main.asm              # Главный исходник
│   ├── graphics.asm          # Графические процедуры
│   └── data.asm              # Данные
├── assets/
│   ├── sprites/              # Спрайты (исходники)
│   └── music/                 # Музыка (исходники)
├── build/                     # Сюда будут генерироваться .dsk/.mgt
└── README.md

Настройки .vscode/settings.json​

{
    "pyz80.mainsource": "src/main.asm",        // Главный файл (всегда собирать его)
    "pyz80.extraopts": "--syntax=f --lst",     // Доп. опции для pyz80
    "pyz80.prebuild": "python tools/convert_gfx.py", // Запустить перед сборкой
    "pyz80.postbuild": "python tools/make_pack.py",  // Запустить после сборки
    "pyz80.samdiskArgs": ["--boot=master"]      // Аргументы для samdisk
}

РАБОЧИЙ ПРОЦЕСС (ТРИ РЕЖИМА РАБОТЫ)​

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

Шаг 2: Собираем (три варианта)​

1. Запускает pyz80 с текущим (или указанным в mainsource) файлом.
2. Создаёт образ диска SAM (обычно .dsk или .mgt).
3. Автоматически добавляет в начало образа SAMDOS v2, чтобы диск был загрузочным .
4. Генерирует symbol map для отладчика SimCoupe .

1. Выполняет сборку (как в варианте А).
2. Запускает SimCoupe, автоматически загружая в него созданный образ диска .
3. Благодаря symbol map, в отладчике SimCoupe вы увидите не просто адреса, а имена ваших меток .

1. Выполняет сборку.
2. Использует SAMdisk для отправки образа на реальный SAM Coupé по сети (через TrinLoad) .
3. Ваша программа запускается на реальном железе!

ПРОДВИНУТЫЙ РЕЖИМ: КАСТОМНЫЕ TASKS ДЛЯ МАКСИМАЛЬНОЙ ГИБКОСТИ​

Пример .vscode/tasks.json​

{
    "version": "2.0.0",
    "options": {
        "env": {
            "PYZ80": "${config:pyz80.path}",
            "PYTHON": "${config:pyz80.python}",
            "SIMCOUPE": "${config:pyz80.simcoupe}",
            "SAMDISK": "${config:pyz80.samdisk}"
        }
    },
    "tasks": [
        {
            "label": "Build",
            "type": "shell",
            "command": "make",
            "windows": {
                "command": ".\\make.bat"
            },
            "args": [],
            "problemMatcher": ["$pyz80"],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Build and SimCoupe",
            "type": "shell",
            "command": "make",
            "windows": {
                "command": ".\\make.bat"
            },
            "args": ["run"],
            "problemMatcher": ["$pyz80"]
        },
        {
            "label": "Build and TrinLoad",
            "type": "shell",
            "command": "make",
            "windows": {
                "command": ".\\make.bat"
            },
            "args": ["net"],
            "problemMatcher": ["$pyz80"]
        }
    ]
}

Биндинг на клавиши (keybindings.json)​

[
    {
        "key": "f5",
        "command": "workbench.action.tasks.runTask",
        "args": "Build and SimCoupe",
        "when": "editorLangId == pyz80"
    },
    {
        "key": "ctrl+f5",
        "command": "workbench.action.tasks.runTask",
        "args": "Build and TrinLoad",
        "when": "editorLangId == pyz80"
    }
]

СРАВНЕНИЕ: vscode-pyz80 VS ОБЫЧНАЯ РАЗРАБОТКА ПОД SAM​

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

Плюсы (Почему это must-have для SAM-разработчика)​

• Полная интеграция: от кода до запуска на реальном железе — три клавиши .
• Всё включено: pyz80 уже внутри расширения, ничего не надо скачивать отдельно .
• Автоматический SAMDOS: образ диска получается сразу загрузочным .
• Поддержка отладки: symbol map для SimCoupe генерируется автоматически .
• Гибкость: можно использовать и встроенные хоткеи, и кастомные tasks для сложных проектов .
• Подстановка BASENAME: удобно для генерации имён файлов .
• Кроссплатформенность: работает на Windows, macOS, Linux .

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

• Узкая ниша: только для SAM Coupé. Если вы пишете под обычный Spectrum, это расширение не для вас.
• Требует Python: нужен интерпретатор Python 3.6+ .
• Настройка путей: если программы не в PATH, придётся прописывать пути вручную .
• Мало звёзд на GitHub: всего 2 звезды на момент написания . Но это не показатель качества, а следствие узости ниши.
• Документация только на английском: для русскоязычных пользователей может быть барьер.

СОВЕТЫ БЫВАЛОГО (ОПТИМИЗАЦИЯ РАБОТЫ)​

1. Используйте workspace settings. Не пишите пути к инструментам в глобальных настройках — кладите их в .vscode/settings.json проекта. Тогда при клонировании репозитория всё будет работать у всех .
2. Настройте mainsource. Если проект состоит из нескольких файлов, укажите главный файл в настройках. Тогда даже если вы редактируете include-файл, F10 будет собирать весь проект, а не только текущий файл .
3. Используйте prebuild для конвертации ресурсов. Графику и музыку удобно хранить в исходных форматах (например, картинки BMP), а перед сборкой автоматически конвертировать в данные для ассемблера через prebuild .
4. Подставка BASENAME — ваш друг. Если вы генерируете несколько файлов (например, main.bin, main.sym, main.dsk), используйте _BASENAME_ в настройках, чтобы не дублировать имена .
5. Для сложных проектов переходите на Makefile. Когда проект перерастает простую схему, используйте кастомные tasks и Makefile — это даст полный контроль над процессом сборки .

ЗАКЛЮЧЕНИЕ: SAM COUPÉ ЖИВЁТ В ЦИФРЕ​