Команды go: go generate, генерация Go файлов посредством обработки источника

Использование:

go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]

generate запускает команды, описанные директивами в существующих файлах. Эти команды могут запускать любой процесс, но целью является создание или обновление исходных файлов Go.

go generate никогда не запускается автоматически при помощи go build, go get, go test и так далее. Он должен быть запущен явно.

go generate сканирует файлы на директивы, которые представляют собой строки вида,

//go:generate command argument...

(примечание: нет начальных пробелов и пробелов в "//go"), где command - это генератор, который должен быть запущен, соответствующий исполняемому файлу, который можно запустить локально. Это должен быть либо путь к оболочке (gofmt), либо полный путь (/usr/you/bin/mytool), либо псевдоним команды, описанный ниже.

Чтобы донести до людей и машинных инструментов, что код генерируется, сгенерированный источник должен иметь строку, которая соответствует следующему регулярному выражению (в синтаксисе Go):

^// Code generated .* DO NOT EDIT\.$

Строка может появиться в любом месте файла, но обычно располагается в начале, поэтому ее легко найти.

Обратите внимание, что go generate не анализирует файл, поэтому строки, похожие на директивы в комментариях или многострочные строки, будут обрабатываться как директивы.

Аргументами директивы являются разделенные пробелами токены или строки в двойных кавычках, которые передаются генератору как отдельные аргументы при его запуске.

Строки в кавычках используют синтаксис Go и оцениваются перед выполнением; строка в кавычках появляется как один аргумент генератора.

go generate устанавливает несколько переменных при запуске генератора:

$GOARCH
    Архитектура исполнения (arm, amd64 и т.д.)
$GOOS
    Операционная система исполнения (Linux, Windows и т.д.)
$GOFILE
    Базовое имя файла.
$GOLINE
    Номер строки директивы в исходном файле.
$GOPACKAGE
    Имя пакета файла, содержащего директиву.
$DOLLAR
    Знак доллара

Кроме подстановки переменных и вычисления строк в кавычках, никакая специальная обработка, такая как "globbing" (глобализация), не выполняется в командной строке.

В качестве последнего шага перед запуском команды любые вызовы любых переменных среды с буквенно-цифровыми именами, таких как $GOFILE или $HOME, расширяются по всей командной строке. Синтаксис для расширения переменной - $NAME во всех операционных системах. Из-за порядка вычисления переменные раскрываются даже внутри строк в кавычках. Если переменная NAME не установлена, $NAME раскрывается в пустую строку.

Директива формы,

//go:generate -command xxx args...

указывает, только для оставшейся части этого исходного файла, что строка xxx представляет команду, указанную в аргументах. Это может быть использовано для создания псевдонимов или для работы с генераторами нескольких слов. Например,

//go:generate -command foo go tool foo

указывает, что команда "foo" представляет генератор "go tool foo".

Генерируйте пакеты процессов в порядке, указанном в командной строке, по одному за раз. Если в командной строке перечислены файлы .go, они рассматриваются как один пакет. Внутри пакета generate обрабатывает исходные файлы в пакете в порядке имен файлов, по одному за раз. В исходном файле generate выполняет генераторы в порядке их появления в файле, по одному за раз.

Если какой-либо генератор возвращает состояние выхода с ошибкой, "go generate" пропускает всю дальнейшую обработку для этого пакета.

Генератор запускается в исходном каталоге пакета.

go generate принимает один конкретный флаг:

-run=""
    если не пустой, указывает регулярное выражение для выбора
    директивы, полный исходный текст которых (за исключением
    любых пробелов в конце и последний перевод строки)
    соответствует выражению.

Он также принимает стандартные флаги сборки, включая -v, -n и -x.
Флаг -v выводит имена пакетов и файлов по мере их обработки.
Флаг -n печатает команды, которые будут выполнены.
Флаг -x печатает команды по мере их выполнения.

Для получения дополнительной информации о флагах сборки см. "go help build".

Подробнее об указании пакетов см. 'go help packages'.

---

Читайте также:

• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей
• Команды go: go clean, удаление объектных файлов и кэшированных файлов