41fb62f62e
Создана структура документации, описывающая функциональность, установку, использование CLI, архитектуру и интеграции с TorrAPI и OpenRouter. Добавлены примеры конфигурации и метаданных, а также описание структуры выходных данных.
399 lines
16 KiB
Markdown
399 lines
16 KiB
Markdown
# 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, где двойные кавычки обрабатываются иначе.
|