Go Modules
External
Internal
Overview
A module is a collection of related packages that are stored together under the same filesystem tree, released, versioned and distributed together. Modules have been introduced in Go 1.11. Packages, a lower-level namespacing, encapsulation and code sharing mechanism, are published as part of modules.
A module is stored as a directory that contains a go.mod file and subdirectories that contain the source code for the module's packages. The go.mod stores metadata such as dependencies needed by the module, required Go version, etc. If any of the subdirectories contains a go.mod file, that subdirectory represents an embedded module.
Modules may be downloaded directly from version control repositories, or from module proxy servers.
Module Path (Module Name)
The module path and module name are used interchangeably. The module path is the published location from which the module can be downloaded by go tool, such as the module code’s repository location. For example, to download the module golang.org/x/tools, the go tool should go to the repository indicated by https://golang.org/x/tools. The process is described in Finding a Repository for a Module Path. The module path serves as a unique identifier, when combined with the module’s version number. The module path serves as import path prefix for all the packages in the module. Packages in the standard library do not have a module path prefix.
The module path consists of three parts: a repository root path, corresponding to the repository root directory, an optional module subdirectory, if the module is not stored directly in root, and a major version suffix (only for modules released at v2 or higher).
Example: github.com/apache/yunikorn-core, example.com/monorepo/something/mymodule/v2.
Older Go versions used to require that the first path component have a dot, but this is not enforced anymore.
The module path is specified when the module is initialized with go mod init <module-path>. For more details on go.mod initialization, see:
TODO: https://go.dev/doc/modules/managing-dependencies#naming_module
Package Import Path
For packages distributed as part of a module, the package's import path is the concatenation of the module's module path and the package's subdirectory within the module. The Multi-Package Module Layout example, provided below, contains packages with import paths example.com/generic/a and example.com/generic/other/b. It is possible to declare a module that contains a single package, with identical module path and package import path. Single-Package Module is such an example.
go.mod
Declaring Modules
This section assumes we want to write an example.com/generic module, which consists of two packages a and b. The a package lives in an a directory in the module root directory, which gives it a example.com/generic/a import path. The b package lives in an other/b directory in the module root directory, which gives it a example.com/generic/other/b import path. There is also a main package that provides the command line binary.
Initialize go.mod
Module Layout
This section needs refactoring after reading
- https://go.dev/doc/modules/managing-dependencies
- "Managing module source" https://go.dev/doc/modules/managing-source
- https://github.com/golang-standards/project-layout
- Think about the difference between project and module layout. Are there multi-module projects? Or usually a project is also a module?
The module root directory contains the go.mod file and the package directories.
Single-Package Module
Simple, one-package modules, where the module path and the the package import path are the same, are supported. In the example below, the single-package module contains just a single a package. The module path example.com/a is the same as the package import path. The filesystem layout is:
. ├─ go.mod └─ a.go
The source file declares inclusion in the a package:
package a
...
go.mod declares the module path and not much else:
module example.com/a
go 1.21.0
Multi-Package Module Layout
. ├── go.mod # Declares a module named example.com/generic │ ├── a │ └─ a.go │ ├── other │ └─ b │ └─ b.go │ └── generic-cmd.go # part of the "main" package
Publishing Modules
This section needs refactoring after reading "Publishing a module" https://go.dev/doc/modules/publishing
Also, reconcile with go install.
Consuming Modules
A package published as part of module can be consumed from another consumer module by importing it from the consumer module source code with the import keyword followed by the package import path, which includes the module path. In simple cases, the module and package import paths can be the same:
package main
import (
...
"example.com/a"
)
The go.mod of the consumer module must be updated with dependency tracking information. If the dependency is published and accessible via network, go.mod can be automatically updated with (after declaring imports appropriately in source files):
go mod tidy
However, for a local, unpublished modules whose code is available only on the local filesystem as a known relative path, the consumer module's go.mod can be edited manually as follows:
module example.com/consumer
[...]
require example.com/a v0.0.0-unpublished
replace example.com/a v0.0.0-unpublished => ../a // relative path from the consumer module directory to the dependency module directory
Importing Packages from Remote Modules
Importing Precompiled Packages
Importing Packages from GitHub
- Where does
go modstore the precompiled packages? - Same question for GoLand. Is the same place?
- What does actually happen there? Are we downloading sources or binaries?
Finding a Repository for a Module Path
Mapping Versions to Commits
Mapping Pseudo-versions to Commits
Downloads
The go command may download module source code and metadata directly from the repository that hosts it or from a proxy.
Direct Download
A direct download is when the go command downloads module source code and metadata directly from a version control repository. The alternative is a proxy download.
Proxy Download
Downloading a module from a proxy is usually faster.
Module Proxy Server
A web server that implements the GOPROXY protocol. The go command downloads version information, go.mod files, and module zip files from module proxies.
Managing Dependencies
In Go, dependencies are managed as modules that contain packages to be imported and used in your code. A well defined version of a module is uniquely identified by the module path, that can be used to actually download the module's source code, and a version.
TODO: https://go.dev/doc/modules/managing-dependencies
Developing and Publishing Modules
TODO: https://go.dev/doc/modules/developing
Module Version
Modules evolve by publishing new versions.
TODO:
- Module version numbering https://go.dev/doc/modules/version-numbers
- Module release and versioning workflow https://go.dev/doc/modules/release-workflow
- Developing a major version update: https://go.dev/doc/modules/major-version
Pseudo-version
A version that encodes a revision identifier (such as a Git commit hash) and a timestamp from a version control system. For example, v0.0.0-20191109021931-daa7c04131f5. Used for compatibility with non-module repositories and in other situations when a tagged version is not available.
Module Cache
The module cache is a directory where the go command stores downloaded module files. The entire snapshot of the source tree is downloaded. The module cache is distinct from the build cache, which contains compiled packages and other build artifacts. The default location of the module cache is ${GOPATH}/pkg/mod. The artifacts are stored in read-only mode to prevent accidental corruption.
To clean the module cache use go clean -modcache.
Private Modules
Also see:
Other Module Subjects
Configuring Modules in GoLand
TODO
- Process https://go.dev/ref/mod
- When your code imports packages contained in other modules, you manage those dependencies through your code's own module.
- A module can be defined locally without belonging to a repository. However, it's a good habit to organize your code as if you will publish it someday.
- To process: https://medium.com/rungo/anatomy-of-modules-in-go-c8274d215c16