Go Modules

External

• https://go.dev/ref/mod
• https://go.dev/blog/using-go-modules

Internal

• Go Modularization
• Go Packages

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:

go.mod | Initialize go.mod

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

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

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 Packages from GitHub

• Where does go mod store 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

https://go.dev/ref/mod#vcs-find

Mapping Versions to Commits

https://go.dev/ref/mod#vcs-version

Mapping Pseudo-versions to Commits

https://go.dev/ref/mod#vcs-pseudo

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

https://go.dev/ref/mod#communicating-with-proxies

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

https://go.dev/ref/mod#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.

Other Module Subjects

Configuring Modules in GoLand

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