Go Concepts - Runtime

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

Internal

Relevance

Go 1.6

Environment Variables

GOPATH

  • External: go help gopath.

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

GOPATH content lists directories on the local file system. 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/<imported-package-name> to them 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/foo/bar can be imported as "foo/bar" and has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.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/foo/blah is installed into DIR/bin/blah, not DIR/bin/foo/blah. The "foo/" 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

Vendoring is using local copies of external dependencies to satisfy imports of those dependencies. Code below a directory named "vendor" is importable only by code in the directory tree rooted at the parent of "vendor", and only using an import path that omits the prefix up to and including the vendor element. Code in vendor directories deeper in the source tree shadows code in higher directories. Within the subtree rooted at foo, an import of "crash/bang" resolves to "foo/vendor/crash/bang", not the top-level "crash/bang". Code in vendor directories is not subject to import path checking (see 'go help importpath').

When 'go get' checks out or updates a git repository, it now also updates submodules.

Vendor directories do not affect the placement of new repositories being checked out for the first time by 'go get': those are always placed in the main GOPATH, never in a vendor subtree.

GOBIN

If the GOBIN environment variable is set, commands are installed to the directory it names instead of DIR/bin. GOBIN must be an absolute path.

GOROOT

Compiling an Executable

TODO, more here: go build creates an executable only if among the packages being compiled there is a main package, and the package contains a main() function.