Руководство разработчика

Сборка, запуск без железа, тесты и соглашения проекта.

Аудитория: разработчики.

Содержание

Окружение
Порядок сборки
Цели Makefile
Сборка deb-пакета
Запуск без железа (эмуляция)
Тесты
Соглашения

Окружение

Go 1.21+ — модуль gpio-monitor, внешних Go-зависимостей нет (только стандартная библиотека, см. go.mod);
Node.js 20+ и npm — только для компиляции TypeScript (единственная dev-зависимость — typescript);
make, git; для deb-пакета — dpkg-deb; опционально golangci-lint для make lint.

Подготовка после клонирования:

make init    # проверит Node.js, скачает Go-модули и npm-пакеты

Порядок сборки

Критичный нюанс: сервер встраивает веб-файлы через go:embed web/dist ... (cmd/server/main.go:28). Каталог dist/ генерируется компилятором TypeScript и в git не хранится, поэтому на чистом checkout go build упадёт с ошибкой embed. Всегда собирайте фронтенд первым:

make build        # = build-frontend (tsc) + build-backend (go build)

По умолчанию бинарник собирается кросс-компиляцией под linux/arm64 (Raspberry Pi) в build/gpio-monitor-server. Для локальной платформы используйте make build-amd64 / build-mac / build-windows или make dev.

Есть также исторический скрипт build.sh — делает то же, что make build, но с захардкоженным путём проекта ~/temp/golang; предпочитайте Makefile.

Цели Makefile

Справка встроена: make help. Основные цели (Makefile):

Цель	Что делает
`init`	Проверка Node.js/npm + установка всех зависимостей
`build`	Полная сборка: фронтенд + бекенд (GOOS/GOARCH переопределяемы)
`build-frontend`	`npm install` (при отсутствии node_modules) + `npm run build` (tsc)
`build-backend`	`go build -ldflags="-s -w"` в `build/`
`run`	Сборка + запуск бинарника
`dev`	`go run ./cmd/server -port :8080` без оптимизаций (dist уже должен существовать)
`test`	`go test -v ./...`
`fmt`	`go fmt ./...`
`lint`	`golangci-lint run ./...` (если установлен)
`clean`	Удаляет `build/`, `web/dist`, `web/node_modules`, временные deb-файлы
`build-arm64` / `build-amd64` / `build-mac` / `build-windows` / `build-all`	Кросс-сборки
`install` / `uninstall`	Копирование бинарника в `/usr/local/bin`
`deb` / `deb-info` / `deb-contents` / `deb-clean` / `version`	Работа с deb-пакетом (ниже)

Цели docker-build/docker-run объявлены, но Dockerfile в репозитории отсутствует — они нерабочие (tech-debt.md).

Сборка deb-пакета

make deb          # от обычного пользователя, без sudo
make version      # показать вычисленную версию и имя файла
make deb-info     # информация о собранном пакете (dpkg-deb -I)
make deb-contents # список файлов пакета (dpkg-deb -c)
make deb-clean    # очистка временных файлов сборки пакета

Версионирование через git: версия пакета = <база>-build<N>, где база берётся из Version: в debian/control (сейчас 1.0.0), а N = git rev-list --count HEAD (число коммитов). Итоговый файл: build/gpio-monitor-server_1.0.0-build<N>_arm64.deb. Каждый коммит автоматически увеличивает номер сборки.

make deb выполняет clean → build-frontend → build-backend → prepare-debian → dpkg-deb --build. В пакет попадают: бинарник, веб-файлы (копия для справки — сервер использует встроенные), unit systemd, конфиг, утилита gpio-logs, maintainer-скрипты из debian/. Что происходит при установке — в operations.md.

Запуск без железа (эмуляция)

FIFO и поток данных можно смоделировать на любой Linux-машине:

mkfifo /tmp/gpio_pipe
python3 scripts/emulator.py scripts/array.txt /tmp/gpio_pipe   # генератор данных
make dev                                                        # сервер (в другом терминале)

Вспомогательные скрипты scripts/:

Скрипт	Назначение
`emulator.py`	Эмулятор капчера: читает массив байт из файла (формат `[0xE0, 0x01, ...]`) и пишет их в pipe/stdout с заданной задержкой, с переподключением и повтором
`array.txt`	Пример массива данных для эмулятора
`imi_wire.py`	Имитатор параллельной шины на реальных GPIO (gpiod, Raspberry Pi 4): выставляет байт на пины данных и дёргает строб WR — для теста настоящего `gpio-interrupt`
`emulatohackrf.sh`	Связка эмулятора с передатчиком HackRF (`hackrf-frame64-tx`): передача байтов GPIO по радиоканалу
`vu_meter.py`	Консольный VU-метр микрофона (sounddevice/numpy) — независимая проверка аудиотракта
`view_logs.sh`	Сводная статистика dev-логов (`~/.local/share/gpio-monitoring/logs`)

Пути внутри emulatohackrf.sh и systemd-юнитов захардкожены под конкретное устройство (/home/user/...) — правьте под своё окружение.

Тесты

make test        # go test -v ./...

Сейчас тестами покрыт только retention: internal/logger/retention_test.go (очистка по возрасту/размеру, minKeepFiles, устойчивость к скачку часов и битым именам). Остальные пакеты тестов не имеют — см. tech-debt.md. CI в репозитории нет — прогоняйте make test и go vet ./... перед коммитом вручную.

Соглашения

Язык — русский: комментарии, логи, сообщения об ошибках, документация.
Конфигурация — только CLI-флаги (без env-переменных и конфиг-файлов); новые параметры добавляются флагом в main() и полем в logger.Config.
Зависимости — Go-код держится на стандартной библиотеке; прежде чем добавить стороннюю зависимость, убедитесь, что она действительно необходима.
Структура: cmd/server — точка входа и HTTP-слой; internal/adapter — буфер; internal/pipe — приём данных; internal/logger — хранение/события; internal/audio — микрофон. Фронтенд — frontend.md.
Целевая платформа — linux/arm64; сборка и на других платформах должна оставаться рабочей (кросс-цели Makefile).
Форматы данных и API описаны в data-formats.md и api.md — при изменении кода обновляйте эти документы.

9.0 KiB Raw Permalink Blame History Unescape Escape