📦 ZX-IDE: КОНТЕЙНЕРНАЯ РЕВОЛЮЦИЯ В МИРЕ РЕТРО-РАЗРАБОТКИ

​

ВСТУПЛЕНИЕ: ОТ РУЧНОЙ НАСТРОЙКИ К "ВСЁ ВКЛЮЧЕНО"​

ЧТО ТАКОЕ ZX-IDE И ЗАЧЕМ ОН НУЖЕН?​

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

1. Готовое окружение "из коробки" — в контейнере уже установлены: sjasmplus, pasmo, z88dk, утилиты для создания TAP/TZX, и всё необходимое.
2. Кроссплатформенность — проект будет собираться одинаково на Windows, macOS и Linux. Никаких "а у меня не компилируется".
3. Изоляция от системы — никакого мусора в реестре, PATH и папках программы. Всё живёт в контейнере.
4. Воспроизводимость сборок — можно зафиксировать версию контейнера, и даже через 10 лет проект соберётся один-в-один.
5. Автоматическое создание проекта — мастер проектов создаёт структуру папок и базовые файлы (main.asm, Makefile, .vscode/tasks.json, .vscode/launch.json).
6. Интеграция с DeZog — в новых версиях предустановлен отладчик, так что можно сразу отлаживать код.
7. Zero-install для коллег — скинул папку проекта другому человеку, он открыл её в VS Code, подтвердил "Reopen in Container" — и работает.

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

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

Предварительные требования​

1. Visual Studio Code — последняя версия.
2. Docker Desktop(или Docker Engine + Docker Compose).
   • Windows: Docker Desktop с поддержкой WSL2.
   • macOS: Docker Desktop.
   • Linux: Docker Engine + docker-compose (или Podman с поддержкой Docker API).

Установка расширения​

1. Запустите Visual Studio Code.
2. Нажмите Ctrl+Shift+X (или иконку квадратиков слева).
3. В поиске введите "Zx-Ide".
4. Найдите расширение от автора dgzornoza (иконка с красным логотипом Spectrum) и нажмите Install.

Создание нового проекта (мастер)​

1. Нажмите F1 (или Ctrl+Shift+P), чтобы открыть палитру команд.
2. Введите и выполните команду: ZxIde: Create new project.
3. Мастер задаст несколько вопросов:
   • Тип проекта: Zx Spectrum (или другие, если поддерживаются).
   • Язык/инструментарий: sjasmplus, pasmo или z88dk.
   • Имя проекта: например, MyFirstGame.
   • Папка для проекта: выберите, куда сохранить.
4. Мастер создаст структуру проекта и откроет её в новом окне.

Открытие проекта в контейнере​

1. В новом окне проекта снова откройте палитру команд (F1).
2. Выполните команду: Dev Containers: Reopen in Container.
3. VS Code начнёт сборку контейнера:
   • Скачивается базовый образ (обычно на основе Debian/Ubuntu).
   • Устанавливаются все необходимые инструменты (sjasmplus, z88dk, make, git и т.д.).
   • Это занимает 3-10 минут при первом запуске (зависит от скорости интернета).
4. После успешной сборки VS Code переподключится к проекту, работающему внутри контейнера.
   • В левом нижнем углу появится индикатор: "Dev Container: Zx-Ide".

СТРУКТУРА ПРОЕКТА (ЧТО МАСТЕР НАГЕНЕРИЛ)​

MyFirstGame/
├── .devcontainer/               # Конфигурация контейнера (сердце проекта)
│   ├── devcontainer.json        # Настройки для VS Code внутри контейнера
│   └── Dockerfile               # Инструкция по сборке образа
├── .vscode/                      # Конфигурация VS Code
│   ├── launch.json               # Настройки запуска отладки (DeZog)
│   └── tasks.json                 # Задачи сборки (Ctrl+Shift+B)
├── src/                          # Исходные коды
│   ├── main.asm                   # Пример программы на ассемблере
│   ├── main.bas                    # Если выбран Boriel Basic
│   └── main.c                      # Если выбран z88dk
├── Makefile                       # Автоматизация сборки
└── README.md                      # Описание проекта

Ключевые файлы: что внутри?​

FROM debian:bullseye-slim

# Устанавливаем зависимости
RUN apt-get update && apt-get install -y \
    make git curl wget \
    build-essential

# Устанавливаем sjasmplus
RUN wget https://github.com/z00m128/sjasmplus/releases/download/v1.20.3/sjasmplus-1.20.3-linux64.tar.gz \
    && tar -xzf sjasmplus-*.tar.gz \
    && cp sjasmplus /usr/local/bin/

# Устанавливаем z88dk
RUN wget https://github.com/z88dk/z88dk/releases/download/v2.3/z88dk-2.3-linux-x64.tgz \
    && tar -xzf z88dk-*.tgz \
    && cd z88dk \
    && make install

# Устанавливаем дополнительные утилиты (bin2tap, etc)
RUN git clone https://github.com/utility_library.git \
    && cd utility_library \
    && make install

{
    "name": "Zx-Ide Project",
    "build": {
        "dockerfile": "Dockerfile"
    },
    "settings": {
        "terminal.integrated.shell.linux": "/bin/bash"
    },
    "extensions": [
        "maziac.dezog",
        "maziac.z80-macroassembler",
        "maziac.hex-hover-converter",
        "rtorralba.boriel-basic"
    ],
    "remoteUser": "vscode",
    "postCreateCommand": "echo 'Контейнер готов к работе!'"
}

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

Пишем код​

    org 32768

Start:
    ; Чистим экран
    ld hl, 16384
    ld de, 16385
    ld bc, 6911
    ld (hl), 0
    ldir

    ; Выводим сообщение
    ld hl, HelloMsg
    call PrintString

    jr $

PrintString:
    ld a, (hl)
    or a
    ret z
    rst 16
    inc hl
    jr PrintString

HelloMsg:
    db "Hello from Zx-Ide!", 0

Сборка проекта​

1. Вызывается sjasmplus (или другой компилятор) с нужными флагами.
2. Генерируется .list файл (для отладки).
3. Создаётся .sna (снапшот) или .tap (лента).
4. В терминале VS Code видим вывод компилятора.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "shell",
            "command": "sjasmplus",
            "args": [
                "--lst=main.list",
                "--sna=main.sna",
                "src/main.asm"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": []
        }
    ]
}

Отладка​

• Программа загружается во встроенный симулятор zsim (или подключается к эмулятору).
• Выполнение останавливается на первой инструкции.
• Слева — регистры, справа — код, снизу — консоль.
• Ставим точки останова, нажимаем F10, F11 — идёт отладка.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "dezog",
            "request": "launch",
            "name": "Debug (zsim)",
            "remoteType": "zsim",
            "sjasmplus": [
                {
                    "path": "${workspaceFolder}/main.list"
                }
            ],
            "load": "${workspaceFolder}/main.sna",
            "topOfStack": "stack_top",
            "startAutomatically": false
        }
    ]
}

Тестирование в эмуляторе​

1. Добавить задачу в tasks.json для запуска Fuse, ZEsarUX или CSpect с загруженным файлом.
2. Или настроить вторую конфигурацию в launch.json для подключения к уже запущенному эмулятору (через ZRCP для ZEsarUX или порт для CSpect).

ВНУТРЕННЕЕ УСТРОЙСТВО: ЧТО ВНУТРИ КОНТЕЙНЕРА?​

Состав типового контейнера Zx-Ide​

Как это работает под капотом​

1. Dockerfile описывает, как собрать образ с нуля.
2. devcontainer.json говорит VS Code, как подключиться к этому контейнеру и какие расширения в нём установить.
3. При выполнении Reopen in Container:
   • VS Code запускает контейнер.
   • Монтирует папку проекта внутрь контейнера.
   • Устанавливает внутрь контейнера свой сервер (VS Code Server).
   • Подключается к нему через защищённый канал.
4. Всё, что вы видите в VS Code — редактор, терминал, отладчик — на самом деле работает внутри контейнера, но вы этого не замечаете.

СРАВНЕНИЕ: ZX-IDE VS КЛАССИЧЕСКАЯ НАСТРОЙКА​

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

Плюсы (Почему это гениально)​

• Чистота системы: Никаких танцев с PATH и зависимостями. Удалил папку проекта — удалил и контейнер (опционально). Система как новенькая.
• Воспроизводимость: Проект, созданный сегодня, будет собираться точно так же через 5 лет, если зафиксировать версию образа.
• Одинаковость для всей команды: Нет больше "у меня компилируется, а у тебя нет". У всех один образ.
• Быстрый старт для новичков: Не нужно знать, что такое sjasmplus и как его ставить. Установил Docker + VS Code + расширение — и вперёд.
• Интеграция с DeZog: Отладка настроена сразу.
• Поддержка трёх языков: sjasmplus, pasmo, z88dk — под любой вкус.
• Готовые конфиги: Мастер создаёт launch.json, tasks.json, Makefile — можно сразу работать.

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

• Требует Docker: На слабых машинах или в виртуальных окружениях Docker может тормозить. На современных ПК — незаметно.
• Первый запуск долгий: Скачивание образа и установка инструментов занимает время (3-10 минут). Но это один раз на проект.
• Размер образа: Образ может весить 500 МБ - 1 ГБ. Но это плата за изоляцию.
• Сложность кастомизации: Если вам нужно добавить в контейнер свою утилиту, придётся править Dockerfile. Но это не сложнее, чем ставить программу в Linux.
• Привязка к пути: Если переместить папку проекта, контейнер перестанет работать (нужно удалить старый и создать новый). Автор предупреждает об этом.
• Не для пуристов: Тем, кто любит "реальное железо" и ручную настройку каждого байта, контейнеры могут показаться избыточными.

СОВЕТЫ БЫВАЛОГО (КАК ВЫЖАТЬ МАКСИМУМ)​

1. Фиксируйте версии в Dockerfile. Если проект важный, не ставьте latest для инструментов. Пропишите конкретную версию sjasmplus и z88dk, чтобы через год ничего не отвалилось.
2. Используйте .dockerignore. Чтобы в образ не попадали временные файлы и бинарники, создайте .dockerignore и пропишите там build/, *.bin, *.sna.
3. Для больших проектов делайте многоэтапную сборку. Если ваш проект требует компиляции дополнительных утилит, используйте multi-stage builds в Dockerfile, чтобы итоговый образ был меньше.
4. Кешируйте образы. После первой сборки образ останется на диске. Следующие проекты будут открываться быстрее, так как Docker использует кеш.
5. Чистите неиспользуемые контейнеры. Команда docker container prune удалит остановленные контейнеры, которые больше не нужны.
6. Интегрируйте с GitHub Actions. Можно настроить автоматическую сборку проекта в контейнере на CI-сервере — тогда гарантия, что на вашем ПК и на сервере сборка будет идентичной.
7. Для z88dk используйте готовые библиотеки. В контейнере уже есть все стандартные библиотеки z88dk для Spectrum — не нужно их копировать в проект.

ЭКОСИСТЕМА: С ЧЕМ ДРУЖИТ ZX-IDE​

ЗАКЛЮЧЕНИЕ: НОВЫЙ СТАНДАРТ РЕТРО-РАЗРАБОТКИ​