Команды go: go test, тестировать пакеты

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

go test [build/test flags] [packages] [build/test flags & test binary flags]

go test автоматизирует тестирование пакетов, названных путями импорта. Он печатает резюме результатов теста в формате:

ok   archive/tar   0.011s
FAIL archive/zip   0.022s
ok   compress/gzip 0.033s
...

с последующим подробным выводом для каждого неудачного пакета.

go test перекомпилирует каждый пакет вместе с любыми файлами с именами, соответствующими шаблону файла *_test.go. Эти дополнительные файлы могут содержать функции тестирования, эталонные (benchmark) функции и примеры функций. Смотрите 'go help testfunc' для более подробной информации. Каждый перечисленный пакет вызывает выполнение отдельного тестового бинарного файла. Файлы, имена которых начинаются с "_" (включая "_test.go") или "." игнорируются

Тестовые файлы, которые объявляют пакет с суффиксом "_test", будут скомпилированы как отдельный пакет, а затем связаны и запущены с основным тестовым бинарным файлом.

Инструмент go игнорирует каталог с именем "testdata", делая его доступным для хранения вспомогательных данных, необходимых для тестов.

В рамках создания бинарного теста go test выполняет go vet для пакета и его исходных файлов для выявления значительных проблем. Если go vet обнаружит какие-либо проблемы, go test сообщит их и не запустит бинарный файл теста. Используется только подмножество с высокой достоверностью проверок по умолчанию. Это подмножество: 'atomic', 'bool', 'buildtags', 'nilfunc' и 'printf'. Вы можете просмотреть документацию для этих и других vet тестов через "go doc cmd/vet". Чтобы отключить запуск go vet, используйте флаг -vet=off.

Все выходные данные теста и итоговые строки выводятся на стандартный вывод команды go, даже если тест выводит их со своей собственной стандартной ошибкой. (Стандартная ошибка команды go зарезервирована для ошибок печати при построении тестов.)

Go test выполняется в двух разных режимах:

Первый, называемый режимом локального каталога, возникает, когда go test вызывается без аргументов пакета (например, 'go test' или 'go test -v'). В этом режиме go test компилирует исходные коды пакетов и тесты, найденные в текущем каталоге, а затем запускает полученный тестовый бинарный файл. В этом режиме кэширование (обсуждается ниже) отключено. После того, как пакетный тест завершится, go test напечатает итоговую строку, показывающую статус теста ('ok' или 'FAIL'), имя пакета и истекшее время.

Второй, называемый режимом списка пакетов, возникает, когда go test вызывается с явными аргументами пакета (например, 'go test math', 'go test ./...' и даже 'go test .'). В этом режиме go test скомпилирует и протестирует каждый из пакетов, перечисленных в командной строке. Если пакетный тест пройден, go test печатает только последнюю итоговую строку 'ok'. Если пакетный тест не пройден, go test распечатывает полный тестовый вывод. Если вызывается с флагом -bench или -v, go test печатает полный вывод даже для прохождения пакетных тестов, чтобы отобразить запрошенные результаты тестов или подробное ведение журнала.

Только в режиме списка пакетов, go test кэширует успешные результаты тестирования пакета, чтобы избежать ненужного повторного запуска тестов. Когда результаты теста могут быть восстановлены из кэша, go test перезапустит предыдущий вывод вместо повторного запуска тестового бинарного файла. Когда это происходит, go test печатает '(cached)' вместо истекшего времени в итоговой строке.

Правило совпадения в кеше заключается в том, что в прогоне используется один и тот же тестовый бинарный файл, а флаги в командной строке целиком исходят из ограниченного набора "кэшируемых" ('cacheable') тестовых флагов, определенных как -cpu, -list, -parallel, -run, -short, и -v. Если запуск go test имеет какие-либо тестовые или не тестовые флаги вне этого набора, результат не кэшируется. Чтобы отключить кэширование тестов, используйте любой тестовый флаг или аргумент, кроме кешируемых флагов. Идиоматический способ явного отключения кэширования тестов - использовать -count=1. Тесты, которые открывают файлы внутри корня исходного кода пакета (обычно $GOPATH) или которые обращаются к переменным среды, соответствуют только будущим прогонам, в которых файлы и переменные среды не изменяются. Кэшированный результат теста обрабатывается как выполняющийся в кратчайшие сроки, поэтому успешный результат теста пакета будет кэшироваться и использоваться повторно независимо от значения параметра -timeout.

В дополнение к флагам сборки, флаги, обрабатываемые самим 'go test':

-args
    Передать остаток от командной строки (все после -args)
    бинарному тесту, без интерпретации и без изменений.
    Поскольку этот флаг потребляет оставшуюся часть командной строки,
    список пакетов (если имеется) должен появляться перед этим флагом.

-с
    Скомпилировать тестовый бинарный файл в pkg.test, но не запускать его
    (где pkg - последний элемент пути импорта пакета).
    Имя файла можно изменить с помощью флага -o.

-exec xprog
    Запустить тестовый бинарный файл с помощью xprog. Поведение такое же, как
    в 'go run'. Смотрите подробности в 'go help run'.

-i
    Установить пакеты, которые являются зависимостями теста.
    Не запускать тест.

-json
    Преобразовать выходные данные теста в формат JSON, подходящий для автоматической обработки.
    Смотрите 'go doc test2json' для деталей кодирования.

-o file
    Скомпилировать бинарный файл теста в указанный файл.
    Тест все еще выполняется (если не указано -c или -i).

Бинарный файл теста также принимает флаги, которые управляют выполнением теста; эти флаги также доступны в 'go test'. Смотрите 'go help testflag' для подробностей.

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

Смотрите также: go build, go vet.

---

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

• Go FAQ: Как написать юнит-тест в Go?
• Команды go: go install, компиляция и установка пакетов и зависимостей
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go run, скомпилировать и запустить Go программу

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

go run [build flags] [-exec xprog] package [arguments...]

run компилирует и запускает указанный основной Go пакет. Обычно пакет указывается в виде списка исходных файлов .go, но это также может быть путь импорта, путь файловой системы или шаблон, соответствующий одному известному пакету, как в 'go run .' или 'go run my/cmd'.

По умолчанию 'go run' запускает скомпилированный бинарный файл напрямую: 'a.out arguments...'. Если указан флаг -exec, 'go run' вызывает бинарный файл, используя xprog:

'xprog a.out arguments...'.

Если флаг -exec не задан, GOOS или GOARCH отличается от системного значения по умолчанию, и программа с именем go_$GOOS_$GOARCH_exec может быть найдена в текущем пути поиска, 'go run' вызывает бинарный файл с использованием этой программы, например 'go_nacl_386_exec a.out arguments ...'. Это позволяет выполнять кросс-компилированные программы, когда доступен симулятор или другой метод выполнения.

Состояние выхода run не является состоянием выхода скомпилированного бинарного файла.

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

Смотрите также: go build.

---

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

• Как запускать Go программы
• Команды go: go install, компиляция и установка пакетов и зависимостей
• Команды go: go build, компиляция пакетов и зависимостей
• Запуск скриптов с помощью Go

Команды go: go mod why, объяснение необходимости пакета или модуля

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

go mod why [-m] [-vendor] packages...

why показывает кратчайший путь на графе импорта из основного модуля к каждому из перечисленных пакетов. Если указан флаг -m, why обрабатывает аргументы как список модулей и находит путь к любому пакету в каждом из модулей.

По умолчанию, why запрашивает граф пакетов, сопоставленных с "go list all", который включает в себя тесты для достижимых пакетов. Флаг -vendor вызывает необходимость исключать проверки зависимостей.

Выходные данные представляют собой последовательность разделов, по одному для каждого имени пакета или модуля в командной строке, разделенных пустыми строками. Каждый раздел начинается со строки комментария "# package" или "# module", в которой указан целевой пакет или модуль. Последующие строки дают путь через граф импорта, один пакет на строку. Если на пакет или модуль не ссылаются из основного модуля, раздел отображает одну заключенную в скобки заметку с указанием этого факта.

Например:

$ go mod why golang.org/x/text/language golang.org/x/text/encoding
# golang.org/x/text/language
rsc.io/quote
rsc.io/sampler
golang.org/x/text/language

# golang.org/x/text/encoding
(main module does not need package golang.org/x/text/encoding)
$

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod verify, проверка достоверности зависимостей

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

go mod verify

verify проверяет, что зависимости текущего модуля, которые хранятся в локальном загруженном исходном кеше, не были изменены с момента загрузки. Если все модули не изменены, verify печает "all modules verified". В противном случае он сообщает, какие модули были изменены, и вызывает 'go mod' для выхода с ненулевым статусом.

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod vendor, сделать вендорную копию зависимостей

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

go mod vendor [-v]

vendor сбрасывает каталог поставщика (vendor directory) основного модуля, чтобы включить все пакеты, необходимые для сборки и тестирования всех пакетов основного модуля. Он не включает тестовый код для вендорных пакетов.

Флаг -v заставляет vendor печатать имена вендорных модулей и пакетов в вывод стандартной ошибки.

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod tidy, добавить отсутствующие и удалить неиспользуемые модули

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

go mod tidy [-v]

tidy удостоверяется, что go.mod соответствует исходному коду в модуле. Он добавляет все недостающие модули, необходимые для построения пакетов и зависимостей текущего модуля, и удаляет неиспользуемые модули, которые не предоставляют никаких соответствующих пакетов. Он также добавляет все недостающие записи в go.sum и удаляет ненужные.

Флаг -v заставляет tidy печатать информацию об удаленных модулях в стандартный вывод ошибки (std err).

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod init, инициализировать новый модуль в текущем каталоге

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

go mod init [module]

init инициализирует и записывает новый go.mod в текущий каталог, фактически создавая новый модуль с корнем в текущем каталоге. Файл go.mod не должен уже существовать. Если возможно, init будет угадывать путь к модулю из комментариев к импорту (см. go help importpath) или из конфигурации управления версиями. Чтобы переопределить это предположение, укажите путь к модулю в качестве аргумента.

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod graph, распечатать граф требований модуля

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

go mod graph

graph печатает граф требований модуля (с примененными заменами) в текстовом виде. Каждая строка в выходных данных имеет два поля, разделенных пробелами: модуль и одно из его требований. Каждый модуль идентифицируется как строка в форме path@version, за исключением основного модуля, у которого нет суффикса @version.

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod edit, редактирование go.mod из инструментов или скриптов

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

go mod edit [editing flags] [go.mod]

Edit предоставляет интерфейс командной строки для редактирования go.mod, для использования в основном инструментами или скриптами. Он читает только go.mod; он не ищет информацию о задействованных модулях. По умолчанию edit читает и записывает файл go.mod основного модуля, но после флагов редактирования можно указать другой целевой файл.

Флаги редактирования определяют последовательность операций редактирования.

Флаг -fmt переформатирует файл go.mod без внесения других изменений. Это переформатирование также подразумевается любыми другими модификациями, которые используют или переписывают файл go.mod. Единственный раз, когда нужен этот флаг, это если другие флаги не указаны, как в 'go mod edit -fmt'.

Флаг -module изменяет путь к модулю (строка модуля файла go.mod).

Флаги -require=path@version и -droprequire=path добавляют и отбрасывают требование к указанному пути и версии модуля. Обратите внимание, что -require отменяет любые существующие требования к пути. Эти флаги в основном предназначены для инструментов, которые понимают граф модуля. Пользователи должны предпочесть 'go get path@version' или 'go get path@none', которые при необходимости выполняют другие корректировки go.mod для удовлетворения ограничений, накладываемых другими модулями.

Флаги -exclude=path@version и -dropexclude=path@version добавляют и удаляют исключение для заданного пути и версии модуля. Обратите внимание, что -exclude=path@version не допускается, если это исключение уже существует.

Флаги -replace=old[@v]=new[@v] и -dropreplace=old[@v] добавляют и удаляют замену указанного пути к модулю и пары версий. Если @v в old@v опущено, замена применяется ко всем версиям со старым путем к модулю. Если @v в new@v опущен, новый путь должен быть корневым каталогом локального модуля, а не путем к модулю. Обратите внимание, что -replace заменяет любые существующие замены для old[@v].

Флаги редактирования -require, -droprequire, -exclude, -dropexclude, -replace и -dropreplace могут быть повторены, и изменения применяются в указанном порядке.

Флаг -go=version устанавливает ожидаемую версию языка Go.

Флаг -print печатает окончательный вариант go.mod в текстовом формате, а не записывает его обратно в go.mod.

Флаг -json печатает конечный файл go.mod в формате JSON, а не записывает его обратно в go.mod. Вывод JSON соответствует этим типам Go:

type Module struct {
    Path string
    Version string
}

type GoMod struct {
    Module  Module
    Go      string
    Require []Require
    Exclude []Module
    Replace []Replace
}

type Require struct {
    Path string
    Version string
    Indirect bool
}

type Replace struct {
    Old Module
    New Module
}

Обратите внимание, что это описывает только сам файл go.mod, а не другие модули, на которые ссылаются косвенно. Для полного набора модулей, доступных для сборки, используйте 'go list -m -json all'.

Например, инструмент может получить go.mod как структуру данных, проанализировав выходные данные 'go mod edit -json', а затем может внести изменения, вызвав 'go mod edit' с -require, -exclude и так далее.

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go mod download, загрузка модулей в локальный кеш

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

go mod download [-json] [modules]

download загружает названные модули, которые могут быть шаблонами модулей, выбирающими зависимости основного модуля, или запросами модулей вида path@version. Без аргументов download применяется ко всем зависимостям основного модуля.

Команда go автоматически загружает модули по мере необходимости во время обычного выполнения. Команда "go mod download" полезна в основном для предварительного заполнения локального кэша или для вычисления ответов от прокси Go модуля.

По умолчанию download сообщает об ошибках в вывод стандартной ошибки (std err), но в остальном молчит. Флаг -json заставляет download печатать последовательность объектов JSON в стандартный вывод, описывая каждый загруженный модуль (или сбой), соответствующий этой Go структуре:

type Module struct {
    Path     string // путь к модулю
    Version  string // версия модуля
    Error    string // ошибка загрузки модуля
    Info     string // абсолютный путь к кешированному файлу .info
    GoMod    string // абсолютный путь к кешированному файлу .mod
    Zip      string // абсолютный путь к кешированному .zip файлу
    Dir      string // абсолютный путь к кешированному корневому каталогу источника
    Sum      string // контрольная сумма для пути, версии (как в go.sum)
    GoModSum string // контрольная сумма для go.mod (как в go.sum)
}

Смотрите 'go help modules' для получения дополнительной информации о запросах модулей.

---

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

• Go модули
• Команды go: go mod, обслуживание модуля
• Команды go: go get, загрузка и установка пакетов и зависимостей

Команды go: go mod, обслуживание модуля

go mod обеспечивает доступ к операциям над модулями.

Обратите внимание, что поддержка модулей встроена во все команды go, а не только в 'go mod'. Например, ежедневное добавление, удаление, обновление и понижение зависимостей должны выполняться с помощью 'go get'. См. 'go help modules' для обзора функциональности модуля.

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

go mod <command> [arguments]

Команды (command):

download    скачать модули в локальный кеш
edit        редактировать go.mod из инструментов или скриптов
graph       напечатать граф требований модуля
init        инициализировать новый модуль в текущем каталоге
tidy        добавить отсутствующие и удалить неиспользуемые модули
vendor      делает вендорную копию зависимостей
verify      проверить зависимости ожидаемого содержания
why         объяснять, зачем нужны пакеты или модули

Используйте "go help mod <command>" для получения дополнительной информации о команде.

---

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

• Go модули
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go list, вывод списка пакетов или модулей

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

go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

list выводит список именованных пакетов, по одному на строку. Чаще всего используются флаги -f и -json, которые управляют формой вывода, напечатанной для каждого пакета. Другие флаги списка, описанные ниже, контролируют более конкретные детали.

Вывод по умолчанию показывает путь импорта пакета:

bytes
encoding/json
github.com/gorilla/mux
golang.org/x/net/html

Флаг -f указывает альтернативный формат для списка, используя синтаксис шаблона пакета. Вывод по умолчанию эквивалентен -f '{{.ImportPath}}'. Структура, передаваемая в шаблон:

type Package struct {
    Dir           string   // каталог, содержащий исходный код пакета
    ImportPath    string   // путь импорта пакета в dir
    ImportComment string   // путь в import комментарии в утверждении пакета (package statement)
    Name          string   // имя пакета
    Doc           string   // строка документации пакета
    Target        string   // путь установки
    Shlib         string   // разделяемая (shared) библиотека, которая содержит этот пакет (устанавливается только когда -linkshared)
    Goroot        bool     // этот пакет в Go root?
    Standard      bool     // этот пакет является частью стандартной Go библиотеки?
    Stale         bool     // будет ли 'go install' делать что-либо с этим пакетом?
    StaleReason   string   // объяснение для Stale==true
    Root          string   // Go root или Go path dir содержащий этот пакет
    ConflictDir   string   // эта директория затеняет(shadows) Dir в $GOPATH
    BinaryOnly    bool     // бинарный пакет: не может быть перекомпилирован из исходных файлов
    ForTest       string   // пакет только для использования в именованном тесте
    Export        string   // файл, содержащий данные экспорта (при использовании -export)
    Module        *Module  // информация о модуле, содержащем пакет, если есть (может быть nil)
    Match         []string // шаблоны командной строки, соответствующие этому пакету
    DepOnly       bool     // пакет является только зависимостью, явно не перечисляемой

    // Исходные файлы
    GoFiles         []string // .go исходные файлы (исключая CgoFiles, TestGoFiles, XTestGoFiles)
    CgoFiles        []string // .go исходные файлы которые импортируют "C"
    CompiledGoFiles []string // .go файлы, представленные компилятору (при использовании -compiled)
    IgnoredGoFiles  []string // .go исходные файлы игнориремые из-за ограничений сборки
    CFiles          []string // .c исходные файлы
    CXXFiles        []string // .cc, .cxx и .cpp исходные файлы
    MFiles          []string // .m исходные файлы
    HFiles          []string // .h, .hh, .hpp и .hxx исходные файлы
    FFiles          []string // .f, .F, .for и .f90 Fortran исходные файлы
    SFiles          []string // .s исходные файлы
    SwigFiles       []string // .swig файлы
    SwigCXXFiles    []string // .swigcxx файлы
    SysoFiles       []string // .syso object файлы для добавления в архив
    TestGoFiles     []string // _test.go файлы в пакете
    XTestGoFiles    []string // _test.go файлы во внешнем пакете

    // Cgo директивы
    CgoCFLAGS    []string // cgo: флаги для C компилятора
    CgoCPPFLAGS  []string // cgo: флаги для C препроцессора
    CgoCXXFLAGS  []string // cgo: флаги для C++ компилятора
    CgoFFLAGS    []string // cgo: флаги для Fortran компилятора
    CgoLDFLAGS   []string // cgo: флаги для линкера (linker)
    CgoPkgConfig []string // cgo: pkg-config имена
    // Информация о зависимости
    Imports      []string          // import использованные для этого пакета
    ImportMap    map[string]string // карта (map) из исходного import в ImportPath (идентификационные записи опущены)
    Deps         []string          // все (рекурсивно) импортированные зависимости
    TestImports  []string          // импорты из TestGoFiles
    XTestImports []string          // импорты из XTestGoFiles

    // Информация об ошибке
    Incomplete bool            // этот пакет или зависимость имеет ошибку
    Error      *PackageError   // ошибка загрузки пакета
    DepsErrors []*PackageError // ошибки загрузки зависимостей
}

Пакеты, хранящиеся в каталогах поставщиков (vendor directories), сообщают о ImportPath, который включает путь к каталогу поставщика (например, "d/vendor/p" вместо "p"), так что ImportPath уникально идентифицирует данную копию пакета. Списки Imports, Deps, TestImports и XTestImports также содержат эти расширенные пути импорта.

Информация об ошибке, если таковая имеется,

type PackageError struct {
    ImportStack   []string // кратчайший путь от пакета, названного в командной строке, к этому
    Pos           string   // позиция ошибки (если есть, файл:строка:столбец)
    Err           string   // сама ошибка
}

Информация модуля является Module структурой, определенной в обсуждении списка -m ниже.

Функция шаблона "join" вызывает strings.Join.

Функция шаблона "context" возвращает контекст сборки, определенный как:

type Context struct {
    GOARCH        string   // целевая архитектура
    GOOS          string   // целевая операционная система
    GOROOT        string   // Go root
    GOPATH        string   // Go path
    CgoEnabled    bool     // можно ли использовать cgo
    UseAllFiles   bool     // использовать файлы независимо от +build строк, имен файлов
    Compiler      string   // компилятор для предположения при вычислении целевых путей
    BuildTags     []string // build огрничения для соотвествия в +build строках
    ReleaseTags   []string // выпуска текущего релиза совместимого с
    InstallSuffix string   // суффикс для использования в имени установочного каталога
}

Для получения дополнительной информации о значении этих полей см. документацию для типа Context пакета go/build.

Флаг -json заставляет печатать данные пакета в формате JSON вместо использования формата шаблона.

Флаг -compiled заставляет список устанавливать CompiledGoFiles в исходные файлы Go, представленные компилятору. Обычно это означает, что он повторяет файлы, перечисленные в GoFiles, а затем также добавляет код Go, сгенерированный путем обработки CgoFiles и SwigFiles. Список Imports содержит объединение всех импортов из GoFiles и CompiledGoFiles.

Флаг -deps заставляет list перебирать не только именованные пакеты, но и все их зависимости. Он просматривает их в глубине первого обхода после заказа, так что пакет перечисляется только после всех его зависимостей. Для пакетов, явно не указанных в командной строке, для поля DepOnly будет установлено значение true.

Флаг -e изменяет обработку ошибочных пакетов, которые не могут быть найдены или искажены. По умолчанию команда list выводит ошибку на стандартную ошибку для каждого ошибочного пакета и не учитывает пакеты при обычной печати. С флагом -e команда list никогда не печатает ошибки в стандартную ошибку и вместо этого обрабатывает ошибочные пакеты обычной печатью. Ошибочные пакеты будут иметь непустое поле ImportPath и не нулевую Error; другая информация может отсутствовать или может не отсутствовать (обнулена).

Флаг -export приводит к тому, что list устанавливает в поле Export имя файла, содержащего актуальную информацию об экспорте для данного пакета.

Флаг -find заставляет список идентифицировать именованные пакеты, но не разрешать их зависимости: списки Imports и Deps будут пустыми.

Флаг -test заставляет list сообщать не только о названных пакетах, но и об их бинарных файлах тестов (для пакетов с тестами), чтобы передать инструментам анализа исходного кода, как именно создаются тестовые бинарные файлы. Указанный путь импорта для тестового бинарного файла - это путь импорта пакета, за которым следует суффикс ".test", как в "math/rand.test". При создании теста иногда необходимо перестроить определенные зависимости специально для этого теста (чаще всего сам тестируемый пакет). Указанный путь импорта пакета, перекомпилированного для конкретного тестового бинарного файла, сопровождается пробелом и именем тестового бинарного файла в скобках, как в "math/rand [math/rand.test]" или "regexp [sort.test]". В поле ForTest также указывается имя тестируемого пакета ("math/rand" или "sort" в предыдущих примерах).

Пути к файлам Dir, Target, Shlib, Root, ConflictDir и Export - это абсолютные пути.

По умолчанию списки GoFiles, CgoFiles и т.д. Содержат имена файлов в Dir (то есть пути относительно Dir, а не абсолютные пути). Сгенерированные файлы, добавленные при использовании флагов -compiled и -test, представляют собой абсолютные пути, ссылающиеся на кэшированные копии сгенерированных исходных файлов Go. Хотя они являются исходными файлами Go, пути могут не заканчиваться на ".go".

Флаг -m заставляет list перечислять модули вместо пакетов.

При перечислении модулей флаг -f по-прежнему указывает шаблон формата, применяемый к Go структуре, но теперь это Module структура:

type Module struct {
    Path     string       // путь к модулю
    Version  string       // версия модуля
    Versions []string     // доступные версии модуля (с -versions)
    Replace  *Module      // замещен на этот модуль
    Time     *time.Time   // временная версия была создана
    Update   *Module      // доступно обновление, если есть (с -u)
    Main     bool         // это основной (main) модуль?
    Indirect bool         // является ли этот модуль только косвенной зависимостью основного модуля?
    Dir      string       // каталог, содержащий файлы для этого модуля, если есть
    GoMod    string       // путь к файлу go.mod для этого модуля, если есть
    Error    *ModuleError // ошибка загрузки модуля
}

type ModuleError struct {
    Err string // сама ошибка
}

По умолчанию выводится путь к модулю, а затем информация о версии и замене, если таковые имеются. Например, 'go list -m all' может вывести:

my/main/module
golang.org/x/text v0.3.0 => /tmp/text
rsc.io/pdf v0.1.1

Структура Module имеет метод String, который форматирует эту строку вывода, поэтому формат по умолчанию эквивалентен -f '{{.String}}'.

Обратите внимание, что когда модуль был заменен, его поле Replace описывает модуль замены, а его поле Dir устанавливается на исходный код замены, если таковой имеется. (То есть, если Replace не ноль, тогда Dir установлен в Replace.Dir, без доступа к замененному исходному коду.)

Флаг -u добавляет информацию о доступных обновлениях. Когда последняя версия данного модуля новее текущей, list -u устанавливает в поле Update в Module информацию о более новом модуле. Метод String модуля указывает доступное обновление путем форматирования новой версии в скобках после текущей версии. Например, 'go list -m -u all' может вывести:

my/main/module
golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
rsc.io/pdf v0.1.1 [v0.1.2]

(Для инструментов 'go list -m -u -json all' может быть удобнее анализировать.)

Флаг -versions приводит к тому, что list устанавливает в поле Versions модуля список всех известных версий этого модуля, упорядоченных в соответствии с семантической версией, начиная с самой ранней и последней версии. Флаг также изменяет формат вывода по умолчанию для отображения пути к модулю, за которым следует разделенный пробелами список версий.

Аргументы для списка -m интерпретируются как список модулей, а не пакетов. Основным модулем является модуль, содержащий текущий каталог. Активные модули являются основным модулем и его зависимостями. Без аргументов list -m показывает основной модуль. С аргументами list -m показывает модули, указанные аргументами. Любой из активных модулей может быть указан его путем к модулю. Специальный шаблон "all" определяет все активные модули, сначала основной модуль, а затем зависимости, отсортированные по пути модуля. Шаблон, содержащий "...", указывает активные модули, чьи пути модулей соответствуют шаблону. Запрос формы path@version указывает результат этого запроса, который не ограничивается активными модулями. Смотрите 'go help modules' для получения дополнительной информации о запросах модулей.

Функция шаблона "module" принимает один строковый аргумент, который должен быть путем к модулю или запросом, и возвращает указанный модуль в виде структуры модуля. Если произойдет ошибка, результатом будет структура модуля с полем Error, отличным от nil.

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

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

Для получения дополнительной информации о модулях см. 'go help modules'.

---

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

• Команды go: go get, загрузка и установка пакетов и зависимостей
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go install, компиляция и установка пакетов и зависимостей

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

go install [-i] [build flags] [packages]

Install компилирует и устанавливает пакеты, названные путями импорта.

Флаг -i также устанавливает зависимости названных пакетов.

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

Смотрите также: go build, go get, go clean.

---

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

• Команды go: go get, загрузка и установка пакетов и зависимостей
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go get, загрузка и установка пакетов и зависимостей

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

go get [-d] [-f] [-t] [-u] [-v] [-fix] [-insecure] [build flags] [packages]

Get загружает пакеты, названные путями импорта, вместе с их зависимостями. Затем он устанавливает именованные пакеты, как 'go install'.

Флаг -d дает команду остановиться после загрузки пакетов; то есть он инструктирует get не устанавливать пакеты.

Флаг -f, действительный только в том случае, если задан параметр -u, заставляет get -u не проверять, был ли каждый пакет извлечен из репозитория исходного кода, подразумеваемого путем его импорта. Это может быть полезно, если источником является локальная ветвь оригинала.

Флаг -fix указывает запустить утилиту исправления для загруженных пакетов перед разрешением зависимостей или созданием кода.

Флаг -insecure разрешает выборку из репозиториев и разрешение пользовательских доменов с использованием небезопасных схем, таких как HTTP. Используйте с осторожностью.

Флаг -t указывает get также загружать пакеты, необходимые для построения тестов для указанных пакетов.

Флаг -u дает команду использовать сеть для обновления именованных пакетов и их зависимостей. По умолчанию get использует сеть для проверки отсутствующих пакетов, но не использует ее для поиска обновлений существующих пакетов.

Флаг -v включает подробный прогресс и отладочный вывод.

Get также принимает флаги сборки (build flags) для управления установкой. Смотрите 'go help build'.

При извлечении нового пакета get создает целевой каталог GOPATH/src/. Если GOPATH содержит несколько записей, get использует первую. Для более подробной информации смотрите: 'go help gopath'.

При проверке или обновлении пакета get ищет ветку или тег, которые соответствуют локальной версии Go. Самое важное правило заключается в том, что, если локальная установка работает под управлением версии "go1", необходимо выполнить поиск ветви или тега с именем "go1". Если такой версии не существует, она извлекает ветвь пакета по умолчанию.

Когда go get извлекает или обновляет Git-репозиторий, он также обновляет любые подмодули git, на которые ссылается репозиторий.

get никогда не проверяет и не обновляет код, хранящийся в каталогах поставщиков (vendor directories).

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

Подробнее о том, как 'go get' находит исходный код для загрузки, см. 'go help importpath'.

Этот текст описывает поведение get при использовании GOPATH для управления исходным кодом и зависимостями. Если вместо этого команда go выполняется в режиме с поддержкой модулей, сведения о флагах и эффектах get меняются, как и 'go help get'. Смотрите 'go help modules' и 'go help module-get'.

Смотрите также: go build, go install, go clean.

---

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

• Go FAQ: Как управлять версиями пакетов, используя "go get"?
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды 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, удаление объектных файлов и кэшированных файлов

Команды go: go fmt, gofmt (переформатировать) источники (исходные файлы) пакетов

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

go fmt [-n] [-x] [packages]

Fmt запускает команду 'gofmt -l -w' для пакетов, названных путями импорта. Он печатает имена файлов, которые были изменены.

Для получения дополнительной информации о gofmt см. "go doc cmd/gofmt".

Флаг -n печатает команды, которые будут выполнены.

Флаг -x печатает команды по мере их выполнения.

Чтобы запустить gofmt с конкретными опциями, запустите сам gofmt.

Смотрите также: go fix, go vet.

---

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

• Go Code Review Comments: gofmt
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go fix, обновить пакеты, чтобы использовать новые API

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

go fix [packages]

Fix запускает команду go fix для пакетов, названных путями импорта.

Чтобы запустить fix с конкретными параметрами, запустите 'go tool fix'.

Смотрите также: go fmt, go vet.

---

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

• Команды Go: введение
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go env, напечатать информацию о среде окружения Go

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

go env [-json] [var ...]

Env печатает информацию о среде окружения Go.

По умолчанию env печатает информацию в виде сценария оболочки (shell script) (в Windows - командный файл (batch file)). Если в качестве аргументов указано одно или несколько имен переменных, env печатает значение каждой именованной переменной в отдельной строке.

Флаг -json печатает среду в формате JSON, а не в виде сценария оболочки.

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

---

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

• Команды Go: введение
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go doc, показать документацию для пакета или символа

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

go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]

doc печатает комментарии документации, связанные с элементом, идентифицированным его аргументами (поле package, const, func, type, var, method или struct), за которым следует однострочная сводка каждого из элементов первого уровня "под" этим элементом (объявления уровня пакета для пакета, методы для типа и т. д.).

doc принимает ноль, один или два аргумента.

При отсутствии аргументов, то есть когда запускается как

go doc

он печатает документацию пакета для пакета в текущем каталоге. Если пакет является командой (основной пакет), экспортированные символы пакета удаляются из представления, если не указан флаг -cmd.

При запуске с одним аргументом аргумент обрабатывается как Go-синтаксическое представление элемента, подлежащего документированию. То, что выбирает аргумент, зависит от того, что установлено в GOROOT и GOPATH, а также от формы аргумента, которая схематически является одной из них:

go doc <pkg>
go doc <sym>[.<methodOrField>]
go doc [<pkg>.]<sym>[.<methodOrField>]
go doc [<pkg>.][<sym>.]<methodOrField>

Первый элемент в этом списке, соответствующий аргументу, - тот, чья документация напечатана. (См. Примеры ниже.) Однако, если аргумент начинается с заглавной буквы, предполагается, что он идентифицирует символ или метод в текущем каталоге.

Для пакетов порядок сканирования определяется лексически в порядке убывания. Таким образом, представленный пакет является тем, который соответствует поиску и является ближайшим к корню и лексически первым на его уровне иерархии. Дерево GOROOT всегда сканируется полностью перед GOPATH.

Если пакет не указан или не найден, пакет в текущем каталоге выбирается, поэтому "go doc Foo" показывает документацию для символа Foo в текущем пакете.

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

При запуске с двумя аргументами, первый должен быть полным путем пакета (а не просто суффиксом), а второй - символом или символом с методом или структурным полем. Это похоже на синтаксис, принятый godoc:

go doc <pkg> <sym>[.<methodOrField>]

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

Примеры:

go doc
    Показать документацию для текущего пакета.
go doc Foo
    Показать документацию для Foo в текущем пакете.
    (Foo начинается с заглавной буквы, 
    поэтому не может соотвествовать пути пакета.)
go doc encoding/json
    Показать документацию для encoding/json пакета.
go doc json
    Сокращение для encoding/json.
go doc json.Number (или go doc json.number)
    Показать документацию и краткое описание метода для json.Number.
go doc json.Number.Int64 (или go doc json.number.int64)
    Показать документацию для json.Number Int64 метода.
go doc cmd/doc
    Показать пакет документов для команды doc.
go doc -cmd cmd/doc
    Показать документы пакета и экспортированные символы в команде doc.
go doc template.new
    Показать документацию для функции New в html/template.
    (html/template лексически идет до text/template)
go doc text/template.new # Один аргумент
    Показать документацию для функции New в text/template.
go doc text/template new # Два аргумента
    Показать документацию для функции New в text/template.

По крайней мере, в текущем дереве все эти вызовы выводят
документация для метода декодирования json.Decoder:

go doc json.Decoder.Decode
go doc json.decoder.decode
go doc json.decode
cd go/src/encoding/json; go doc decode

Флаги:

-all
    Показать всю документацию для пакета.
-c
    Учитывать регистр при сопоставлении символов.
-cmd
    Рассматривайте команду (основной пакет, пакет main) как для обычного пакета.
    В противном случае экспортируемые символы пакета main будут скрыты
    при показе документации верхнего уровня пакета.
-src
    Показать полный исходный код символа. Это будет
    отображать полный исходный код Go своей декларации и
    определение, такое как определение функции (включая
    тело), объявление типа или вложенный const
    блок. Поэтому выходные данные могут включать в себя неэкспортированные
    подробности.
-u
    Показать документацию для неэкспортированных, а также экспортированных
    символов, методов и полей.

---

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

• Команды Go: введение
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go clean, удаление объектных файлов и кэшированных файлов

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

go clean [clean flags] [build flags] [packages]

clean удаляет объектные файлы из исходных каталогов пакетов. Команда go собирает большинство объектов во временном каталоге, поэтому go clean в основном касается объектных файлов, оставленных другими инструментами, или ручными вызовами go build.

В частности, clean удаляет следующие файлы в каждом из исходных каталогов, соответствующих путям импорта:

_obj/            старый объектный каталог, оставленный от Makefile'ов
_test/           старый тестовый каталог, оставленный от Makefile'ов
_testmain.go     старый gotest файл, оставленный от Makefile'ов
test.out         старый тестовый журнал, оставленный от Makefile'ов
build.out        старый тестовый журнал, оставленный от Makefile'ов
*.[568ao]        object файлы, оставленные от Makefile'ов

DIR(.exe)        от go build
DIR.test(.exe)   от go test -c
MAINFILE(.exe)   от go build MAINFILE.go
*.so             от SWIG

В списке DIR представляет собой последний элемент пути к каталогу, а MAINFILE - базовое имя любого исходного файла Go в каталоге, который не включается при сборке пакета.

Флаг -i заставляет команду clean удалить соответствующий установленный архив или бинарный файл (который "go install" создаст).

Флаг -n заставляет clean печатать команды удаления, которые он будет выполнять, но не запускать их.

Флаг -r приводит к рекурсивному применению команды clean ко всем зависимостям пакетов, указанным в путях импорта.

Флаг -x заставляет команду clean выводить команды удаления по мере их выполнения.

Флаг -cache заставляет clean удалить весь кэш сборки go.

Флаг -testcache заставляет clean сделать истекшими все результаты теста в кэше сборки go.

Флаг -modcache заставляет clean удалить весь кэш загрузки модуля, включая распакованный исходный код версионных зависимостей.

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

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

---

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

• Команды Go: введение
• Инструмент go, команды
• Команды go: go build, компиляция пакетов и зависимостей

Команды go: go build, компиляция пакетов и зависимостей

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

go build [-o output] [-i] [build flags] [packages]

build компилирует пакеты, названные путями импорта, вместе с их зависимостями, но не устанавливает результаты.

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

При компиляции единичного основного пакета (main package) build записывает полученный исполняемый файл в выходной файл, названный в честь первого исходного файла ("go build ed.go rx.go" записывает "ed" или "ed.exe") или в каталог исходного кода ("go build unix/sam" записывает "sam" или "sam.exe"). Суффикс ".exe" добавляется при записи исполняемого файла Windows.

При компиляции нескольких пакетов или одного неосновного пакета, build компилирует пакеты, но отбрасывает полученный объект, служа только для проверки возможности сборки пакетов.

При компиляции пакетов build игнорирует файлы, заканчивающиеся на "_test.go".

Флаг -o, разрешен только при компиляции одного пакета, он заставляет build записывать полученный исполняемый файл или объект в именованный выходной файл вместо поведения по умолчанию, описанного выше.

Флаг -i устанавливает пакеты, которые являются зависимостями от цели.

Флаги сборки (build flags) используются командами build, clean, get, install, list, run и test:

-a
    заставляет пересобрать (rebuild) пакеты, 
    которые и так уже имеют последнюю версию (up-to-date).
-n
    печатает команды, но не запускает их.
-p n
    количество программ, таких как команды сборки или
    тестирования бинарных файлов, которые можно запускать параллельно.
    По умолчанию равно количеству доступных ядер процессоров.
-race
    включить обнаружение гонки данных.
    Поддерживается только в linux/amd64, freebsd/amd64, darwin/amd64 и windows/amd64.
-msan
    включить взаимодействие с очистителем памяти.
    Поддерживается только на linux/amd64, linux/arm64
    и только с Clang/LLVM в качестве C компилятора хоста.
-v
    печатать имена пакетов по мере их компиляции.
-work
    распечатать имя временного рабочего каталога и
    не удалять его при выходе.
-x
    распечатать команды.
-asmflags '[pattern =] arg list'
    аргументы для передачи при каждом вызове go tool asm.
-buildmode mode
    режим сборки для использования. Смотрите 'go help buildmode' для более подробной информации.
-compiler name
    имя используемого компилятора, как в runtime.Compiler (gccgo или gc).
-gccgoflags '[pattern =] arg list'
    аргументы для передачи при каждом вызове компилятора/компоновщика gccgo (gccgo compiler/linker).
-gcflags '[pattern =] arg list'
    аргументы для передачи при каждом вызове go tool compile.
-installsuffix suffix
    суффикс для использования в имени каталога установки пакета,
    чтобы сохранить вывод отдельно от сборок по умолчанию.
    При использовании флага -race суффикс установки автоматически устанавливается равным race
    или, если задано явно, к нему добавлен _race. Аналогично для -msan
    флага. Использование параметра -buildmode, который требует нестандартных флагов компиляции
    имеет аналогичный эффект.
-ldflags '[pattern =] arg list'
    аргументы для передачи при каждом вызове go tool link.
-linkshared
    ссылка на общие библиотеки, ранее созданные с
    -buildmode=shared.
-mod mode
    Режим (mode) загрузки модуля для использования: readonly или vendor.
    См. 'go help modules' для получения дополнительной информации.
-pkgdir dir
    установить и загрузить все пакеты из dir вместо обычных мест.
    Например, при сборке с нестандартной конфигурацией,
    используйте -pkgdir для хранения сгенерированных пакетов в отдельном месте.
-tags 'tag list'
    разделенный пробелами список тегов сборки, которые необходимо учитывать во время
    сборки. Для получения дополнительной информации о тегах сборки см. Описание
    ограничения сборки в документации для пакета go/build.
-toolexec 'cmd args'
    программа, используемая для вызова таких программ, как vet и asm.
    Например, вместо запуска asm будет запущена команда go
    'cmd args /path/to/asm <аргументы для asm>'.

Флаги -asmflags, -gccgoflags, -gcflags и -ldflags принимают разделенный пробелами список аргументов для передачи базовому инструменту во время сборки. Чтобы вставить пробелы в элемент списка, заключите его в одинарные или двойные кавычки. Списку аргументов может предшествовать паттерн пакета и знак равенства, который ограничивает использование этого списка аргументов до построения пакетов, соответствующих этому паттерну (описание паттернов пакетов см. в «go help packages»). Без паттерна список аргументов применяется только к пакетам, указанным в командной строке. Флаги могут повторяться с разными паттернами, чтобы указывать разные аргументы для разных наборов пакетов. Если пакет соответствует паттернам, указанным в нескольких флагах, побеждает последнее совпадение в командной строке. Например, 'go build -gcflags=-S fmt' печатает разборку (disassembly) только для пакета fmt, а 'go build -gcflags=all=-S fmt' печатает разборку (disassembly) для fmt и всех его зависимостей.

Подробнее об указании пакетов см. в разделе 'go help packages'. Чтобы узнать больше о том, где установлены пакеты и бинарные файлы, запустите 'go help gopath'. Чтобы узнать больше о вызовах между Go и C/C++, запустите 'go help c'.

Примечание: build придерживается определенных соглашений, таких как те, которые описаны в 'go help gopath'. Однако не все проекты могут следовать этим правилам. Установки, которые имеют свои собственные соглашения или используют отдельную систему сборки программного обеспечения, могут использовать вызовы более низкого уровня, такие как 'go tool compile' и 'go tool link', чтобы избежать некоторых накладных расходов и проектных решений инструмента сборки.

Смотрите также: go install, go get, go clean.

---

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

• Команды Go: введение
• Инструмент go, команды
• Как писать Go код

Инструмент go, команды

go - это инструмент для управления исходным кодом Go.

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

go <command> [arguments]

Команды (command):

bug         начать отчет об ошибке
build       компиляция пакетов и зависимостей
clean       удалить объектные файлы (object files) и кэшированные файлы
doc         показать документацию для пакета или символа
env         напечатать информацию о среде окружения Go
fix         обновить пакеты чтобы использовать новые API
fmt         gofmt (переформатировать) исходный файлы пакета
generate    сгенерировать файлы Go посредством обработки исходного кода
get         скачать и установить пакеты и зависимости
install     скомпилировать и установить пакеты и зависимости
list        вывести список пакетов или модулей
mod         обслуживание модуля
run         скомпилировать и запустить Go программу 
test        тестировать пакеты
tool        запускает определенный go tool
version     напечатать версию Go
vet         сообщить о вероятных ошибках в пакетах

Используйте "go help <command>" для получения дополнительной информации о команде.

Дополнительные вспомогательные темы (topic):

buildmode   режимы сборки
c           вызов между Go и C
cache       сборка и тестирование кеша
environment переменные среды окружения
filetype    типы файлов
go.mod      файл go.mod
gopath      переменная среды окружения GOPATH
gopath-get  legacy GOPATH go get
goproxy     протокол прокси модуля
importpath  синтакс import пути
modules     модули, версии модулей и другое
module-get  осведамленный о муодулях go get
packages    списки пакетов и паттерны
testflag    флаги тестирования
testfunc    функции тестирования

Используйте "go help <topic>" для получения дополнительной информации по этой теме (topic).

Начать отчет об ошибке

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

go bug

Открывает браузер по умолчанию и запускает новый отчет об ошибке. Отчет содержит полезную системную информацию.

---

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

• Команды Go: введение
• Как запускать Go программы
• Как писать Go код

Команды Go: введение

Существует набор программ для сборки и обработки исходного кода Go. Вместо непосредственного запуска программы, они обычно запускаются программой go.

Наиболее распространенный способ запуска этих программ - это подкоманда программы go, например, go fmt. При выполнении этого команда работает с полными пакетами исходного кода Go, при этом программа go вызывает базовый бинарный файл с аргументами, подходящими для обработки на уровне пакета.

Программы также можно запускать как отдельные бинарные файлы с неизмененными аргументами, используя подкоманду go tool, например go tool cgo. Для большинства команд это в основном полезно для отладки. Некоторые команды, такие как pprof, доступны только через подкоманду go tool.

Наконец, команды fmt и godoc устанавливаются как обычные бинарные файлы, называемые gofmt и godoc, потому что на них так часто ссылаются.

---

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

• Go Code Review Comments: введение, gofmt
• Как запускать Go программы
• Как писать Go код

Go модули: удаление неиспользуемых зависимостей

Мы удалили все наши использования rsc.io/quote, но он по-прежнему отображается в списке go -m all и в нашем файле go.mod:

$ go list -m all
example.com/hello
golang.org/x/text v0.3.0
rsc.io/quote v1.5.2
rsc.io/quote/v3 v3.1.0
rsc.io/sampler v1.3.1
$ cat go.mod
module example.com/hello

go 1.12

require (
    golang.org/x/text v0.3.0 // indirect
    rsc.io/quote v1.5.2
    rsc.io/quote/v3 v3.0.0
    rsc.io/sampler v1.3.1 // indirect
)
$

Почему? Потому что сборка одного пакета, как с помощью go build или go test, может легко определить, когда чего-то не хватает и что нужно добавить, но не тогда, когда что-то можно безопасно удалить. Удаление зависимости может быть выполнено только после проверки всех пакетов в модуле и всех возможных комбинаций тегов сборки для этих пакетов. Обычная команда build не загружает эту информацию, и поэтому она не может безопасно удалить зависимости.

Команда go mod tidy очищает эти неиспользуемые зависимости:

$ go mod tidy
$ go list -m all
example.com/hello
golang.org/x/text v0.3.0
rsc.io/quote/v3 v3.1.0
rsc.io/sampler v1.3.1
$ cat go.mod
module example.com/hello

go 1.12

require (
    golang.org/x/text v0.3.0 // indirect
    rsc.io/quote/v3 v3.1.0
    rsc.io/sampler v1.3.1 // indirect
)

$ go test
PASS
ok      example.com/hello    0.020s
$

---

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

• Go модули: создание нового модуля
• Go модули: добавление зависимости от новой основной версии
• Go модули: обновление зависимости до новой основной версии

Go модули: обновление зависимости до новой основной версии

Завершим наше преобразование от использования rsc.io/quote к использованию только rsc.io/quote/v3. Из-за существенного изменения версии следует ожидать, что некоторые API-интерфейсы могут быть удалены, переименованы или иным образом изменены несовместимыми способами. Читая документы, мы видим, что Hello стал HelloV3:

$ go doc rsc.io/quote/v3
package quote // import "rsc.io/quote"

Package quote collects pithy sayings.

func Concurrency() string
func GlassV3() string
func GoV3() string
func HelloV3() string
func OptV3() string
$

Мы можем обновить наше использование quote.Hello() в hello.go, чтобы использовать quoteV3.HelloV3():

package hello

import quoteV3 "rsc.io/quote/v3"

func Hello() string {
    return quoteV3.HelloV3()
}

func Proverb() string {
    return quoteV3.Concurrency()
}

И затем на этом этапе больше нет необходимости в переименованном импорте, поэтому мы можем отменить это:

package hello

import "rsc.io/quote/v3"

func Hello() string {
    return quote.HelloV3()
}

func Proverb() string {
    return quote.Concurrency()
}

Запустим тесты, чтобы убедиться, что все работает:

$ go test
PASS
ok      example.com/hello       0.014s

---

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

• Go модули: добавление зависимости
• Go модули: обновление зависимостей
• Go модули: добавление зависимости от новой основной версии

Go модули: добавление зависимости от новой основной версии

Добавим новую функцию в наш пакет, созданный в предыдущих постах: func Proverb возвращает пословицу о конкурентности в Go, вызвав quote.Concurrency, который предоставляется модулем rsc.io/quote/v3. Сначала мы обновляем hello.go, чтобы добавить новую функцию:

package hello

import (
    "rsc.io/quote"
    quoteV3 "rsc.io/quote/v3"
)

func Hello() string {
    return quote.Hello()
}

func Proverb() string {
    return quoteV3.Concurrency()
}

Затем мы добавляем тест в hello_test.go:

func TestProverb(t *testing.T) {
    want := "Concurrency is not parallelism."
    if got := Proverb(); got != want {
        t.Errorf("Proverb() = %q, want %q", got, want)
    }
}

Тогда мы можем протестировать наш код:

$ go test
go: finding rsc.io/quote/v3 v3.1.0
go: downloading rsc.io/quote/v3 v3.1.0
go: extracting rsc.io/quote/v3 v3.1.0
PASS
ok      example.com/hello    0.024s
$

Обратите внимание, что наш модуль теперь зависит как от rsc.io/quote, так и от rsc.io/quote/v3:

$ go list -m rsc.io/q...
rsc.io/quote v1.5.2
rsc.io/quote/v3 v3.1.0
$

Каждая отдельная основная версия (v1, v2 и т. Д.) модуля Go использует свой путь к модулю: начиная с версии v2, путь должен заканчиваться основной версией. В этом примере v3 из rsc.io/quote больше не является rsc.io/quote: вместо этого он идентифицируется путем к модулю rsc.io/quote/v3. Это соглашение называется семантическим контролем версий импорта, и оно дает несовместимым пакетам (пакетам с разными основными версиями) разные имена. Напротив, v1.6.0 из rsc.io/quote должен быть обратно совместим с v1.5.2, поэтому он повторно использует имя rsc.io/quote. (В предыдущем посте rsc.io/sampler v1.99.99 должен был быть обратно совместим с rsc.io/sampler v1.3.0, но могут возникать ошибки или неверные предположения клиента о поведении модуля.)

Команда go позволяет сборке включать не более одной версии любого конкретного пути модуля, то есть не более одной версии каждой основной версии: одну rsc.io/quote, одну rsc.io/quote/v2, одну rsc.io/quote/v3 и тд. Это дает авторам модулей четкое правило о возможном дублировании пути к одному модулю: невозможно собрать программу как с rsc.io/quote v1.5.2, так и с rsc.io/quote v1.6.0. В то же время, разрешение разных основных версий модуля (поскольку они имеют разные пути) дает потребителям модуля возможность постепенного обновления до новой основной версии. В этом примере мы хотели использовать quote.Concurrency из rsc/quote/v3 v3.1.0, но пока не готовы перенести использование rsc.io/quote v1.5.2. Возможность постепенной миграции особенно важна в большой программе или кодовой базе.

---

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

• Go модули: создание нового модуля
• Go модули: добавление зависимости
• Go модули: обновление зависимостей

Go модули: обновление зависимостей

В модулях Go в версии указываются теги семантической версии. Семантическая версия состоит из трех частей: мажорной, минорной и патча. Например, для v0.1.2 основной (мажорной) версией является 0, второстепенной (минорной) версией - 1, а версией патча - 2. Пройдемся по паре небольших обновлений версии. В следующем посте мы рассмотрим обновление основной версии.

Из вывода списка go -m all видно, что мы используем немаркированную версию golang.org/x/text. Обновимся до последней версии с тегами и проверим, что наш тест, созданный в предыдущих постах, все еще работает:

$ go get golang.org/x/text
go: finding golang.org/x/text v0.3.0
go: downloading golang.org/x/text v0.3.0
go: extracting golang.org/x/text v0.3.0
$ go test
PASS
ok      example.com/hello    0.013s
$

Все проходит. Еще раз посмотрим на список go -m all и файл go.mod:

$ go list -m all
example.com/hello
golang.org/x/text v0.3.0
rsc.io/quote v1.5.2
rsc.io/sampler v1.3.0
$ cat go.mod
module example.com/hello

go 1.12

require (
    golang.org/x/text v0.3.0 // indirect
    rsc.io/quote v1.5.2
)
$

Пакет golang.org/x/text обновлен до последней версии с тегами (v0.3.0). Файл go.mod был обновлен и теперь также указывает v0.3.0. indirect комментарий указывает, что зависимость не используется непосредственно этим модулем, только косвенно другими зависимостями модуля.

Теперь попробуем обновить минорную версию rsc.io/sampler. Начнем так же, запустив go get и запустив тесты:

$ go get rsc.io/sampler
go: finding rsc.io/sampler v1.99.99
go: downloading rsc.io/sampler v1.99.99
go: extracting rsc.io/sampler v1.99.99
$ go test
--- FAIL: TestHello (0.00s)
    hello_test.go:8: Hello() = "99 bottles of beer on the wall, 99 bottles of beer, ...", want "Hello, world."
FAIL
exit status 1
FAIL    example.com/hello    0.014s
$

Провал теста показывает, что последняя версия rsc.io/sampler несовместима с нашим использованием. Перечислим доступные теговые версии этого модуля:

$ go list -m -versions rsc.io/sampler
rsc.io/sampler v1.0.0 v1.2.0 v1.2.1 v1.3.0 v1.3.1 v1.99.99
$

Мы использовали v1.3.0; v1.99.99 явно не годится. Может быть, мы можем попробовать использовать v1.3.1 вместо этого:

$ go get rsc.io/sampler@v1.3.1
go: finding rsc.io/sampler v1.3.1
go: downloading rsc.io/sampler v1.3.1
go: extracting rsc.io/sampler v1.3.1
$ go test
PASS
ok      example.com/hello    0.022s
$

Обратите внимание на явный @v1.3.1 в аргументе go get. В общем, каждый аргумент, передаваемый в get get, может иметь явную версию; значение по умолчанию - @latest, которое разрешается до последней версии, определенной ранее.

---

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

• Go модули: введение
• Go модули: создание нового модуля
• Go модули: добавление зависимости

Go модули: добавление зависимости

Основной мотивацией для модулей Go было улучшение опыта использования (то есть добавления зависимости) кода, написанного другими разработчиками.

Обновим файл hello.go, который мы создали в предыдущем посте, для импорта rsc.io/quote и используем его для реализации Hello:

package hello

import "rsc.io/quote"

func Hello() string {
    return quote.Hello()
}

Теперь запустим тест, который мы создали в предыдущем посте:

$ go test
go: finding rsc.io/quote v1.5.2
go: downloading rsc.io/quote v1.5.2
go: extracting rsc.io/quote v1.5.2
go: finding rsc.io/sampler v1.3.0
go: finding golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
go: downloading rsc.io/sampler v1.3.0
go: extracting rsc.io/sampler v1.3.0
go: downloading golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
go: extracting golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
PASS
ok      example.com/hello    0.023s
$

Команда go разрешает импорт с использованием определенных версий модуля зависимостей, перечисленных в go.mod. Когда он обнаруживает импорт пакета, не предоставленного ни одним модулем в go.mod, команда go автоматически ищет модуль, содержащий этот пакет, и добавляет его в go.mod, используя последнюю версию. ("Последняя" определяется как последняя помеченная как stable (не prerelease) версия, либо последняя помеченная как prerelease версия, либо последняя версия без тегов.) В нашем примере go test разрешил новый импорт rsc.io/quote в модуль rsc.io/quote v1.5.2. Он также загрузил две зависимости, используемые rsc.io/quote, а именно rsc.io/sampler и golang.org/x/text. В файле go.mod записываются только прямые зависимости:

$ cat go.mod
module example.com/hello

go 1.12

require rsc.io/quote v1.5.2
$

Вторая команда go test не будет повторять эту работу, поскольку go.mod обновлен и загруженные модули кэшируются локально (в $GOPATH/pkg/mod):

$ go test
PASS
ok      example.com/hello    0.020s
$

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

Как мы видели выше, добавление одной прямой зависимости часто приводит и к другим косвенным зависимостям. Команда go list -m all перечисляет текущий модуль и все его зависимости:

$ go list -m all
example.com/hello
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c
rsc.io/quote v1.5.2
rsc.io/sampler v1.3.0
$

В выводе списка переходов текущий модуль, также известный как основной (main) модуль, всегда является первой строкой, за которой следуют зависимости, отсортированные по пути модуля.

Golang.org/x/text version v0.0.0-20170915032832-14c0d48ead0c является примером псевдо-версии, которая является синтаксисом версии команды go для определенного коммита без тегов.

В дополнение к go.mod команда go поддерживает файл с именем go.sum, содержащий ожидаемые криптографические хеши содержимого определенных версий модуля:

$ cat go.sum
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c h1:qgOY6WgZO...
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:Nq...
rsc.io/quote v1.5.2 h1:w5fcysjrx7yqtD/aO+QwRjYZOKnaM9Uh2b40tElTs3...
rsc.io/quote v1.5.2/go.mod h1:LzX7hefJvL54yjefDEDHNONDjII0t9xZLPX...
rsc.io/sampler v1.3.0 h1:7uVkIFmeBqHfdjD+gZwtXXI+RODJ2Wc4O7MPEh/Q...
rsc.io/sampler v1.3.0/go.mod h1:T1hPZKmBbMNahiBKFy5HrXp6adAjACjK9...
$

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

---

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

• Go модули: введение
• Go FAQ: Как управлять версиями пакетов, используя "go get"?
• Go модули: создание нового модуля