Go Environment Variables: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(50 intermediate revisions by the same user not shown)
Line 3: Line 3:
=Internal=
=Internal=
* [[Go_Development_and_Execution_Environment#Environment_Variables|Go Development and Execution Environment]]
* [[Go_Development_and_Execution_Environment#Environment_Variables|Go Development and Execution Environment]]
* [[go env|<tt>go env</tt>]]
=Overview=
The go command and the tools it invokes consult environment variables for configuration. To see or set the values for relevant environment variables, use <code>[[go env#Overview|go env]]</code>. The values set with <code>go env -w</code> are recorded in a Go environment configuration file stored in the per-user configuration directory, as reported by <code>os.UserConfigDir</code>. By default, the directory is <code>/Users/ovidiu/Library/Application Support/go/env</code> and can be displayed with:
<syntaxhighlight lang='bash'>
go env GOENV
</syntaxhighlight>
The directory does not exist unless <code>go env -w</code> is executed at least once. If no stored value for a specific environment variable exist in the Go environment configuration file, the Go runtime uses sensible defaults.
The location of the configuration file can be changed by setting the value of the <code>GOENV</code> environment variable.
If an environment variable is set the shell's environment, but not in the Go environment, the value is used correctly, and <code>go env</code> reports it.
If an environment variable is not set the shell's environment, but it set in the Go environment, the value is used correctly, and <code>go env</code> reports it.
If the same environment variable is set both in the shell's environment and in the Go environment, '''the shell environment value takes precedence'''.


=<tt>GOPATH</tt>=
=<tt>GOPATH</tt>=
<FONT COLOR=DARKKHAKI>The <code>GOPATH</code> environment variable defines the [[Go_Language_Modularization#Workspaces|workspace]] directory. Go tools assume that your code is under the path designated by <code>GOPATH</code>. Used to search for packages during compilation, when packages are being [[Go_Language_Modularization#Importing_Packages|imported]].</font>
<FONT COLOR=DARKKHAKI>The <code>GOPATH</code> environment variable defines the [[Go_Language_Modularization#Workspaces|workspace]] directory. Go tools assume that your code is under the path designated by <code>GOPATH</code>. Used to search for packages during compilation, when packages are being [[Go_Language_Modularization#Importing_Packages|imported]]. Also see {{Internal|Go_Language_Modularization#Relationship_between_Workspace_and_GOPATH|Relationship between Workspace and <tt>GOPATH</tt>}}</font>


To display the value, as seen by the Go runtime, execute:
To display the value, as seen by the Go runtime, execute:
Line 16: Line 31:
</syntaxhighlight>
</syntaxhighlight>


=<tt>GOROOT</tt>=
As of Go 1.16, the module-aware mode is turned on by default and the value of <code>GOPATH</code> is ignored while resolving package dependencies. In module-aware mode, <code>GOPATH</code> no longer defines the meaning of imports during a build, but it still stores downloaded dependencies in <code>${GOPATH}/pkg/mod</code> and installed commands in <code>${GOPATH}/bin</code>, unless <code>GOBIN</code> is set.
<font color=darkkhaki>Used to search for packages during compilation, when packages are being [[Go_Language_Modularization#Importing_Packages|imported]].</font>
 
To display the value, as seen by the Go runtime, execute:
For more details see: {{Internal|Go_Language_Modularization#Module-Aware_or_GOPATH_Mode|Module-Aware or GOPATH Mode}}
<syntaxhighlight lang='bash'>
go env GOROOT
</syntaxhighlight>
=<tt>GO111MODULE</tt>=
{{External|https://go.dev/ref/mod#mod-commands}}
Controls whether the [[Go_Tool#Overview|<code>go</code> tool]] runs in module-aware mode or GOPATH mode. May be "off", "on" or "auto".


For an example of building and installing an executable with <code>go install</code> see: {{Internal|Go_Tool#Build_and_Install_an_Executable_with_go_install|Build and Install an Executable with <tt>go_install</tt>}}




=<tt>GOPATH</tt>=
<font color=darkkhaki>


<tt>GOPATH</tt> is used by the compiler to locate ''source files'' and ''package objects'' for the [[Go_Language_Modularization#Overview|package]]s listed by the [[Go Keyword import#How_Packages_are_Resolved|import]] statements in source files being compiled.
<tt>GOPATH</tt> is used by the compiler to locate ''source files'' and ''package objects'' for the [[Go_Language_Modularization#Overview|package]]s listed by the [[Go Keyword import#How_Packages_are_Resolved|import]] statements in source files being compiled.
Line 45: Line 55:


* The bin directory holds compiled commands. Each command is named for its source directory, but only the final element, not the entire path.  That is, the command with source in <tt>DIR/src/x/blah</tt> is installed into <tt>DIR/bin/blah</tt>, not <tt>DIR/bin/x/blah</tt>.  The "<tt>x/</tt>" prefix is stripped so that you can add <tt>DIR/bin</tt> to your PATH to get at the installed commands.   
* The bin directory holds compiled commands. Each command is named for its source directory, but only the final element, not the entire path.  That is, the command with source in <tt>DIR/src/x/blah</tt> is installed into <tt>DIR/bin/blah</tt>, not <tt>DIR/bin/x/blah</tt>.  The "<tt>x/</tt>" prefix is stripped so that you can add <tt>DIR/bin</tt> to your PATH to get at the installed commands.   
==Relative Order==
Order in which root directories are listed in <tt>GOPATH</tt> matters. If two directories contain packages with the same name, the compiler will stop searching once it finds the first package that satisfies the import statement. The compiler first look into Go installation directory, then into the directories listed in GOPATH. The behavior corresponding to the package whose root directory exists in the Go installation, and then is listed first in the GOPATH list is used.


=="internal" directories==
=="internal" directories==
Line 55: Line 61:


==Vendor directories==
==Vendor directories==
==Organizatorium==
Validated, to integrate:
* GOPATH cannot have relative entries, all entries must be absolute directories.
</font>
==Relative Order==
The order in which root directories are listed in <code>GOPATH</code> matters. If two directories contain packages with the same name, the compiler will stop searching once it finds the first package that satisfies the import statement. The compiler first look into Go installation directory, then into the directories listed in <code>GOPATH</code>. <code>go install</code> handles multiple-entry <code>GOPATH</code> is a [[Go_Packages#GOPATH_Lists_Multiple_Directories|similar manner]].


==In-line Documentation==
==In-line Documentation==
 
<syntaxhighlight lang='bash'>
<pre>
go help gopath
go help gopath
</pre>
</syntaxhighlight >


=<tt>GOBIN</tt>=
=<tt>GOBIN</tt>=


If the GOBIN environment variable is set, commands are installed to the directory it names instead of <tt>DIR/bin</tt>. <tt>GOBIN</tt> must be an absolute path.
If the <code>GOBIN</code> environment variable is set, <code>[[Go_Tool#install|go install]]</code> installs binary executable artifacts into the directory designated by it, instead of <code>${GOPATH}/bin</code>. <code>GOBIN</code> must be an absolute path.
 
Also see: {{Internal|Go_Tool#Build_and_Install_an_Executable_with_go_install|Build and Install an Executable with <tt>go_install</tt>}}


=<tt>GOROOT</tt>=
=<tt>GOROOT</tt>=
<code>GOROOT</code> specifies the root directory of the local Go distribution, also known as the Go runtime installation directory. The directory contains all packages of the standard library under the <code>src</code> subdirectory . The typical value for <code>GOROOT</code> is <code>/usr/local/go</code>. The actual value can be obtained with:
<syntaxhighlight lang='bash'>
go env GOROOT
</syntaxhighlight>
<code>GOROOT</code> must be set at installation, Go runtime expects to find the variable in the environment, unless the runtime is installed in its default location <code>/usr/local/go</code>. The [[Go_Installation#Installation|installation procedure]] typically sets it.
=<tt>GO111MODULE</tt>=
Controls whether the [[Go_Tool#Overview|<code>go</code> tool]] runs in module-aware mode or GOPATH mode. Accepts the following values:
* "off": run in GOPATH mode and ignore <code>go.mod</code>.
* "on": run. in module-aware mode, even if no <code>go.mod</code>file is present.
* "auto": run in module-aware mode if a <code>go.mod</code> file is present.
For more details see: {{Internal|Go_Language_Modularization#Module-Aware_or_GOPATH_Mode|Module-Aware or <tt>GOPATH</tt> Mode}}
=<tt>GOOS</tt>=
"darwin" for MacOS.
=<tt>GOARCH</tt>=
"amd64"
=<tt>GOCACHE</tt>=
{{Internal|Go_Build_Cache#GOCACHE|Go Build Cache}}
=<tt>GOENV</tt>=
The location of the Go environment configuration file. Cannot be set using <code>go env -w</code>. Setting <code>GOENV=off</code> in the environment disables the use of the default configuration file.
=<tt>GOPROXY</tt>=
=<tt>GOPRIVATE</tt>, <tt>GONOPROXY</tt>, <tt>GONOSUMDB</tt>=
<syntaxhighlight lang='bash'>
go env -w GOPRIVATE="*.example.com"
</syntaxhighlight>
Comma-separated list of glob patterns in the syntax of Go's <code>path.Match</code> of module path prefixes that should be considered private, always be fetched directly or that should not be compared against the checksum database.
<span id='GOPRIVATE'></span><code>GOPRIVATE</code> carries the comma-separated list of glob patterns of module path prefixes that should be considered private. Acts as a default value for <code>GONOPROXY</code> and <code>GONOSUMDB</code>. <font color=darkkhaki>If <code>GONOPROXY</code> has a value then <code>GOPRIVATE</code> content is added to that value.</font>
<span id='GONOPROXY'></span><code>GONOPROXY</code> carries the comma-separated list of glob patterns of module path prefixes that should not be downloaded from a proxy. The <code>go</code> command will download matching modules from version control repositories where they are developed, regardless of <code>GOPROXY</code>.


The Go runtime installation directory. The compiler looks for packages that are imported at location referenced by the <tt>GOROOT</tt> and <tt>GOPATH</tt> variables.
<span id='GONOSUMDB'></span><code>GONOSUMDB</code> comma-separated list of glob patterns of module path prefixes that should not be checked using the public checksum database sum.golang.org.


<tt>GOROOT</tt> ''must'' be set at installation, Go runtime expects to find the variable in the environment, unless the runtime is installed in <tt>/usr/local/go</tt>.
Also see: {{Internal|Go_Modules#Private_Modules|Private Modules}}

Latest revision as of 01:24, 21 February 2024

External

Internal

Overview

The go command and the tools it invokes consult environment variables for configuration. To see or set the values for relevant environment variables, use go env. The values set with go env -w are recorded in a Go environment configuration file stored in the per-user configuration directory, as reported by os.UserConfigDir. By default, the directory is /Users/ovidiu/Library/Application Support/go/env and can be displayed with:

go env GOENV

The directory does not exist unless go env -w is executed at least once. If no stored value for a specific environment variable exist in the Go environment configuration file, the Go runtime uses sensible defaults.

The location of the configuration file can be changed by setting the value of the GOENV environment variable.

If an environment variable is set the shell's environment, but not in the Go environment, the value is used correctly, and go env reports it.

If an environment variable is not set the shell's environment, but it set in the Go environment, the value is used correctly, and go env reports it.

If the same environment variable is set both in the shell's environment and in the Go environment, the shell environment value takes precedence.

GOPATH

The GOPATH environment variable defines the workspace directory. Go tools assume that your code is under the path designated by GOPATH. Used to search for packages during compilation, when packages are being imported. Also see

Relationship between Workspace and GOPATH

To display the value, as seen by the Go runtime, execute:

go env GOPATH

For documentation on GOPATH, execute:

go help gopath

As of Go 1.16, the module-aware mode is turned on by default and the value of GOPATH is ignored while resolving package dependencies. In module-aware mode, GOPATH no longer defines the meaning of imports during a build, but it still stores downloaded dependencies in ${GOPATH}/pkg/mod and installed commands in ${GOPATH}/bin, unless GOBIN is set.

For more details see:

Module-Aware or GOPATH Mode

For an example of building and installing an executable with go install see:

Build and Install an Executable with go_install


GOPATH is used by the compiler to locate source files and package objects for the packages listed by the import statements in source files being compiled.

It must contain absolute paths.

GOPATH content lists directories on the local file system. GOPATH may contain multiple directories. On UNIX, the value is a colon-separated string. On Windows, the value is a semicolon-separated string. GOPATH must be set every time we need to get and build packages outside the standard Go tree.

The compiler loops over the values listed in GOPATH, in order, appends /src/<package-path-string-literal> to them, as declared in the import statement, and looks into the directories whose name are thus generated for source files that belong to the required packages. This is why it is important that the package and the directory containing the package sources have the same name: if they don't, the compilation fails to find the source file.

Each directory listed in GOPATH must have a prescribed structure:

  • The src directory holds source code. The path below src determines the import path or executable name.
  • The pkg directory holds installed package objects. As in the Go tree, each target operating system and architecture pair has its own subdirectory of pkg: pkg/GOOS_GOARCH.

If DIR is a directory listed in the GOPATH, a package with source in DIR/src/x/y can be imported as "x/y" and has its compiled form installed to "DIR/pkg/GOOS_GOARCH/x/y.a".

  • The bin directory holds compiled commands. Each command is named for its source directory, but only the final element, not the entire path. That is, the command with source in DIR/src/x/blah is installed into DIR/bin/blah, not DIR/bin/x/blah. The "x/" prefix is stripped so that you can add DIR/bin to your PATH to get at the installed commands.

"internal" directories

Code in or below a directory named "internal" is importable only by code in the directory tree rooted at the parent of "internal". For more details see https://golang.org/s/go14internal.

Vendor directories

Organizatorium

Validated, to integrate:

  • GOPATH cannot have relative entries, all entries must be absolute directories.

Relative Order

The order in which root directories are listed in GOPATH matters. If two directories contain packages with the same name, the compiler will stop searching once it finds the first package that satisfies the import statement. The compiler first look into Go installation directory, then into the directories listed in GOPATH. go install handles multiple-entry GOPATH is a similar manner.

In-line Documentation

go help gopath

GOBIN

If the GOBIN environment variable is set, go install installs binary executable artifacts into the directory designated by it, instead of ${GOPATH}/bin. GOBIN must be an absolute path.

Also see:

Build and Install an Executable with go_install

GOROOT

GOROOT specifies the root directory of the local Go distribution, also known as the Go runtime installation directory. The directory contains all packages of the standard library under the src subdirectory . The typical value for GOROOT is /usr/local/go. The actual value can be obtained with:

go env GOROOT

GOROOT must be set at installation, Go runtime expects to find the variable in the environment, unless the runtime is installed in its default location /usr/local/go. The installation procedure typically sets it.

GO111MODULE

Controls whether the go tool runs in module-aware mode or GOPATH mode. Accepts the following values:

  • "off": run in GOPATH mode and ignore go.mod.
  • "on": run. in module-aware mode, even if no go.modfile is present.
  • "auto": run in module-aware mode if a go.mod file is present.

For more details see:

Module-Aware or GOPATH Mode

GOOS

"darwin" for MacOS.

GOARCH

"amd64"

GOCACHE

Go Build Cache

GOENV

The location of the Go environment configuration file. Cannot be set using go env -w. Setting GOENV=off in the environment disables the use of the default configuration file.

GOPROXY

GOPRIVATE, GONOPROXY, GONOSUMDB

go env -w GOPRIVATE="*.example.com"

Comma-separated list of glob patterns in the syntax of Go's path.Match of module path prefixes that should be considered private, always be fetched directly or that should not be compared against the checksum database.

GOPRIVATE carries the comma-separated list of glob patterns of module path prefixes that should be considered private. Acts as a default value for GONOPROXY and GONOSUMDB. If GONOPROXY has a value then GOPRIVATE content is added to that value.

GONOPROXY carries the comma-separated list of glob patterns of module path prefixes that should not be downloaded from a proxy. The go command will download matching modules from version control repositories where they are developed, regardless of GOPROXY.

GONOSUMDB comma-separated list of glob patterns of module path prefixes that should not be checked using the public checksum database sum.golang.org.

Also see:

Private Modules