Go.mod file: Difference between revisions

From wikinotes
 
(5 intermediate revisions by the same user not shown)
Line 18: Line 18:
|}
|}
</blockquote><!-- Documentation -->
</blockquote><!-- Documentation -->
= Tutorials =
<blockquote>
{| class="wikitable"
|-
| DO: public go modules || https://www.digitalocean.com/community/tutorials/how-to-distribute-go-modules
|-
| DO: private, authenticated go modules || https://www.digitalocean.com/community/tutorials/how-to-use-a-private-go-module-in-your-own-project
|-
|}
</blockquote><!-- Tutorials -->


= Example =
= Example =
Line 54: Line 65:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# run inside go project's directory, with the desired project 'module-path' (see below)
# run inside go project's directory, with the desired project 'module-path' (see below)
go mod init github.com/myproject
go mod init example.com/x/myproject
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Creation -->
</blockquote><!-- Creation -->
Line 60: Line 71:
= Components =
= Components =
<blockquote>
<blockquote>
== module path ==
== Go Version ==
<blockquote>
Module paths are used both to locate, and uniquely identify packages.<br>
Downloading packages is normally performed by a lookup in go index,<br>
but the actual src is hosted using a server/service of your choosing.
 
=== URL suffix ===
<blockquote>
<blockquote>
Suffix indicating repository type
<syntaxhighlight lang="bash">
<syntaxhighlight lang="go">
pacman -S go  # update your os's go version
# Repos supporting multiple protocols will try each in order.
go mod edit -go=1.19
# ex: https://, git://, git+ssh://
go mod tidy
#
#
# Bazaar      .bzr
# Fossil      .fossil
# Git        .git
# Mercurial  .hg
# Subversion  .svn
 
import "example.com/path/to/repo.git"
import "example.com/path/to/repo.git/sub/directory"
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- url suffix -->
</blockquote><!-- Go Version -->


=== HTTP meta tag ===
== module path ==
<blockquote>
<blockquote>
HTTP meta tag
See [[golang module path]]
<syntaxhighlight lang="html5">
<!--
  Meta tags let you abstract the path of your src.
  You may use a import-prefix that has nothing to do with your URL.
 
  IMPORT-PREFIX: prefix of unique-identifier of package (not necessarily url) ex. "foo.com/x"
  VCS:          bzr, fossil, git, hg, svn
  REPO-ROOT:    URL to repo-root (no VCS extension!)
-->
<!--                            IMPORT-PREFIX  VCS  REPO-ROOT                -->
<meta name="go-import" content="example.org    git  https://code.org/r/p/exproj">
</syntaxhighlight>
</blockquote><!-- HTTP meta tag -->
 
=== Hosted services ===
<blockquote>
Hosted Services
<syntaxhighlight lang="go">
# github.com
import "github.com/user/your_project"
import "github.com/user/your_project/sub/directory"
 
# launchpad.net
import "launchpad.net/project"
import "launchpad.net/project/series"
import "launchpad.net/project/series/sub/directory"
 
# ...
</syntaxhighlight>
</blockquote><!-- Hosted services -->
 
=== Private modules ===
<blockquote>
{{ TODO |
verify you can host your own proxy/checksums }}
You may use private modules, but you'll need to set environment variables to keep them private.
 
<syntaxhighlight lang="bash">
# ignore checksum checks on these packages
GOPRIVATE=*.corp.example.com,rsc.io/private
 
# alternatively, define your own proxy with your own checksums
GOPROXY=proxy.example.com
GONOPROXY=none
</syntaxhighlight>
</blockquote><!-- Private modules -->
</blockquote><!-- module path -->
</blockquote><!-- module path -->


Latest revision as of 20:00, 7 August 2022

The go.mod file contains metadata about your project,
and describes it's requirements (ex. go version, packages, etc)

Documentation

go.mod ref https://go.dev/doc/modules/gomod-ref
go modules ref https://go.dev/ref/mod
go checksum database docs https://go.dev/ref/mod#checksum-database
go module index https://index.golang.org/index
go remote import paths https://pkg.go.dev/cmd/go#hdr-Remote_import_paths

Tutorials

DO: public go modules https://www.digitalocean.com/community/tutorials/how-to-distribute-go-modules
DO: private, authenticated go modules https://www.digitalocean.com/community/tutorials/how-to-use-a-private-go-module-in-your-own-project

Example

Minimal/throwaway 

module foo
go 1.18

More complete 

/* Unique identifier for project.
 * Distinguishes tools of the same name within `pkgs.go.dev`
 * Also directly or indirectly identifies the source-code's repo
 * (see module-path notes below)
 */
module example.com/x/yourproject

/* minimum supported go version */
go 1.18

/* project dependencies */
require (
    example.com/project-1 v1.1.1
    example.com/project-2 v2.2.2
)

/* replace content of module with a local directory */
replace example.com/project-2 => example.com/patched/project-2 v2.2.2-fixed

Creation

# run inside go project's directory, with the desired project 'module-path' (see below)
go mod init example.com/x/myproject

Components

Go Version

pacman -S go  # update your os's go version
go mod edit -go=1.19
go mod tidy

module path

See golang module path

Requirements

Adding/Removing

go get "rsc.io/quote"  # add requirement to 'go.mod'
go mod tidy            # auto-discover missing requirements, add to 'go.mod'

Vendor/Patch

// go.mod

require (
    example.com/project-2
    // ...
)

replace example.com/project-2 => example.com/patched/project-2 v2.2.2-fixed

Updating

go list -m -u all                 # list avail updates for all deps
go list -m -u example.com/module  # list avail updates for target dep

go get example.com/module@latest  # update to latest
go get example.com/module v1.1.1  # update/downgrade to target version
Retrieved from "http://willpittman.net:8080/index.php?title=Go.mod_file&oldid=31469"