Go.mod file: Difference between revisions

From wikinotes
(Created page with "= Example = <blockquote> <syntaxhighlight lang="go"> /* Unique identifier for project. * Distinguishes tools of the same name within `pkgs.go.dev` * Also directly or indirec...")
 
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
The <code>go.mod</code> file contains metadata about your project,<br>
and describes it's requirements (ex. go version, packages, etc)
= Documentation =
<blockquote>
{| class="wikitable"
|-
| <code>go.mod</code> 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
|-
|}
</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 =
<blockquote>
<blockquote>
Minimal/throwaway
<syntaxhighlight lang="go">
module foo
go 1.18
</syntaxhighlight>
More complete
<syntaxhighlight lang="go">
<syntaxhighlight lang="go">
/* Unique identifier for project.
/* Unique identifier for project.
Line 22: Line 60:
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Example -->
</blockquote><!-- Example -->
= Creation =
<blockquote>
<syntaxhighlight lang="bash">
# run inside go project's directory, with the desired project 'module-path' (see below)
go mod init example.com/x/myproject
</syntaxhighlight>
</blockquote><!-- Creation -->


= Components =
= Components =
<blockquote>
<blockquote>
== module path ==
== Go Version ==
<blockquote>
<blockquote>
Module paths are used both to locate, and uniquely identify packages.<br>
<syntaxhighlight lang="bash">
Downloading packages is normally performed by a lookup in go index,<br>
pacman -S go  # update your os's go version
but the actual src is hosted using a server/service of your choosing.
go mod edit -go=1.19
 
go mod tidy
Suffix indicating repository type
<syntaxhighlight lang="go">
# Repos supporting multiple protocols will try each in order.
# ex: https://, git://, git+ssh://
#
#
# 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><!-- Go Version -->


HTTP meta tag
== module path ==
<syntaxhighlight lang="html5">
<blockquote>
<!--
See [[golang module path]]
  Meta tags let you abstract the path of your src.
</blockquote><!-- module path -->
  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"
== Requirements ==
  VCS:          bzr, fossil, git, hg, svn
<blockquote>
  REPO-ROOT:    URL to repo-root (no VCS extension!)
=== Adding/Removing ===
-->
<blockquote>
<!--                            IMPORT-PREFIX  VCS  REPO-ROOT                -->
<syntaxhighlight lang="bash">
<meta name="go-import" content="example.org    git  https://code.org/r/p/exproj">
go get "rsc.io/quote" # add requirement to 'go.mod'
go mod tidy            # auto-discover missing requirements, add to 'go.mod'
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Adding/Removing -->


Hosted Services
=== Vendor/Patch ===
<blockquote>
<syntaxhighlight lang="go">
<syntaxhighlight lang="go">
# github.com
// go.mod
import "github.com/user/your_project"
import "github.com/user/your_project/sub/directory"


# launchpad.net
require (
import "launchpad.net/project"
    example.com/project-2
import "launchpad.net/project/series"
    // ...
import "launchpad.net/project/series/sub/directory"
)


# ...
replace example.com/project-2 => example.com/patched/project-2 v2.2.2-fixed
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- module path -->
</blockquote><!-- Vendor/Patch -->


=== Updating ===
<blockquote>
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# create ./go.mod (project settings, requirements, etc)
go list -m -u all                # list avail updates for all deps
# sample project: MyProject, github.com/MyProject, ...
go list -m -u example.com/module  # list avail updates for target dep
go mod init ${project}
</syntaxhighlight>
 
Dependencies can be determined automatically based on your imports.
<syntaxhighlight lang="go">
# foo.go
import "rsc.io/quote"
</syntaxhighlight>


<syntaxhighlight lang="bash">
go get example.com/module@latest  # update to latest
go mod tidy # find/download source for dependencies defined in src
go get example.com/module v1.1.1 # update/downgrade to target version
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Updating -->
</blockquote><!-- Requirements -->
</blockquote><!-- Components -->
</blockquote><!-- Components -->

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"