Показаны сообщения с ярлыком Вспомогательные темы инструмента go. Показать все сообщения
Показаны сообщения с ярлыком Вспомогательные темы инструмента go. Показать все сообщения

суббота, 6 июля 2019 г.

Вспомогательные темы инструмента go: модули

go help modules

Модуль представляет собой набор связанных пакетов Go. Модули - это единицы исходного кода для обмена и управления версиями. Команда go имеет прямую поддержку для работы с модулями, включая запись и разрешение зависимостей от других модулей. Модули заменяют старый подход, основанный на GOPATH, для указания, какие исходные файлы используются в данной сборке.

Предварительная поддержка модуля

Go 1.11 включает в себя предварительную поддержку модулей Go, включая новую команду 'go get' с поддержкой модулей. Поддержка будет продолжатся, сохраняя совместимость, до тех пор, пока она не будет объявлена официальной (больше не предварительной), а затем на более позднем этапе возможно будет удалена поддержка работы в GOPATH и старая команда 'go get'.

Самый быстрый способ воспользоваться преимуществами поддержки модуля Go 1.11 - выгрузить свой репозиторий в каталог за пределами GOPATH/src, создать там файл go.mod и запустить команды go из этого файлового дерева.

Для более детального управления поддержка модулей в Go 1.11 учитывает временную переменную среды GO111MODULE, для которой может быть задано одно из трех строковых значений: off, on или auto (по умолчанию). Если GO111MODULE=off, то команда go никогда не использует поддержку модулей. Вместо этого она ищет в каталогах поставщиков и GOPATH, чтобы найти зависимости; это "GOPATH mode" ("GOPATH режим"). Если GO111MODULE=on, то команда go требует использования модулей, никогда не обращаясь к GOPATH. Это называется командой, которая работает с модулем или работает в "module-aware mode" ("режиме с поддержкой модулей"). Если GO111MODULE=auto или не задано, то команда go включает или отключает поддержку модулей на основе текущего каталога. Поддержка модулей включается, только если текущий каталог находится вне GOPATH/src и сам содержит файл go.mod или находится под каталогом, содержащим файл go.mod.

В режиме с поддержкой модулей GOPATH больше не определяет значение импорта во время сборки, но по-прежнему хранит загруженные зависимости (в GOPATH/pkg/mod) и установленные команды (в GOPATH/bin, если не установлен GOBIN).


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


Вспомогательные темы инструмента go: пути импорта

Синтаксис пути импорта

go help importpath

Путь импорта обозначает пакет, хранящийся в локальной файловой системе. В общем случае путь импорта обозначает либо стандартный пакет (например, "unicode/utf8"), либо пакет, найденный в одном из рабочих пространств (подробнее см. go help gopath).

Относительные пути импорта

Путь импорта, начинающийся с ./ или ../, называется относительным путем. Цепочка инструментов поддерживает относительные пути импорта в виде сокращений двумя способами.

Во-первых, относительный путь может быть использован как сокращение в командной строке. Если вы работаете в каталоге, содержащем код, импортированный как "unicode", и хотите запустить тесты для "unicode/utf8", вы можете ввести "go test ./utf8" вместо того, чтобы указывать полный путь. Аналогично, в обратной ситуации "go test .." будет проверять "unicode" из каталога "unicode/utf8". Допускаются также относительные шаблоны, такие как "go test ./..." для проверки всех подкаталогов. Смотрите 'go help packages' для подробностей о синтаксисе шаблона.

Во-вторых, если вы компилируете программу Go не в рабочем пространстве, вы можете использовать относительный путь в операторе импорта в этой программе, чтобы ссылаться на соседний код, также не в рабочем пространстве. Это позволяет легко экспериментировать с небольшими многопакетными программами за пределами обычных рабочих пространств, но такие программы не могут быть установлены с помощью "go install" (нет рабочего пространства, в котором их можно установить), поэтому они пересобираются (rebuilt) с нуля при каждой сборке (go built). Чтобы избежать неоднозначности, программы Go не могут использовать относительные пути импорта в рабочем пространстве.


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


пятница, 5 июля 2019 г.

Вспомогательные темы инструмента go: протокол прокси модуля

go help goproxy

Команда go по умолчанию загружает модули из систем управления версиями напрямую, как это всегда бывает с go get. Переменная среды GOPROXY позволяет дополнительно контролировать источник загрузки. Если GOPROXY не установлен, является пустой строкой или строкой "direct", при загрузке используется прямое подключение по умолчанию к системам контроля версий. Отключение GOPROXY запрещает загрузку модулей из любого источника. В противном случае ожидается, что GOPROXY будет URL-адресом прокси модуля, и в этом случае команда go извлечет все модули из этого прокси. Независимо от источника модулей, загруженные модули должны соответствовать существующим записям в go.sum.

Прокси модуля Go - это любой веб-сервер, который может отвечать на запросы GET для URL-адресов заданной формы. Запросы не имеют параметров запроса, поэтому даже сайт, обслуживающий фиксированную файловую систему (включая file:/// URL), может быть прокси модуля.

GET-запросы, отправленные на прокси Go модуля:

GET $GOPROXY/<module>/@v/list возвращает список всех известных версий данного модуля, по одной на строку.

GET $GOPROXY/<module>/@v/<version>.info возвращает метаданные в формате JSON об этой версии данного модуля.

GET $GOPROXY/<module>/@v/<version>.mod возвращает файл go.mod для этой версии данного модуля.

GET $GOPROXY/<module>/@v/<version>.zip возвращает zip-архив для этой версии данного модуля.

Чтобы избежать проблем при обслуживании из файловых систем с учетом регистра, элементы <module> и <version> кодируются регистром, заменяя каждую заглавную букву восклицательным знаком, за которым следует соответствующая строчная буква: github.com/Azure кодируется как github.com/!azure.

Метаданные в формате JSON о данном модуле соответствуют этой структуре данных Go, которая может быть расширена в будущем:

type Info struct {
    Version string    // строка версии
    Time    time.Time // время комита
}

Zip-архив для конкретной версии данного модуля - это стандартный zip-файл, содержащий дерево файлов, соответствующее исходному коду модуля и связанным файлам. В архиве используются разделенные косой чертой пути, и каждый путь к файлу в архиве должен начинаться с <module>@<version>/, где модуль и версия подставляются напрямую, а не в регистре. Корень дерева файлов модулей соответствует префиксу <module>@<version>/ в архиве.

Даже при загрузке непосредственно из систем управления версиями команда go синтезирует явно info, mod и zip файлы и сохраняет их в своем локальном кэше, $GOPATH/pkg/mod/cache/download, так же, как если бы она загружала их непосредственно из прокси. Макет кэша такой же, как и у прокси-пространства URL, поэтому обслуживание $GOPATH/pkg/mod/cache/download в (или копирование его) https://example.com/proxy позволит другим пользователям получать доступ к этим версиям кэшированных модулей с GOPROXY=https://example.com/proxy.


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


четверг, 4 июля 2019 г.

Вспомогательные темы инструмента go: переменная среды GOPATH

go help gopath

Путь Go (Go path) используется для разрешения операторов импорта. Он реализован и задокументирован в пакете go/build.

Переменная окружения GOPATH перечисляет места для поиска кода Go. В Unix значение представляет собой строку, разделенную двоеточиями. В Windows значение представляет собой строку, разделенную точкой с запятой.

Если переменная среды не установлена, GOPATH по умолчанию использует подкаталог с именем "go" в домашнем каталоге пользователя ($HOME/go в Unix, %USERPROFILE%\go в Windows), если только этот каталог не содержит дистрибутив Go. Запустите "go env GOPATH", чтобы увидеть текущую GOPATH.

Смотрите этот пост, чтобы установить пользовательскую GOPATH.

Каждый каталог, указанный в GOPATH, должен иметь предписанную структуру:

Каталог src содержит исходный код. Путь ниже src определяет путь импорта или имя исполняемого файла.

В каталоге pkg хранятся установленные объекты пакета. Как и в дереве Go, каждая целевая пара операционной системы и архитектуры имеет свой собственный подкаталог pkg (pkg/GOOS_GOARCH).

Если DIR является каталогом, указанным в GOPATH, пакет с источником в DIR/src/foo/bar можно импортировать как "foo/bar", а его скомпилированная форма установлена в "DIR/pkg/GOOS_GOARCH/foo/bar.a".

Каталог bin содержит скомпилированные команды. Каждая команда названа для своего исходного каталога, но только конечный элемент, а не весь путь. То есть команда с источником в DIR/src/foo/quux устанавливается в DIR/bin/quux, а не в DIR/bin/foo/quux. Префикс "foo/" удален, так что вы можете добавить DIR/bin в PATH, чтобы получить доступ к установленным командам. Если установлена переменная среды GOBIN, команды устанавливаются в каталог, который она называет, а не в DIR/bin. GOBIN должен быть абсолютным путем.

Вот пример макета каталога:

GOPATH=/home/user/go

/home/user/go/
    src/
        foo/
            bar/               (go код в пакете bar)
                x.go
            quux/              (go код в пакете main)
                y.go
    bin/
        quux                   (установленная команда)
    pkg/
        linux_amd64/
            foo/
                bar.a          (установленный объект пакета)

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

См. этот пост для примера.


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


Вспомогательные темы инструмента go: файл go.mod

go help go.mod

Версия модуля определяется деревом исходных файлов с файлом go.mod в его корне. Когда команда go выполняется, она просматривает текущий каталог, а затем последующие родительские каталоги, чтобы найти go.mod, отмечающий корень основного (текущего) модуля.

Сам файл go.mod ориентирован на строки, с // комментариями, но без /* */ комментариев. Каждая строка содержит одну директиву, состоящую из глагола, за которым следуют аргументы. Например:

module my/thing
go 1.12
require other/thing v1.0.2
require new/thing/v2 v2.3.4
exclude old/thing v1.2.3
replace bad/thing v1.4.5 => good/thing v1.4.5

Глаголы:

module  чтобы определить путь модуля;
go      чтобы установить ожидаемую версию языка;
require требовать определенный модуль в данной версии 
        или новее;
exclude чтобы исключить конкретную версию модуля 
        из использования;
replace чтобы заменить версию модуля другой 
        версией модуля.

exclude и replace применяются только в go.mod основного модуля и игнорируются в зависимостях.

Ведущий глагол может быть выделен из соседних строк для создания блока, как в импорте Go:

require (
    new/thing v2.3.4
    old/thing v1.2.3
)

Файл go.mod предназначен как для непосредственного редактирования, так и для удобного обновления инструментами. Команда go mod edit может использоваться для анализа и редактирования файла go.mod из программ и инструментов.

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

module M

require (
        A v1
        B v1.0.0
        C v1.0.0
        D v1.2.3
        E dev
)

exclude D v1.2.3

Обновление переписывает неканонические идентификаторы версий в форму semver, поэтому версия v1 для A становится v1.0.0, а dev для E становится псевдо-версией для последнего коммита в ветви dev, возможно, v0.0.0-20180523231146-b3f5c0f6e5f1.

Обновление изменяет требования для соблюдения исключений, поэтому требование исключенной версии D v1.2.3 обновляется для использования следующей доступной версии D, возможно, версии D v1.2.2 или D v1.3.3.

Обновление устраняет избыточные или вводящие в заблуждение требования. Например, если для A v1.0.0 требуется B v1.2.0 и C v1.0.0, то требование go.mod для B v1.0.0 вводит в заблуждение (заменено потребностью A в v1.2.0) и требованием C v1.0.0 является избыточным (подразумевается потребность A в одной и той же версии), поэтому оба будут удалены. Если модуль M содержит пакеты, которые напрямую импортируют пакеты из B или C, то требования будут сохранены, но обновлены до фактических используемых версий.

Наконец, обновление переформатирует go.mod в каноническое форматирование, так что будущие механические изменения приведут к минимальным различиям.

Поскольку граф модуля определяет значение операторов импорта, любые команды, которые загружают пакеты, также используют и, следовательно, обновляют go.mod, включая go build, go get, go install, go list, go test, go mod graph, go mod tidy и go mod why.


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


Вспомогательные темы инструмента go: типы файлов

go help filetype

Команда go проверяет содержимое ограниченного набора файлов в каждом каталоге. Она определяет, какие файлы проверять, основываясь на расширении имени файла. Эти расширения:

.go
    Go исходные файлы.
.c, .h
    C исходные файлы.
    Если пакет использует cgo или SWIG, 
    они будут скомпилированы с OS-native компилятором 
    (обычно gcc); в противном случае 
    они будут вызывать ошибку.
.cc, .cpp, .cxx, .hh, .hpp, .hxx
    C++ исходные файлы. Полезно только с cgo или SWIG, 
    и всегда скомпилированы OS-native компилятором.
.m
    Objective-C исходные файлы. Полезно только с cgo,
    и всегда скомпилированы OS-native компилятором.
.s, .S
    Исходные файлы ассемблера.
    Если пакет использует cgo или SWIG, они будут 
    собраны с OS-native ассемблером (обычно gcc (sic)); 
    в противном случае они будут собраны с ассемблером Go.
.swig, .swigcxx
    SWIG файлы определения.
.syso
    Системные объектные файлы.

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

В версии Go 1.12 исходные файлы Go, не входящие в тест, также могут включать комментарий //go: binary-only-package, указывающий, что источники пакета включены только для документации и не должны использоваться для сборки бинарного файла пакета. Это позволяет распространять пакеты Go только в скомпилированном виде. Даже бинарные пакеты требуют точных блоков импорта, перечисляющих требуемые зависимости, так что эти зависимости могут быть предоставлены при связывании результирующей команды. Обратите внимание, что эту функцию планируется удалить после выпуска Go 1.12.


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


купить игрушку gopher

среда, 3 июля 2019 г.

Вспомогательные темы инструмента go: переменные среды окружения

go help environment

Команда go и инструменты, которые она вызывает, проверяют несколько различных переменных среды. Для многих из них вы можете увидеть значение по умолчанию в вашей системе, запустив 'go env NAME', где NAME - это имя переменной.

Переменные среды общего назначения:

GCCGO
    Команда gccgo для запуска 'go build -compiler=gccgo'.
GOARCH
    Архитектура или процессор, для которого компилируется 
    код. Примерами являются amd64, 386, arm, ppc64.
GOBIN
    Каталог, куда 'go install' установит команду.
GOCACHE
    Каталог, в котором команда go будет хранить 
    кешированную информацию для повторного
    использования в будущих сборках. 
GOFLAGS
    Разделенный пробелами список параметров -flag=value 
    для применения к go командам по умолчанию, 
    когда данный флаг известен текущей команде. 
    Флаги, перечисленные в командной строке применяются 
    после этого списка и, следовательно, переопределяют его.
GOOS
    Операционная система, для которой компилируется код.
    Примерами являются linux, darwin, windows, netbsd.
GOPATH
    Для более подробной информации: 'go help gopath'.
GOPROXY
    URL прокси Go модуля. См. 'go help goproxy'.
GORACE
    Опции для детектора гонки.
GOROOT
    Корень go дерева.
GOTMPDIR
    Каталог, куда команда go будет записывать
    временные исходные файлы, пакеты и бинарные файлы.

Каждая запись в списке GOFLAGS должна быть отдельным флагом. Поскольку записи разделены пробелами, значения флагов не должны содержать пробелов.

Переменные окружения для использования с cgo:

CC
    Команда, используемая для компиляции C кода.
CGO_ENABLED
    Поддерживается ли команда cgo. Либо 0, либо 1.
CGO_CFLAGS
    Флаги, которые cgo будет передавать компилятору 
    при компиляции С кода.
CGO_CFLAGS_ALLOW
    Регулярное выражение, указывающее дополнительные флаги, 
    чтобы разрешить им появиться в директивах 
    исходного кода #cgo CFLAGS.
    Не применяется к переменной среды CGO_CFLAGS.
CGO_CFLAGS_DISALLOW
    Регулярное выражение, указывающее флаги, 
    которые должны быть запрещены
    от появления в директивах #cgo CFLAGS исходного кода.
    Не применяется к переменной среды CGO_CFLAGS.
CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
    Как CGO_CFLAGS, CGO_CFLAGS_ALLOW и CGO_CFLAGS_DISALLOW,
    но для препроцессора C.
CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
    Как CGO_CFLAGS, CGO_CFLAGS_ALLOW и CGO_CFLAGS_DISALLOW,
    но для компилятора C++.
CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
    Как CGO_CFLAGS, CGO_CFLAGS_ALLOW и CGO_CFLAGS_DISALLOW,
    но для компилятора Фортрана.
CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
    Как CGO_CFLAGS, CGO_CFLAGS_ALLOW и CGO_CFLAGS_DISALLOW,
    но для компоновщика (linker).
CXX
    Команда, используемая для компиляции C++ кода.
PKG_CONFIG
    Путь для pkg-config интрумента.
AR
    Команда, используемая для управления 
    библиотечными архивами, когда
    идет сборка с помощью компилятора gccgo.
    По умолчанию равна 'ar'.

Архитектурно-зависимые переменные среды:

GOARM
    Для GOARCH=arm - архитектура ARM, 
    для которой нужно скомпилировать.
    Допустимые значения: 5, 6, 7.
GO386
    Для GOARCH=386 - набор команд с плавающей запятой.
    Допустимые значения: 387, sse2.
GOMIPS
    Для GOARCH=mips{,le}, использовать ли инструкции 
    с плавающей запятой.
    Допустимые значения: 
    hardfloat (по умолчанию), softfloat.
GOMIPS64
    Для GOARCH = mips64{,le}, использовать ли инструкции 
    с плавающей запятой.
    Допустимые значения: 
    hardfloat (по умолчанию), softfloat.

Переменные среды специального назначения:

GCCGOTOOLDIR
    Если установлено, где найти инструменты gccgo, 
    такие как cgo.
    Значение по умолчанию основано на том, 
    как был настроен gccgo.
GOROOT_FINAL
    Корень установленного дерева Go, когда он
    установлен в месте, отличном от того, где он собран.
    Имена файлов в следах стека (stack traces) 
    переписываются из GOROOT в GOROOT_FINAL.
GO_EXTLINK_ENABLED
    Должен ли компоновщик использовать режим внешней ссылки
    при использовании -linkmode=auto с кодом, 
    который использует cgo.
    Установите 0, чтобы отключить режим внешней ссылки, 
    1, чтобы включить его.
GIT_ALLOW_PROTOCOL
    Определено Git. Список схем, разделенных двоеточиями, 
    которые разрешено использовать с git fetch/clone.
    Если установлено, любая схема, не упомянутая явно, 
    будет считается небезопасной для 'go get'.

Дополнительная информация, доступная из 'go env', но не считываемая из среды:

GOEXE
    Суффикс имени исполняемого файла 
    (".exe" в Windows, "" в других системах).
GOHOSTARCH
    Архитектура (GOARCH) исполняемых файлов Go.
GOHOSTOS
    Операционная система (GOOS) исполняемых файлов Go.
GOMOD
    Абсолютный путь к go.mod основного модуля,
    или пустая строка, если не используются модули.
GOTOOLDIR
    Каталог, в котором установлены инструменты go 
    (compile, cover, doc и т.д.).


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


вторник, 2 июля 2019 г.

Вспомогательные темы инструмента go: кеширование сборки и тестирования

go help cache

Команда go кэширует выходные данные сборки (build output) для повторного использования в будущих сборках. Расположение по умолчанию для данных кэша - это подкаталог go-build в стандартном каталоге кэша пользователя для текущей операционной системы. Установка переменной среды GOCACHE переопределяет это значение по умолчанию, а запуск 'go env GOCACHE' печатает текущий каталог кэша.

Команда go периодически удаляет кэшированные данные, которые недавно не использовались. Запуск 'go clean -cache' удаляет все кэшированные данные.

Кэш сборки правильно учитывает изменения в исходных файлах Go, компиляторах, параметрах компилятора и т.д.: явная очистка кэша не обязательна при обычном использовании. Однако кэш сборки не обнаруживает изменений в библиотеках C, импортированных с помощью cgo. Если вы внесли изменения в библиотеки C в вашей системе, вам нужно будет явно очистить кеш или использовать флаг сборки -a (см. go help build), чтобы принудительно перестроить пакеты, которые зависят от обновленных библиотек C.

Команда go также кэширует успешные результаты тестирования пакета. Смотрите подробности в go help test. Запуск 'go clean -testcache' удаляет все кэшированные результаты теста (но не кэшированные результаты сборки).

Переменная среды GODEBUG может разрешить печать отладочной информации о состоянии кэша:

GODEBUG=gocacheverify=1 заставляет команду go обходить использование любых записей кэша, а вместо этого перестраивать все и проверять, соответствуют ли результаты существующим записям кэша.

GODEBUG=gocachehash=1 заставляет команду go печатать входные данные для всех хэшей содержимого, которые она использует для создания ключей поиска в кэше. Вывод объемный, но может быть полезен для отладки кеша.

GODEBUG=gocachetest=1 заставляет команду go выводить подробности своих решений о том, следует ли повторно использовать кэшированный результат теста.


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


Вспомогательные темы инструмента go: вызовы между Go и C

go help c

Существует два разных способа вызова между кодом Go и кодом C/C++.

Первым является инструмент cgo, который является частью дистрибутива Go. Информацию о том, как его использовать, смотрите в документации по cgo (go doc cmd/cgo).

Вторая - это программа SWIG, которая является общим инструментом для взаимодействия между языками. Для получения информации о SWIG см. http://swig.org. При запуске go build любой файл с расширением .swig будет передан SWIG. Любой файл с расширением .swigcxx будет передан SWIG с параметром -c++.

Когда используется cgo или SWIG, go build передает любые файлы .c, .m, .s или .S компилятору C, а любые файлы .cc, .cpp, .cxx компилятору C++. Переменные окружения CC или CXX могут быть установлены для определения, соответственно, используемого компилятора C или C++.


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


Вспомогательные темы инструмента go: режимы сборки

go help buildmode

Команды 'go build' и 'go install' принимают аргумент -buildmode, который указывает, какой тип объектного файла должен быть собран. В настоящее время поддерживаются следующие значения:


-buildmode=archive

Собрать перечисленные неосновные пакеты в .a файлы. Пакеты названные main игнорируются.


-buildmode=c-archive

Собрать указанный основной пакет, а также все пакеты, которые он импортирует, в C архивный файл. Единственными вызываемыми символами будут функции, которые экспортируются с использованием cgo //export комментариев. Требует чтобы ровно один основной (main) пакет был в переданном списке.


-buildmode=c-shared

Собрать указанный основной пакет, а также все пакеты, которые он импортирует, в C общую библиотеку (shared library). Единственными вызываемыми символами будут функции, которые экспортируются с использованием cgo //export комментариев. Требует чтобы ровно один основной (main) пакет был в переданном списке.


-buildmode=default

Перечисленные основные пакеты встроены в исполняемые файлы и перечисленные неосновные пакеты встроены в .a файлы (поведение по умолчанию).


-buildmode=shared

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


-buildmode=exe

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


-buildmode=pie

Собрать перечисленные основные пакеты и все, что они импортируют в позиционные независимые исполняемые файлы (PIE). Пакеты без имени main игнорируются.


-buildmode=plugin

Собрать перечисленные основные пакеты, а также все пакеты, которые они импортируют в плагин Go. Пакеты без имени main игнорируются.


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