# Makefile — описание команд В проекте используется `Makefile` как единая точка входа для сборки, тестирования, линтинга и управления релизами. Файл поддерживает **Windows (PowerShell)** и **Unix (sh)** — ветвление происходит автоматически через `ifeq ($(OS),Windows_NT)`. Команда по умолчанию (`make` без аргументов) показывает справку. --- ## Переменные конфигурации | Переменная | Значение по умолчанию | Назначение | |---------------|-----------------------------------|----------------------------------------------------| | `APP_NAME` | `genaudiobookinfo` | Имя исполняемого файла | | `VERSION` | `2.0.0` | Версия, встраивается в бинарник через `-ldflags` | | `BUILD_DIR` | `build` | Директория для артефактов сборки | | `CMD_PATH` | `./cmd/genaudiobookinfo` | Путь к `main.go` | | `GO` | `go` | Команда Go-компилятора | | `GOFLAGS` | `-trimpath` | Флаги компилятора (убирает пути хоста из бинарника)| | `LDFLAGS` | `-s -w -X main.version=$(VERSION)`| Линковщик: strip debug, strip DWARF, встроить версию | | `OUTPUT_DIR` | `./result` | Директория с результатами работы программы | | `GITEA_URL` | `https://github.dfv24.com` | Адрес Gitea-инстанции | | `GITEA_REPO` | `fofanov/genaudiobookinfo` | Владелец/репозиторий в Gitea | | `GITEA_TOKEN` | *(пусто)* | Токен API Gitea (нужен только для `ci-release`) | Переменные можно переопределять при вызове: ```bash make build VERSION=2.1.0 make ci-release VERSION=2.1.0 GITEA_TOKEN=abc123 ``` --- ## Основные команды ### `make` / `make help` Вывод справки со списком всех доступных команд. Цель по умолчанию — не требует аргументов. ```bash make ``` --- ### `make all` Последовательно выполняет `build` и `vet`. Удобен как первичная проверка после изменений. ```bash make all ``` --- ### `make build` Компилирует бинарник для **текущей платформы** и помещает его в `build/`. | ОС | Результирующий файл | |---------|----------------------------------| | Windows | `build/genaudiobookinfo.exe` | | Linux | `build/genaudiobookinfo` | | macOS | `build/genaudiobookinfo` | Флаги компилятора: `-trimpath -ldflags "-s -w -X main.version=2.0.0"`. ```bash make build make build VERSION=2.1.0 # встроить другую версию ``` --- ### `make build-windows-current` Компилирует `genaudiobookinfo.exe` (Windows/amd64) **в корневой директории проекта** (не в `build/`). Удобно для быстрой локальной проверки на Windows без отдельной папки. ```bash make build-windows-current ``` --- ### `make run` Запускает программу напрямую через `go run` без предварительной компиляции с параметрами по умолчанию: `-workers 8 -timeout 60m`. Директории `DIR_IN` и `DIR_OUT` берутся из `.env`. ```bash make run ``` --- ### `make run-custom ARGS="..."` Запускает программу с произвольными CLI-флагами через переменную `ARGS`. ```bash make run-custom ARGS="-workers 4 -timeout 30m" make run-custom ARGS="-workers 2" ``` > Полный список CLI-флагов: [[CLI-Usage|CLI-Usage]]. --- ## Тестирование ### `make test` Запускает все unit-тесты с флагами `-v -race -count=1`. - `-v` — podробный вывод - `-race` — детектор гонок (data race detector) - `-count=1` — отключает кэширование результатов тестов ```bash make test ``` --- ### `make test-cover` Запускает тесты с измерением покрытия кода и генерирует HTML-отчёт `coverage.html`. ```bash make test-cover # откройте coverage.html в браузере для просмотра отчёта ``` Файлы: - `coverage.out` — сырые данные покрытия - `coverage.html` — визуальный отчёт (удаляется через `make clean`) --- ## Качество кода ### `make fmt` Форматирует весь Go-код согласно стандарту `gofmt`. Эквивалент `go fmt ./...`. ```bash make fmt ``` --- ### `make vet` Запускает статический анализ `go vet ./...`. Выявляет потенциальные ошибки: неправильный printf-формат, достижимые nil-dereference и т.п. ```bash make vet ``` --- ### `make lint` Запускает `golangci-lint run ./...`. Если `golangci-lint` не установлен, выводит команду для установки. ```bash make lint # Установка линтера: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest ``` --- ### `make deps` Загружает все зависимости модуля (`go mod download`). Полезно для первоначальной настройки или подготовки к офлайн-сборке. ```bash make deps ``` --- ### `make tidy` Запускает `go mod tidy` — убирает неиспользуемые зависимости и обновляет `go.sum`. ```bash make tidy ``` --- ## Очистка ### `make clean` Удаляет артефакты сборки: - папку `build/` - файл `genaudiobookinfo.exe` в корне (от `build-windows-current`) - файлы `coverage.out` и `coverage.html` ```bash make clean ``` --- ### `make clean-results` Удаляет и пересоздаёт директорию результатов (`./result/`). Используйте с осторожностью — удаляет все обработанные аудиокниги из выходной папки. ```bash make clean-results ``` > Директория `OUTPUT_DIR` задаётся переменной Makefile (`./result` по умолчанию), но реальный путь при работе программы берётся из `DIR_OUT` в `.env`. --- ### `make clean-all` Выполняет `clean` + `clean-results` — полная очистка проекта. ```bash make clean-all ``` --- ## Кросс-компиляция ### `make build-all` Компилирует бинарники для **всех 16 поддерживаемых платформ**. Сначала выполняет `clean`, затем `ensure-build-dir`, затем собирает каждую платформу последовательно. Все результаты помещаются в `build/`. ```bash make build-all make build-all VERSION=2.1.0 ``` Время выполнения: 1–3 минуты в зависимости от машины. --- ### Платформы и выходные файлы | Команда make | GOOS | GOARCH | Доп. флаг | Файл | |-------------------------|---------|----------|---------------|---------------------------------------------| | `build-linux-amd64` | linux | amd64 | — | `genaudiobookinfo-linux-amd64` | | `build-linux-386` | linux | 386 | — | `genaudiobookinfo-linux-386` | | `build-linux-arm64` | linux | arm64 | — | `genaudiobookinfo-linux-arm64` | | `build-linux-arm7` | linux | arm | GOARM=7 | `genaudiobookinfo-linux-armv7` | | `build-darwin-amd64` | darwin | amd64 | — | `genaudiobookinfo-darwin-amd64` | | `build-darwin-arm64` | darwin | arm64 | — | `genaudiobookinfo-darwin-arm64` | | `build-windows-amd64` | windows | amd64 | — | `genaudiobookinfo-windows-amd64.exe` | | `build-windows-386` | windows | 386 | — | `genaudiobookinfo-windows-386.exe` | | `build-windows-arm64` | windows | arm64 | — | `genaudiobookinfo-windows-arm64.exe` | | `build-arm-mips` | linux | mips | GOMIPS=softfloat | `genaudiobookinfo-linux-mips` | | `build-arm-mipsle` | linux | mipsle | GOMIPS=softfloat | `genaudiobookinfo-linux-mipsle` | | `build-arm-riscv64` | linux | riscv64 | — | `genaudiobookinfo-linux-riscv64` | | `build-freebsd-amd64` | freebsd | amd64 | — | `genaudiobookinfo-freebsd-amd64` | | `build-freebsd-arm64` | freebsd | arm64 | — | `genaudiobookinfo-freebsd-arm64` | | `build-openbsd-amd64` | openbsd | amd64 | — | `genaudiobookinfo-openbsd-amd64` | | `build-netbsd-amd64` | netbsd | amd64 | — | `genaudiobookinfo-netbsd-amd64` | Каждую платформу можно собирать независимо: ```bash make build-linux # Linux: все 4 варианта make build-darwin # macOS: Intel + Apple Silicon make build-windows # Windows: amd64 + 386 + arm64 make build-arm # Embedded: MIPS + MIPSle + RISC-V make build-freebsd # FreeBSD: amd64 + arm64 make build-openbsd # OpenBSD: amd64 make build-netbsd # NetBSD: amd64 ``` --- ## Локальный релиз ### `make release` Выполняет `build-all`, затем копирует все скомпилированные бинарники из `build/` в `build/release/`. ```bash make release ``` --- ### `make checksum` Выполняет `release`, затем генерирует файл `build/release/checksums-sha256.txt` с SHA256-хешами всех бинарников. - **Windows**: использует `Get-FileHash` (PowerShell) - **Unix**: использует `sha256sum` ```bash make checksum ``` --- ### `make release-local` **Рекомендуемая команда для полного локального релиза.** Псевдоним для `checksum` — собирает все платформы, создаёт архивную папку и файл контрольных сумм. ```bash make release-local make release-local VERSION=2.1.0 ``` Результат: папка `build/release/` с 16 бинарниками и `checksums-sha256.txt`. --- ## CI/CD через Gitea Для автоматизации релизов используется пайплайн `.gitea/workflows/release.yml` (3 стадии: `quality → build → publish`). Подробнее: [[Architecture|Architecture]]. ### `make ci-check` Показывает текущее состояние рабочего дерева (`git status --short`) и последние 5 коммитов. Рекомендуется запускать **перед созданием тега релиза**, чтобы убедиться, что все изменения закоммичены. ```bash make ci-check ``` --- ### `make release-tag VERSION=X.Y.Z` Создаёт аннотированный git-тег `vX.Y.Z` и пушит его в `origin`. Это **автоматически запускает CI/CD pipeline** в Gitea (триггер `push tags v*.*.*`). ```bash make ci-check # 1. проверяем состояние make release-tag VERSION=2.1.0 # 2. создаём тег → CI запускается ``` > **Внимание**: если `VERSION` не изменён (остался `2.0.0`), команда выведет предупреждение, но тег всё равно будет создан. Обязательно указывайте нужную версию явно. После создания тега статус CI доступен по адресу: `https://github.dfv24.com/fofanov/genaudiobookinfo/actions` --- ### `make release-tag-delete VERSION=X.Y.Z` Удаляет тег `vX.Y.Z` локально и в `origin`. Используется для исправления ошибочно созданного тега. ```bash make release-tag-delete VERSION=2.1.0 ``` Затем можно выполнить коммит исправлений и повторно создать тег: ```bash git add . git commit -m "fix: исправление перед релизом" make release-tag VERSION=2.1.0 ``` --- ### `make ci-release VERSION=X.Y.Z GITEA_TOKEN=<токен>` Запускает CI/CD workflow **вручную через Gitea REST API** (endpoint `workflow_dispatch`) — без создания git-тега. Удобно для тестирования пайплайна или выпуска сборки на уже существующей ветке. ```bash make ci-release VERSION=2.1.0 GITEA_TOKEN=abc123def456 ``` - **`GITEA_TOKEN`** обязателен — команда завершится с ошибкой, если токен не задан. - Токен получается в настройках Gitea: *Settings → Applications → Generate Token* (scope: `write:repository`). - **Windows**: использует `Invoke-RestMethod` (PowerShell) - **Unix**: использует `curl` --- ## Типичные рабочие сценарии ### Разработка (ежедневно) ```bash make fmt # форматирование перед коммитом make vet # статический анализ make test # запуск тестов make build # локальная сборка ``` ### Выпуск новой версии через CI ```bash make ci-check # проверить состояние make release-tag VERSION=2.1.0 # создать тег → CI запустится автоматически ``` ### Локальный релиз (без CI) ```bash make release-local VERSION=2.1.0 # результат: build/release/ — 16 бинарников + checksums-sha256.txt ``` ### Отладка пайплайна CI ```bash make ci-release VERSION=2.1.0 GITEA_TOKEN=abc123 # ручной запуск без тега make release-tag-delete VERSION=2.1.0 # откат тега при ошибке ``` --- ## Совместимость с платформами | Функция | Windows (PowerShell) | Linux/macOS (sh) | |--------------------------|----------------------|------------------| | Установка `GOOS/GOARCH` | `$$env:GOOS='...'` | `GOOS=... $(GO)` | | Создание директорий | `New-Item -Force` | `mkdir -p` | | Удаление файлов | `Remove-Item -Force` | `rm -rf` | | SHA256 контрольные суммы | `Get-FileHash` | `sha256sum` | | Запрос к Gitea API | `Invoke-RestMethod` | `curl` | | Вывод сообщений | `$(info ...)` | `$(info ...)` | > `$(info ...)` используется вместо `@echo "..."` для корректной работы в PowerShell, где двойные кавычки обрабатываются иначе.