_content/doc: fix module and tutorial bugs and clean up flow
For golang/go#44241
- Fix issues 2, 3, 8, 16, 17, 18 from golang/go#44241
Other changes in multiple topics:
- In markdown, replace HTML anchor tags with {#anchor} tags.
- In a few places, add content to clarify that module path must
be a location from which the module can be downloaded.
- Where it was missing, add example.com domain to example module
paths. Hopefully, this will reinforce the idea that the module
path should typically include a domain. Docs will use
something that looks like a domain name for module path.
- Add more cross-references from tutorial to references for
packages and commands.
- Rewrite a few links so that they include the topic title,
rather than simply inline text. Left those links whose
destinations are references -- the item's name seems to
suggest that a reference is at the destination.
- Remove domain name from golang.org doc links, leaving root
directory. Such as /cmd/go/* or /doc/modules/*
- Add path up to root for all links in the same domain.
Some were linking by file name only.
- Change standard library links from golang.org to pkg.go.dev.
Changes in the module tutorial:
- Add text to help clarify that there should be a hello and
greetings directory as siblings in their directory hierarchy.
Some users thought one should be subordinate to the other.
- Where needed, reorder steps so that `go mod init` is run before
code is added. This is intended to reinforce the importance of
the module's presence.
- In require/replace steps, have the user use `go mod edit`
rather than editing the go.mod file in an editor. The tools
are more likely to yield a functioning result.
- Where possible/appropriate, change module directive link
destinations from "Modules reference" to go.mod reference.
- Change "run the code" steps so that they all use `go run .`
rather than `go build` or `go run <filename>`. This removes
the impedance of explanation and more commands, while
moving the explanation of `go build` and `go install` to
a separate topic where they share a clearer context.
- Add a "Conclusion" topic with a few links. The tutorial ended
rather abruptly before.
- Minor edits to remove some redundant language.
Change-Id: I93055035d73c362ba73edea458fc53bc45e66512
Reviewed-on: https://go-review.googlesource.com/c/website/+/297531
Trust: Steve Traut <straut@google.com>
Run-TryBot: Steve Traut <straut@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>
diff --git a/_content/doc/code.html b/_content/doc/code.html
index a1b9bd2..99a1729 100644
--- a/_content/doc/code.html
+++ b/_content/doc/code.html
@@ -78,7 +78,7 @@
$ cat go.mod
module example.com/user/hello
-go 1.14
+go 1.16
$
</pre>
@@ -323,16 +323,17 @@
</pre>
<p>
-When you run commands like <code>go install</code>, <code>go build</code>, or
-<code>go run</code>, the <code>go</code> command will automatically download the
-remote module and record its version in your <code>go.mod</code> file:
+Now that you have a dependency on an external module, you need to download that
+module and record its version in your <code>go.mod</code> file. The <code>go
+mod tidy</code> command adds missing module requirements for imported packages
+and removes requirements on modules that aren't used anymore.
</p>
<pre>
-$ go install example.com/user/hello
+$ go mod tidy
go: finding module for package github.com/google/go-cmp/cmp
-go: downloading github.com/google/go-cmp v0.4.0
-go: found github.com/google/go-cmp/cmp in github.com/google/go-cmp v0.4.0
+go: found github.com/google/go-cmp/cmp in github.com/google/go-cmp v0.5.4
+$ go install example.com/user/hello
$ hello
Hello, Go!
string(
@@ -342,9 +343,9 @@
$ cat go.mod
module example.com/user/hello
-go 1.14
+go 1.16
-<b>require github.com/google/go-cmp v0.4.0</b>
+<b>require github.com/google/go-cmp v0.5.4</b>
$
</pre>
diff --git a/_content/doc/modules/developing.md b/_content/doc/modules/developing.md
index bcaabfe..c1cbe4c 100644
--- a/_content/doc/modules/developing.md
+++ b/_content/doc/modules/developing.md
@@ -25,7 +25,7 @@
[Versioning](#versioning).
* **Go tools** that make it easier for other developers to manage
dependencies, including getting your module's source, upgrading, and so on.
- See [Managing dependencies](managing-dependencies).
+ See [Managing dependencies](/doc/modules/managing-dependencies).
**See also**
@@ -33,10 +33,9 @@
isn't the topic for you. Instead, see [Managing
dependencies](managing-dependencies).
* For a tutorial that includes a few module development basics, see
- [Tutorial: Create a Go module](https://golang.org/doc/tutorial/create-module).
+ [Tutorial: Create a Go module](/doc/tutorial/create-module).
-<a id="workflow" ></a>
-## Workflow for developing and publishing modules
+## Workflow for developing and publishing modules {#workflow}
When you want to publish your modules for others, you adopt a few conventions to
make using those modules easier.
@@ -51,8 +50,7 @@
1. Over time, revise the module with versions that use a version numbering
convention that signals each version's stability and backward compatibility.
-<a id="design" ></a>
-## Design and development
+## Design and development {#design}
Your module will be easier for developers to find and use if the functions and
packages in it form a coherent whole. When you're designing a module's public
@@ -70,8 +68,7 @@
information, see "Coding against an unpublished module" in [Module release and
versioning workflow](release-workflow#unpublished).
-<a id="decentralized" ></a>
-## Decentralized publishing
+## Decentralized publishing {#decentralized}
In Go, you publish your module by tagging its code in your repository to make it
available for other developers to use. You don't need to push your module to a
@@ -88,13 +85,12 @@
locate and download the module for its users.
For more about source and publishing conventions and best practices, see
-[Managing module source](managing-source).
+[Managing module source](/doc/modules/managing-source).
For step-by-step instructions on publishing a module, see [Publishing a
module](publishing).
-<a id="discovery" ></a>
-## Package discovery
+## Package discovery {#discovery}
After you've published your module and someone has fetched it with Go tools, it
will become visible on the Go package discovery site at
@@ -107,8 +103,7 @@
For more about how developers find and use modules, see [Managing
dependencies](managing-dependencies).
-<a id="versioning" ></a>
-## Versioning
+## Versioning {#versioning}
As you revise and improve your module over time, you assign version numbers
(based on the semantic versioning model) designed to signal each version's
@@ -121,4 +116,4 @@
update](major-version).
For more about how you use the semantic versioning model for Go modules, see
-[Module version numbering](version-numbers).
+[Module version numbering](/doc/modules/version-numbers).
diff --git a/_content/doc/modules/gomod-ref.md b/_content/doc/modules/gomod-ref.md
index bdbe853..7a7c2b7 100644
--- a/_content/doc/modules/gomod-ref.md
+++ b/_content/doc/modules/gomod-ref.md
@@ -8,9 +8,12 @@
These properties include:
-* The current module's **module path**. This serves as both its location and
- unique identifier, when combined with its version number. It is also the
- prefix of the package path for all packages in the module.
+* The current module's **module path**. This should be a location from which
+the module can be down loaded by Go tools, such as the module code's
+repository location. This serves as a unique identifier, when combined
+with the module's version number. It is also the prefix of the package path for
+all packages in the module. For more about how Go locates the module, see the
+<a href="/ref/mod#vcs-find">Go Modules Reference</a>.
* The minimum **version of Go** required by the current module.
* A list of minimum versions of other **modules required** by the current module.
* Instructions, optionally, to **replace** a required module with another
@@ -18,9 +21,8 @@
a required module.
Go generates a go.mod file when you run the [`go mod init`
-command](https://golang.org/cmd/go/#hdr-Initialize_new_module_in_current_directory).
-The following example creates a go.mod file, setting the module's module path to
-example.com/mymodule:
+command](/ref/mod#go-mod-init). The following example creates a go.mod file,
+setting the module's module path to example.com/mymodule:
```
$ go mod init example.com/mymodule
@@ -28,26 +30,22 @@
Use `go` commands to manage dependencies. The commands ensure that the
requirements described in your go.mod file remain consistent and the content of
-your go.mod file is valid. These commands include the [`go
-get`](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
-and [`go mod
-tidy`](https://golang.org/cmd/go/#hdr-Add_missing_and_remove_unused_modules) and
-[`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts)
+your go.mod file is valid. These commands include the [`go get`](/ref/mod#go-get)
+and [`go mod tidy`](/ref/mod#go-mod-tidy) and [`go mod edit`](/ref/mod#go-mod-edit)
commands.
-For reference on `go` commands, see [Command go](https://golang.org/cmd/go/).
+For reference on `go` commands, see [Command go](/cmd/go/).
You can get help from the command line by typing `go help` _command-name_, as
with `go help mod tidy`.
**See also**
* Go tools make changes to your go.mod file as you use them to manage
- dependencies. For more, see [Managing dependencies](managing-dependencies).
+ dependencies. For more, see [Managing dependencies](/doc/modules/managing-dependencies).
* For more details and constraints related to go.mod files, see the [Go modules
- reference](https://golang.org/ref/mod#go-mod-file).
+ reference](/ref/mod#go-mod-file).
-## Example
+## Example {#example}
A go.mod file includes directives shown in the following example. These are
described in this topic.
@@ -67,24 +65,28 @@
exclude example.com/thismodule v1.3.0
```
-<a id="module" ></a>
-## module
+## module {#module}
-Declares the module's module path, the module's unique identifier when combined
-with the module version.
+Declares the module's module path, which is the module's unique identifier
+(when combined with the module version number). This becomes the import prefix
+for all packages the module contains.
-### Syntax
+### Syntax {#module-syntax}
<pre>module <var>module-path</var></pre>
<dl>
<dt>module-path</dt>
- <dd>The module's module path, usually a concatenation of the module source's
- repository domain and the module name. For module versions v2 and later,
- this value must end with the major version number, such as <code>/v2</code>.</dd>
+ <dd>The module's module path, usually the repository location from which
+ the module can be downloaded by Go tools. For module versions v2 and
+ later, this value must end with the major version number, such as
+ <code>/v2</code>.</dd>
</dl>
-### Examples
+### Examples {#module-examples}
+
+The following examples substitute `example.com` for a repository domain from
+which the module could be downloaded.
* Module declaration for a v0 or v1 module:
```
@@ -95,18 +97,35 @@
module example.com/mymodule/v2
```
-### Notes
+### Notes {#module-notes}
-The module path, together with the module's version number, is a unique
-identifier for the module. Go uses the `module` directive's value to locate the
-module source when building other modules that depend on it.
+The module path should be a path from which Go tools can download the module
+source. In practice, this is typically the module source's repository domain
+and path to the module code within the repository. The <code>go</code> command
+relies on this form when downloading module versions to resolve dependencies
+on the module user's behalf.
-<a id="go" ></a>
-## go
+Even if you're not at first intending to make your module available for use
+from other code, using its repository path is a best practice that will help
+you avoid having to rename the module if you publish it later.
+
+If at first you don't know the module's eventual repository location, consider
+temporarily using a safe substitute, such as the name of a domain you own or
+`example.com`, along with a path following from the module's name or source
+directory.
+
+For example, if you're developing in a `stringtools` directory, your temporary
+module path might be `example.com/stringtools`, as in the following example:
+
+```
+go mod init example.com/stringtools
+```
+
+## go {#go}
Specifies the minimum Go version required by the module.
-### Syntax
+### Syntax {#go-syntax}
<pre>go <var>minimum-go-version</var></pre>
@@ -115,28 +134,27 @@
<dd>The minimum version of Go required to compile packages in this module.</dd>
</dl>
-### Examples
+### Examples {#go-examples}
* Module must run on Go version 1.14 or later:
```
go 1.14
```
-### Notes
+### Notes {#go-notes}
The version number also controls some module-related features in the `go`
command. For example, if the vendor directory is present, that directory will be
used automatically if the version number is 1.14 or higher.
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
-<a id="require" ></a>
-## require
+## require {#require}
Declares a module as dependency required by the current module, specifying the
minimum version of the module required.
-### Syntax
+### Syntax {#require-syntax}
<pre>require <var>module-path</var> <var>module-version</var></pre>
@@ -151,7 +169,7 @@
v0.0.0-20200921210052-fa0125251cc4.</dd>
</dl>
-### Examples
+### Examples {#require-examples}
* Requiring a released version v1.2.3:
```
@@ -163,7 +181,7 @@
require example.com/othermodule v0.0.0-20200921210052-fa0125251cc4
```
-### Notes
+### Notes {#require-notes}
When you run a `go` command such as `go get`, Go inserts `require` directives
for each module containing imported packages. When a module isn't yet tagged in
@@ -173,24 +191,23 @@
You can have Go require a module from a location other than its repository by
using the [`replace` directive](#replace).
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
For more about managing dependencies, see the following:
-* [Adding a dependency](managing-dependencies#adding_dependency)
-* [Getting a specific dependency version](managing-dependencies#getting_version)
-* [Discovering available updates](managing-dependencies#discovering_updates)
-* [Upgrading or downgrading a dependency](managing-dependencies#upgrading)
-* [Synchronizing your code's dependencies](managing-dependencies#synchronizing)
+* [Adding a dependency](/doc/modules/managing-dependencies#adding_dependency)
+* [Getting a specific dependency version](/doc/modules/managing-dependencies#getting_version)
+* [Discovering available updates](/doc/modules/managing-dependencies#discovering_updates)
+* [Upgrading or downgrading a dependency](/doc/modules/managing-dependencies#upgrading)
+* [Synchronizing your code's dependencies](/doc/modules/managing-dependencies#synchronizing)
-<a id="replace" ></a>
-## replace
+## replace {#replace}
Replaces the content of a module at a specific version (or all versions) with
another module version or with a local directory. Go tools will use the
replacement path when resolving the dependency.
-### Syntax
+### Syntax {#replace-syntax}
<pre>replace <var>module-path</var> <var>[module-version]</var> => <var>replacement-path</var> <var>[replacement-version]</var></pre>
@@ -212,7 +229,7 @@
be specified if <em>replacement-path</em> is a module path (not a local directory).</dd>
</dl>
-### Examples
+### Examples {#replace-examples}
* Replacing with a fork of the module repository
@@ -229,7 +246,7 @@
for packages in the module you're replacing.
For more on using a forked copy of module code, see [Requiring external module
- code from your own repository fork](managing-dependencies#external_fork).
+ code from your own repository fork](/doc/modules/managing-dependencies#external_fork).
* Replacing with a different version number
@@ -270,9 +287,9 @@
```
For more on using a local copy of module code, see [Requiring module code in a
- local directory](managing-dependencies#local_directory).
+ local directory](/doc/modules/managing-dependencies#local_directory).
-### Notes
+### Notes {#replace-notes}
Use the `replace` directive to temporarily substitute a module path value with
another value when you want Go to use the other path to find the module's
@@ -282,7 +299,7 @@
Use the `exclude` and `replace` directives to control build-time dependency
resolution when building the current module. These directives are ignored in
-modules that are dependencies of the current module.
+modules that depend on the current module.
The `replace` directive can be useful in situations such as the following:
@@ -294,31 +311,31 @@
For more on replacing a required module, including using Go tools to make the
change, see:
-* [Requiring external module code from your own repository fork](managing-dependencies#external_fork)
-* [Requiring module code in a local directory](managing-dependencies#local_directory)
+* [Requiring external module code from your own repository
+fork](/doc/modules/managing-dependencies#external_fork)
+* [Requiring module code in a local
+directory](/doc/modules/managing-dependencies#local_directory)
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version
+numbering](/doc/modules/version-numbers).
-<a id="exclude" ></a>
-## exclude
+## exclude {#exclude}
Specifies a module or module version to exclude from the current module's
dependency graph.
-### Syntax
+### Syntax {#exclude-syntax}
-<pre>exclude <var>module-path</var> <var>[module-version]</var></pre>
+<pre>exclude <var>module-path</var> <var>module-version</var></pre>
<dl>
<dt>module-path</dt>
<dd>The module path of the module to exclude.</dd>
<dt>module-version</dt>
- <dd>Optional. A specific version to exclude. If this version number is
- omitted, all versions of the module are replaced with the content on the
- right side of the arrow.</dd>
+ <dd>The specific version to exclude.</dd>
</dl>
-### Example
+### Example {#exclude-example}
* Exclude example.com/theirmodule version v1.3.0
@@ -326,7 +343,7 @@
exclude example.com/theirmodule v1.3.0
```
-### Notes
+### Notes {#exclude-notes}
Use the `exclude` directive to exclude a specific version of a module that is
indirectly required but can't be loaded for some reason. For example, you might
@@ -336,12 +353,11 @@
resolution when building the current module (the main module you're building).
These directives are ignored in modules that depend on the current module.
-You can use the [`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts) command
+You can use the [`go mod edit`](/ref/mod#go-mod-edit) command
to exclude a module, as in the followng example.
```
go mod edit -exclude=example.com/theirmodule@v1.3.0
```
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
diff --git a/_content/doc/modules/major-version.md b/_content/doc/modules/major-version.md
index fe1555b..9143634 100644
--- a/_content/doc/modules/major-version.md
+++ b/_content/doc/modules/major-version.md
@@ -13,7 +13,7 @@
understand the level of risk a release represents to their own code. In other
words, when preparing a release, be sure that its version number accurately
reflects the nature of the changes since the preceding release. For more on
-version numbers, see [Module version numbering](version-numbers).
+version numbers, see [Module version numbering](/doc/modules/version-numbers).
**See also**
@@ -22,7 +22,7 @@
* For an end-to-end view, see [Module release and versioning
workflow](release-workflow).
-## Considerations for a major version update
+## Considerations for a major version update {#considerations}
You should only update to a new major version when it's absolutely necessary.
A major version update represents significant churn for both you and your
@@ -52,7 +52,7 @@
wherever code imports packages from the new module. Your module's users must
also update their import paths if they want to upgrade to the new major version.
-## Branching for a major release
+## Branching for a major release {#branching}
The most straightforward approach to handling source when preparing to develop a
new major version is to branch the repository at the latest version of the
@@ -85,4 +85,4 @@
* Old import statement: `import "example.com/mymodule/package1"`
* New import statement: `import "example.com/mymodule/v2/package1"`
-For publishing steps, see [Publishing a module](publishing).
+For publishing steps, see [Publishing a module](/doc/modules/publishing).
diff --git a/_content/doc/modules/managing-dependencies.md b/_content/doc/modules/managing-dependencies.md
index 671ec5a..1385a6f 100644
--- a/_content/doc/modules/managing-dependencies.md
+++ b/_content/doc/modules/managing-dependencies.md
@@ -16,24 +16,23 @@
**See also**
* If you're new to working with dependencies as modules, take a look at the
- [Getting started tutorial](https://golang.org/doc/tutorial/getting-started)
+ [Getting started tutorial](/doc/tutorial/getting-started)
for a brief introduction.
* Using the `go` command to manage dependencies helps ensure that your
requirements remain consistent and the content of your go.mod file is valid.
- For reference on the commands, see [Command go](https://golang.org/cmd/go/).
+ For reference on the commands, see [Command go](/cmd/go/).
You can also get help from the command line by typing `go help`
_command-name_, as with `go help mod tidy`.
* Go commands you use to make dependency changes edit your go.mod file. For
- more about the contents of the file, see [go.mod file reference](gomod-ref).
+ more about the contents of the file, see [go.mod file reference](/doc/modules/gomod-ref).
* Making your editor or IDE aware of Go modules can make the work of managing
them easier. For more on editors that support Go, see [Editor plugins and
- IDEs](https://golang.org/doc/editors.html).
+ IDEs](/doc/editors.html).
* This topic doesn't describe how to develop, publish, and version modules for
others to use. For more on that, see [Developing and publishing
modules](developing).
-<a id="workflow" ></a>
-## Workflow for using and managing dependencies
+## Workflow for using and managing dependencies {#workflow}
You can get and use useful packages with Go tools. On
[pkg.go.dev](https://pkg.go.dev), you can search for packages you might find
@@ -46,13 +45,12 @@
1. [Locate useful packages](#locating_packages) on [pkg.go.dev](https://pkg.go.dev).
1. [Import the packages](#locating_packages) you want in your code.
1. Add your code to a module for dependency tracking (if it isn't in a module
- already). See [Enabling dependencies tracking](#enable_tracking)
+ already). See [Enabling dependency tracking](#enable_tracking)
1. [Add external packages as dependencies](#adding_dependency) so you can manage
them.
1. [Upgrade or downgrade dependency versions](#upgrading) as needed over time.
-<a id="modules" ></a>
-## Managing dependencies as modules
+## Managing dependencies as modules {#modules}
In Go, you manage dependencies as modules that contain the packages you import.
This process is supported by:
@@ -61,7 +59,7 @@
Developers make their modules available for other developers to use from
their own repository and publish with a version number.
* A **package search engine** and documentation browser (pkg.go.dev) at which
- you can find modules. See [Package discovery](developing#discovery).
+ you can find modules. See [Locating and importing useful packages](#locating_packages).
* A module **version numbering convention** to help you understand a module's
stability and backward compatibility guarantees. See [Module version
numbering](version-numbers).
@@ -69,8 +67,7 @@
getting a module's source, upgrading, and so on. See sections of this topic
for more.
-<a id="locating_packages" ></a>
-## Locating and importing useful packages
+## Locating and importing useful packages {#locating_packages}
You can search [pkg.go.dev](https://pkg.go.dev) to find packages with functions
you might find useful.
@@ -88,15 +85,14 @@
package's code to compile with. For more, see [Enabling dependency tracking in
your code](#enable_tracking) and [Adding a dependency](#adding_dependency).
-<a id="enable_tracking" ></a>
-## Enabling dependency tracking in your code
+## Enabling dependency tracking in your code {#enable_tracking}
To track and manage the dependencies you add, you begin by putting your code in
its own module. This creates a go.mod file at the root of your source tree.
Dependencies you add will be listed in that file.
To add your code to its own module, use the [`go mod init`
-command](https://golang.org/cmd/go/#hdr-Initialize_new_module_in_current_directory).
+command](/ref/mod#go-mod-init).
For example, from the command line, change to your code's root directory, then
run the command as in the following example:
@@ -104,6 +100,13 @@
$ go mod init example.com/mymodule
```
+The `go mod init` command's argument is your module's module path. If possible,
+the module path should be the repository location of your source code. If at
+first you don't know the module's eventual repository location, consider
+temporarily using a safe substitute, such as the name of a domain you own or
+`example.com`, along with a path following from the module's name or source
+directory.
+
As you use Go tools to manage dependencies, the tools update the go.mod file so
that it maintains a current list of your dependencies.
@@ -114,21 +117,20 @@
Include the go.mod and go.sum files in your repository with your code.
-See the [go.mod reference](gomod-ref) for more.
+See the [go.mod reference](/doc/modules/gomod-ref) for more.
-<a id="adding_dependency" ></a>
-## Adding a dependency
+## Adding a dependency {#adding_dependency}
Once you're importing packages from a published module, you can add that module
to manage as a dependency by using the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them).
+command](/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them).
The command does the following:
* If needed, it adds `require` directives to your go.mod file for modules
needed to build packages named on the command line. A `require` directive
tracks the minimum version of a module that your module depends on. See the
- [go.mod reference](gomod-ref) for more.
+ [go.mod reference](/doc/modules/gomod-ref) for more.
* If needed, it downloads module source code so you can compile packages that
depend on them. It can download modules from a module proxy like
proxy.golang.org or directly from version control repositories. The source
@@ -159,8 +161,7 @@
-- Go tools will present a security error. This authentication check protects
you from modules that might have been tampered with.
-<a id="getting_version" ></a>
-## Getting a specific dependency version
+## Getting a specific dependency version {#getting_version}
You can get a specific version of a dependency module by specifying its version
in the `go get` command. The command updates the `require` directive in your
@@ -174,7 +175,7 @@
* You want to upgrade or downgrade a module you're already requiring.
Here are examples for using the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them):
+command](/ref/mod#go-get):
* To get a specific numbered version, append the module path with an @ sign
followed by the version you want:
@@ -190,15 +191,14 @@
```
The following go.mod file `require` directive example (see the [go.mod
-reference](gomod-ref) for more) illustrates how to require a specific version
+reference]/doc/modules/gomod-ref) for more) illustrates how to require a specific version
number:
```
require example.com/theirmodule v1.3.4
```
-<a id="discovering_updates" ></a>
-## Discovering available updates
+## Discovering available updates {#discovering_updates}
You can check to see if there are newer versions of dependencies you're already
using in your current module. Use the `go list` command to display a list of
@@ -206,8 +206,7 @@
module. Once you've discovered available upgrades, you can try them out with your
code to decide whether or not to upgrade to new versions.
-For more about the `go list` command, see the [`go` command
-reference](https://golang.org/cmd/go/#hdr-List_packages_or_modules).
+For more about the `go list` command, see [`go list -m`](/ref/mod#go-list-m).
Here are a couple of examples.
@@ -224,8 +223,7 @@
$ go list -m -u example.com/theirmodule
```
-<a id="upgrading" ></a>
-## Upgrading or downgrading a dependency
+## Upgrading or downgrading a dependency {#upgrading}
You can upgrade or downgrade a dependency module by using Go tools to discover
available versions, then add a different version as a dependency.
@@ -234,10 +232,9 @@
[Discovering available updates](#discovering_updates).
1. To add a particular version as a dependency, use the `go get` command as
- described in [Getting a specific module version](#getting_version).
+ described in [Getting a specific dependency version](#getting_version).
-<a id="synchronizing" ></a>
-## Synchronizing your code's dependencies
+## Synchronizing your code's dependencies {#synchronizing}
You can ensure that you're managing dependencies for all of your code's imported
packages while also removing dependencies for packages you're no longer
@@ -260,8 +257,7 @@
$ go mod tidy
```
-<a id="unpublished" ></a>
-## Developing and testing against unpublished module code
+## Developing and testing against unpublished module code {#unpublished}
You can specify that your code should use dependency modules that may not be
published. The code for these modules might be in their respective repositories,
@@ -276,8 +272,7 @@
* You're building a new module and haven't yet published it, so it's
unavailable on a repository where the `go get` command can reach it.
-<a id="local_directory" ></a>
-### Requiring module code in a local directory
+### Requiring module code in a local directory {#local_directory}
You can specify that the code for a required module is on the same local drive
as the code that requires it. You might find this useful when you are:
@@ -290,8 +285,8 @@
To tell Go commands to use the local copy of the module's code, use the
`replace` directive in your go.mod file to replace the module path given in a
-`require` directive. See the [go.mod reference](gomod-ref) for more about
-directives.
+`require` directive. See the [go.mod reference](/doc/modules/gomod-ref) for
+more about directives.
In the following go.mod file example, the current module requires the external
module `example.com/theirmodule`, with a nonexistent version number
@@ -310,11 +305,9 @@
replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule
```
-When setting up a `require`/`replace` pair, use the [`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts) and
-[`go
-get`](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
-commands to ensure that requirements described by the file remain consistent:
+When setting up a `require`/`replace` pair, use the
+[`go mod edit`](/ref/mod#go-mod-edit) and [`go get`](/ref/mod#go-get) commands
+to ensure that requirements described by the file remain consistent:
```
$ go mod edit -replace=example.com/theirmodule@v0.0.0-unpublished=../theirmodule
@@ -324,10 +317,9 @@
**Note:** When you use the replace directive, Go tools don't authenticate
external modules as described in [Adding a dependency](#adding_dependency).
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
-<a id="external_fork" ></a>
-### Requiring external module code from your own repository fork
+### Requiring external module code from your own repository fork {#external_fork}
When you have forked an external module's repository (such as to fix an issue in
the module's code or to add a feature), you can have Go tools use your fork for
@@ -362,10 +354,9 @@
When setting up a `require`/`replace` pair, use Go tool commands to ensure that
requirements described by the file remain consistent. Use the [`go
-list`](https://golang.org/cmd/go/#hdr-List_packages_or_modules) command to get
-the version in use by the current module. Then use the [`go mod
-edit`](https://golang.org/cmd/go/#hdr-Edit_go_mod_from_tools_or_scripts) command
-to replace the required module with the fork:
+list`](/ref/mod#go-list-m) command to get the version in use by the current
+module. Then use the [`go mod edit`](/ref/mod#go-mod-edit) command to replace
+the required module with the fork:
```
$ go list -m example.com/theirmodule
@@ -376,10 +367,9 @@
**Note:** When you use the `replace` directive, Go tools don't authenticate
external modules as described in [Adding a dependency](#adding_dependency).
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
-<a id="repo_identifier" ></a>
-## Getting a specific commit using a repository identifier
+## Getting a specific commit using a repository identifier {#repo_identifier}
You can use the `go get` command to add unpublished code for a module from a
specific commit in its repository.
@@ -404,25 +394,22 @@
$ go get example.com/theirmodule@bugfixes
```
-<a id="removing_dependency" ></a>
-## Removing a dependency
+## Removing a dependency {#removing_dependency}
When your code no longer uses any packages in a module, you can stop tracking
the module as a dependency.
To stop tracking all unused modules, run the [`go mod tidy`
-command](https://golang.org/cmd/go/#hdr-Add_missing_and_remove_unused_modules).
-This command also may also add missing dependencies needed to build packages in
-your module.
+command](/ref/mod#go-mod-tidy). This command also may also add missing
+dependencies needed to build packages in your module.
```
$ go mod tidy
```
To remove a specific dependency, use the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them),
-specifying the module's module path and appending `@none`, as in the following
-example:
+command](/ref/mod#go-get), specifying the module's module path and appending
+`@none`, as in the following example:
```
$ go get example.com/theirmodule@none
@@ -431,8 +418,7 @@
The `go get` command will also downgrade or remove other dependencies that
depend on the removed module.
-<a id="proxy_server" ></a>
-## Specifying a module proxy server
+## Specifying a module proxy server {#proxy_server}
When you use Go tools to work with modules, the tools by default download
modules from proxy.golang.org (a public Google-run module mirror) or directly
diff --git a/_content/doc/modules/managing-source.md b/_content/doc/modules/managing-source.md
index ac14da3..cb41dce 100644
--- a/_content/doc/modules/managing-source.md
+++ b/_content/doc/modules/managing-source.md
@@ -14,7 +14,7 @@
Some of the conventions described here are required in modules, while others are
best practices. This content assumes you're familiar with the basic module use
-practices described in [Managing dependencies](managing-dependencies).
+practices described in [Managing dependencies](/doc/modules/managing-dependencies).
Go supports the following repositories for publishing modules: Git, Subversion,
Mercurial, Bazaar, and Fossil.
@@ -22,8 +22,7 @@
For an overview of module development, see [Developing and publishing
modules](developing).
-<a id="tools" ></a>
-## How Go tools find your published module
+## How Go tools find your published module {#tools}
In Go's decentralized system for publishing modules and retrieving their code,
you can publish your module while leaving the code in your repository. Go tools
@@ -31,7 +30,7 @@
module's name and version number. When your repository follows these
requirements, your module code is downloadable from your repository by Go tools
such as the [`go get`
-command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them).
+command](/ref/mod#go-get).
When a developer uses the `go get` command to get source code for packages their
code imports, the command does the following:
@@ -46,8 +45,7 @@
release version.
1. Retrieves module source and downloads it to the developer's local module cache.
-<a id="repository" ></a>
-## Organizing code in the repository
+## Organizing code in the repository {#repository}
You can keep maintenance simple and improve developers' experience with your
module by following the conventions described here. Getting your module code
@@ -116,8 +114,7 @@
$ git push
```
-<a id="repository-scope" ></a>
-## Choosing repository scope
+## Choosing repository scope {#repository-scope}
You publish code in a module when the code should be versioned independently
from code in other modules.
@@ -128,8 +125,7 @@
your needs require it, you can instead maintain a collection of modules in a
single repository.
-<a id="one-module-source" ></a>
-### Sourcing one module per repository
+### Sourcing one module per repository {#one-module-source}
You can maintain a repository that has a single module's source in it. In this
model, you place your go.mod file at the repository root, with package
@@ -143,8 +139,7 @@
alt="Diagram illustrating a single module's source in its repository"
style="width: 425px;" />
-<a id="multiple-module-source" ></a>
-### Sourcing multiple modules in a single repository
+### Sourcing multiple modules in a single repository {#multiple-module-source}
You can publish multiple modules from a single repository. For example, you
might have code in a single repository that constitutes multiple modules, but
@@ -155,7 +150,7 @@
Sourcing module code in subdirectories changes the form of the version tag you
must use when publishing a module. You must prefix the version number part of
the tag with the name of the subdirectory that is the module root. For more
-about version numbers, see [Module version numbering](version-numbers).
+about version numbers, see [Module version numbering](/doc/modules/version-numbers).
For example, for module `example.com/mymodules/module1` below, you would have
the following for version v1.2.3:
diff --git a/_content/doc/modules/publishing.md b/_content/doc/modules/publishing.md
index db5ec4f..f98f07c 100644
--- a/_content/doc/modules/publishing.md
+++ b/_content/doc/modules/publishing.md
@@ -19,9 +19,9 @@
* For an overview of module development, see [Developing and publishing
modules](developing)
* For a high-level module development workflow -- which includes publishing --
- see [Module release and versioning workflow](release-workflow).
+ see [Module release and versioning workflow](/doc/modules/release-workflow).
-## Publishing steps
+## Publishing steps {#steps}
Use the following steps to publish a module.
@@ -75,9 +75,9 @@
```
Developers interested in your module import a package from it and run the
-[`go get` command](/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
+[`go get` command](/ref/mod#go-get)
just as they would with any other module. They can run the
-[`go get` command](/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them)
+[`go get` command](/ref/mod#go-get)
for latest versions or they can specify a particular version, as in the
following example:
diff --git a/_content/doc/modules/release-workflow.md b/_content/doc/modules/release-workflow.md
index 78f0cb6..097a57a 100644
--- a/_content/doc/modules/release-workflow.md
+++ b/_content/doc/modules/release-workflow.md
@@ -13,11 +13,11 @@
**See also**
* If you're merely wanting to use external packages in your code, be sure to
- see [Managing dependencies](managing-dependencies).
+ see [Managing dependencies](/doc/modules/managing-dependencies).
* With each new version, you signal the changes to your module with its
- version number. For more, see [Module version numbering](version-numbers).
+ version number. For more, see [Module version numbering](/doc/modules/version-numbers).
-## Common workflow steps
+## Common workflow steps {#common-steps}
The following sequence illustrates release and versioning workflow steps for an
example new module. For more about each step, see the sections in this topic.
@@ -26,10 +26,10 @@
to use and for you to maintain.
If you're brand new to developing modules, check out [Tutorial: Create a Go
- module](https://golang.org/doc/tutorial/create-module).
+ module](/doc/tutorial/create-module).
In Go's decentralized module publishing system, how you organize your code
- matters. For more, see [Managing module source](managing-source).
+ matters. For more, see [Managing module source](/doc/modules/managing-source).
1. Set up to **write local client code** that calls functions in the
unpublished module.
@@ -82,8 +82,7 @@
disruptive upgrade for your module's users. It should be a last resort. For
more, see [Publishing breaking API changes](#breaking).
-<a id="unpublished" ></a>
-## Coding against an unpublished module
+## Coding against an unpublished module {#unpublished}
When you begin developing a module or a new version of a module, you won't yet
have published it. Before you publish a module, you won't be able to use Go
@@ -96,15 +95,14 @@
information, see in [Requiring module code in a local
directory](managing-dependencies#local_directory).
-<a id="pre-release" ></a>
-## Publishing pre-release versions
+## Publishing pre-release versions {#pre-release}
You can publish pre-release versions to make a module available for others to
try it out and give you feedback. A pre-release version includes no guarantee of
stability.
Pre-release version numbers are appended with a pre-release identifier. For more
-on version numbers, see [Module version numbering](version-numbers).
+on version numbers, see [Module version numbering](/doc/modules/version-numbers).
Here are two examples:
@@ -128,8 +126,7 @@
specifying the pre-release identifier in the tag. For more, see [Publishing a
module](publishing).
-<a id="first-unstable" ></a>
-## Publishing the first (unstable) version
+## Publishing the first (unstable) version {#first-unstable}
As when you publish a pre-release version, you can publish release versions that
don't guarantee stability or backward compatibility, but give your users an
@@ -156,8 +153,7 @@
specifying a v0 version number in the tag. For more, see [Publishing a
module](publishing).
-<a id="first-stable" ></a>
-## Publishing the first stable version
+## Publishing the first stable version {#first-stable}
Your first stable release will have a v1.x.x version number. The first stable
release follows pre-release and v0 releases through which you got feedback,
@@ -182,7 +178,7 @@
when you increment from v0 to v1, you needn't be mindful of breaking backward
compatibility because the v0 release was not considered stable.
-For more about version numbers, see [Module version numbering](version-numbers).
+For more about version numbers, see [Module version numbering](/doc/modules/version-numbers).
Here's an example of a stable version number:
@@ -194,8 +190,7 @@
repository, specifying a v1 version number in the tag. For more, see [Publishing
a module](publishing).
-<a id="bug-fixes" ></a>
-## Publishing bug fixes
+## Publishing bug fixes {#bug-fixes}
You can publish a release in which the changes are limited to bug fixes. This is
known as a patch release.
@@ -210,7 +205,7 @@
more invasive change to a transitive dependency that they use.
A patch release increments the patch part of the module's version number. For
-more see, [Module version numbering](version-numbers).
+more see, [Module version numbering](/doc/modules/version-numbers).
In the following example, v1.0.1 is a patch release.
@@ -222,8 +217,7 @@
incrementing the patch version number in the tag. For more, see [Publishing a
module](publishing).
-<a id="non-breaking" ></a>
-## Publishing non-breaking API changes
+## Publishing non-breaking API changes {#non-breaking}
You can make non-breaking changes to your module's public API and publish those
changes in a _minor_ version release.
@@ -235,7 +229,7 @@
existing code that calls the module's functions.
A minor release increments the minor part of the module's version number. For
-more, see [Module version numbering](version-numbers).
+more, see [Module version numbering](/doc/modules/version-numbers).
In the following example, v1.1.0 is a minor release.
@@ -247,8 +241,7 @@
incrementing the minor version number in the tag. For more, see [Publishing a
module](publishing).
-<a id="breaking" ></a>
-## Publishing breaking API changes
+## Publishing breaking API changes {#breaking}
You can publish a version that breaks backward compatibility by publishing a
_major_ version release.
@@ -259,7 +252,7 @@
Given the disruptive effect a major version upgrade can have on code relying on
the module, you should avoid a major version update if you can. For more about
-major version updates, see [Developing a major version update](major-version).
+major version updates, see [Developing a major version update](/doc/modules/major-version).
For strategies to avoid making breaking changes, see the blog post [Keeping your
modules compatible](https://blog.golang.org/module-compatibility).
@@ -272,7 +265,7 @@
One way to do this is to create a new branch in your repository that is
specifically for the new major version and its subsequent minor and patch
- versions. For more, see [Managing module source](managing-source).
+ versions. For more, see [Managing module source](/doc/modules/managing-source).
1. In the module's go.mod file, revise the module path to append the new major
version number, as in the following example:
@@ -298,4 +291,4 @@
incrementing the major version number in the tag -- such as from v1.5.2 to
v2.0.0.
- For more, see [Publishing a module](publishing).
+ For more, see [Publishing a module](/doc/modules/publishing).
diff --git a/_content/doc/modules/version-numbers.md b/_content/doc/modules/version-numbers.md
index ca1acdd..70ec30b 100644
--- a/_content/doc/modules/version-numbers.md
+++ b/_content/doc/modules/version-numbers.md
@@ -10,18 +10,23 @@
When you're developing code that uses external modules, you can use the version
numbers to understand an external module's stability when you're considering an
-upgrade. When you're developing your own modules, your version numbers will
+upgrade. For more on managing versions, see
+[Managing dependencies](/doc/modules/managing-dependencies).
+
+When you're developing your own modules, your version numbers will
signal your modules' stability and backward compatibility to other developers.
+For more about versioning in the module development workflow, see
+[Module release and versioning workflow](/doc/modules/release-workflow).
This topic describes what module version numbers mean.
**See also**
* When you're using external packages in your code, you can manage those
- dependencies with Go tools. For more, see [Managing dependencies](managing-dependencies).
+ dependencies with Go tools. For more, see [Managing dependencies](/doc/modules/managing-dependencies).
* If you're developing modules for others to use, you apply a version number
when you publish the module, tagging the module in its repository. For more,
- see [Publishing a module](publishing).
+ see [Publishing a module](/doc/modules/publishing).
A released module is published with a version number in the semantic versioning
model, as in the following illustration:
@@ -81,8 +86,7 @@
</tbody>
</table>
-<a id="in-development" ></a>
-## In development
+## In development {#in-development}
Signals that the module is still in development and **unstable**. This release
carries no backward compatibility or stability guarantees.
@@ -91,14 +95,17 @@
**Pseudo-version number**
-> v0.0.0-20170915032832-14c0d48ead0c
+```
+v0.0.0-20170915032832-14c0d48ead0c
+```
**v0 number**
-> v0.x.x
+```
+v0.x.x
+```
-<a id="pseudo" ></a>
-### Pseudo-version number
+### Pseudo-version number {#pseudo}
When a module has not been tagged in its repository, Go tools will generate a
pseudo-version number for use in the go.mod file of code that calls functions in
@@ -114,11 +121,11 @@
A pseudo-version number has three parts separated by dashes, as shown in the
following form:
-#### Syntax
+#### Syntax {#pseudo-syntax}
_baseVersionPrefix_-_timestamp_-_revisionIdentifier_
-#### Parts
+#### Parts {#pseudo-parts}
* **baseVersionPrefix** (vX.0.0 or vX.Y.Z-0) is a value derived either from a
semantic version tag that precedes the revision or from vX.0.0 if there is no
@@ -130,8 +137,7 @@
* **revisionIdentifier** (abcdefabcdef) is a 12-character prefix of the commit
hash, or in Subversion, a zero-padded revision number.
-<a id="v0" ></a>
-### v0 number
+### v0 number {#v0}
A module published with a v0 number will have a formal semantic version number
with a major, minor, and patch part, as well as an optional pre-release
@@ -143,13 +149,12 @@
developer with code consuming functions in a v0 module is responsible for
adapting to incompatible changes until v1 is released.
-<a id="pre-release" ></a>
-## Pre-release version
+## Pre-release version {#pre-release}
Signals that this is a pre-release milestone, such as an alpha or beta. This
release carries no stability guarantees.
-#### Example
+#### Example {#pre-release-example}
```
vx.x.x-beta.2
@@ -158,13 +163,12 @@
A module's developer can use a pre-release identifier with any major.minor.patch
combination by appending a hyphen and the pre-release identifier.
-<a id="minor" ></a>
-## Minor version
+## Minor version {#minor}
Signals backward-compatible changes to the module’s public API. This release
guarantees backward compatibility and stability.
-#### Example
+#### Example {#minor-example}
```
vx.4.x
@@ -178,13 +182,12 @@
that another developer might want to use. However, a developer using previous
minor versions needn’t change their code otherwise.
-<a id="patch" ></a>
-## Patch version
+## Patch version {#patch}
Signals changes that don't affect the module's public API or its dependencies.
This release guarantees backward compatibility and stability.
-#### Example
+#### Example {#patch-example}
```
vx.x.1
@@ -194,16 +197,17 @@
fixes. Developers of consuming code can upgrade to this version safely without
needing to change their code.
-<a id="major" ></a>
-## Major version
+## Major version {#major}
Signals backward-incompatible changes in a module’s public API. This release
carries no guarantee that it will be backward compatible with preceding major
versions.
-#### Example
+#### Example {#major-example}
+```
v1.x.x
+```
A v1 or above version number signals that the module is stable for use (with
exceptions for its pre-release versions).
@@ -230,6 +234,6 @@
A major version update makes this a new module with a separate history from the
module's previous version. If you're developing modules to publish for others,
see "Publishing breaking API changes" in [Module release and versioning
-workflow](release-workflow).
+workflow](/doc/modules/release-workflow).
-For more on the module directive, see [go.mod reference](gomod-ref).
+For more on the module directive, see [go.mod reference](/doc/modules/gomod-ref).
diff --git a/_content/doc/tutorial/add-a-test.html b/_content/doc/tutorial/add-a-test.html
index d52f3d3..dffd492 100644
--- a/_content/doc/tutorial/add-a-test.html
+++ b/_content/doc/tutorial/add-a-test.html
@@ -12,7 +12,7 @@
<aside class="Note">
<strong>Note:</strong> This topic is part of a multi-part tutorial that begins
- with <a href="create-module.html">Create a Go module</a>.
+ with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
</aside>
<p>
@@ -73,16 +73,13 @@
Implement test functions in the same package as the code you're testing.
</li>
<li>
- Create two test functions to test the
- <code>greetings.Hello</code> function. Test function names have the form
- <code>Test<em>Name</em></code
- >, where <em>Name</em> is specific to the test. Also, test functions
- take a pointer to the
- <a href="https://golang.org/pkg/testing/"
- ><code>testing</code> package's</a
- >
- <code>testing.T</code> as a parameter. You use this parameter's methods
- for reporting and logging from your test.
+ Create two test functions to test the <code>greetings.Hello</code>
+ function. Test function names have the form <code>Test<em>Name</em></code>,
+ where <em>Name</em> says something about the specific test. Also, test
+ functions take a pointer to the <code>testing</code> package's
+ <a href="https://pkg.go.dev/testing/#T"><code>testing.T</code>
+ type</a> as a parameter. You use this parameter's methods for reporting
+ and logging from your test.
</li>
<li>
Implement two tests:
@@ -94,18 +91,16 @@
able to return a valid response message. If the call returns an
error or an unexpected response message (one that doesn't include
the name you passed in), you use the <code>t</code> parameter's
- <code>Fatalf</code> method to print a message to the console and end
- execution.
+ <a href="https://pkg.go.dev/testing/#T.Fatalf">
+ <code>Fatalf</code> method</a> to print a message to the console
+ and end execution.
</li>
<li>
<code>TestHelloEmpty</code> calls the <code>Hello</code> function
with an empty string. This test is designed to confirm that your
error handling works. If the call returns a non-empty string or no
- error, you use the <code>t</code> parameter's
- <a href="https://golang.org/pkg/testing/#T.Fatalf"
- ><code>Fatalf</code> method</a
- >
- to print a message to the console and end execution.
+ error, you use the <code>t</code> parameter's <code>Fatalf</code>
+ method to print a message to the console and end execution.
</li>
</ul>
</li>
@@ -114,7 +109,7 @@
<li>
At the command line in the greetings directory, run the
- <a href="https://golang.org/cmd/go/#hdr-Test_packages"
+ <a href="/cmd/go/#hdr-Test_packages"
><code>go test</code> command</a
>
to execute the test.
@@ -202,16 +197,15 @@
</ol>
<p>
- This topic introduced Go's built-in support for unit testing. In the
- tutorial's <a href="compile-install.html">next topic</a>, you'll see how to
- compile and install your code to run it locally.
+ In the next (and last) topic, you'll see how to compile and install your code
+ to run it locally.
</p>
<p class="Navigation">
- <a class="Navigation-prev" href="greetings-multiple-people.html"
+ <a class="Navigation-prev" href="/doc/tutorial/greetings-multiple-people.html"
>< Return greetings for multiple people</a
>
- <a class="Navigation-next" href="compile-install.html"
+ <a class="Navigation-next" href="/doc/tutorial/compile-install.html"
>Compile and install the application ></a
>
</p>
diff --git a/_content/doc/tutorial/call-module-code.html b/_content/doc/tutorial/call-module-code.html
index 3c3602b..bce43d7 100644
--- a/_content/doc/tutorial/call-module-code.html
+++ b/_content/doc/tutorial/call-module-code.html
@@ -4,7 +4,7 @@
}-->
<p>
- In the <a href="create-module.html">previous section</a>, you created a
+ In the <a href="/doc/tutorial/create-module.html">previous section</a>, you created a
<code>greetings</code> module. In this section, you'll write code to make
calls to the <code>Hello</code> function in the module you just wrote. You'll
write code you can execute as an application, and which calls code in the
@@ -13,7 +13,7 @@
<aside class="Note">
<strong>Note:</strong> This topic is part of a multi-part tutorial that begins
- with <a href="create-module.html">Create a Go module</a>.
+ with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
</aside>
<ol>
@@ -22,8 +22,16 @@
is where you'll write your caller.
<p>
- For example, if your current directory in the command prompt is the
- greetings directory, you could use the following commands:
+ After you create this directory, you should have both a hello and a
+ greetings directory at the same level in the hierarchy, like so:
+ </p>
+ <pre><home>/
+ |-- greetings/
+ |-- hello/</pre>
+
+ <p>
+ For example, if your command prompt is in the greetings directory, you
+ could use the following commands:
</p>
<pre>
@@ -35,7 +43,28 @@
</li>
<li>
- In your text editor (in the hello directory), create a file in which to
+ Enable dependency tracking for the code you're about to write.
+
+ <p>
+ To enable dependency tracking for your code, run the
+ <a
+ href="/ref/mod#go-mod-init"
+ ><code>go mod init</code> command</a>, giving it the name of the module
+ your code will be in.</p>
+
+ <p>
+ For the purposes of this tutorial, use <code>example.com/hello</code>
+ for the module path.
+ </p>
+
+ <pre>
+$ go mod init example.com/hello
+go: creating new go.mod: module example.com/hello
+</pre>
+ </li>
+
+ <li>
+ In your text editor, in the hello directory, create a file in which to
write your code and call it hello.go.
</li>
@@ -61,8 +90,7 @@
message := greetings.Hello("Gladys")
fmt.Println(message)
}
-</pre
- >
+</pre>
<p>
In this code, you:
@@ -71,16 +99,16 @@
<ul>
<li>
Declare a <code>main</code> package. In Go, code executed as an
- application must go in a <code>main</code> package.
+ application must be in a <code>main</code> package.
</li>
<li>
Import two packages: <code>example.com/greetings</code> and
- <code>fmt</code>. This gives your code access to functions in those
- packages. Importing <code>example.com/greetings</code> (the package
- contained in the module you created earlier) gives you access to the
- <code>Hello</code> function. You also import <code>fmt</code>, with
- functions for handling input and output text (such as printing text to
- the console).
+ the <a href="https://pkg.go.dev/fmt/"><code>fmt</code> package</a>. This
+ gives your code access to functions in those packages. Importing
+ <code>example.com/greetings</code> (the package contained in the module
+ you created earlier) gives you access to the <code>Hello</code>
+ function. You also import <code>fmt</code>, with functions for handling
+ input and output text (such as printing text to the console).
</li>
<li>
Get a greeting by calling the <code>greetings</code> package’s
@@ -90,148 +118,124 @@
</li>
<li>
- Create a new module for this hello package.
+ Edit the <code>example.com/hello</code> module to use your local
+ <code>example.com/greetings</code> module.
<p>
- From the command line at the hello directory, run the
- <code>go mod init</code> command, giving it the name of the module your
- code will be in (here, just use "hello").
- </p>
-
- <pre>
-$ go mod init hello
-go: creating new go.mod: module hello
-</pre
- >
- </li>
-
- <li>
- Edit the <code>hello</code> module to use the unpublished greetings module.
-
- <p>
- For production use, you’d publish your modules on a server, either inside
- your company or on the internet, and the Go command will download them
- from there. For now, you need to adapt the caller's module so it can find
- the greetings code on your local file system.
+ For production use, you’d publish the <code>example.com/greetings</code>
+ module from its repository (with a module path that reflected its published
+ location), where Go tools could find it to download it.
+ For now, because you haven't published the module yet, you need to adapt
+ the <code>example.com/hello</code> module so it can find the
+ <code>example.com/greetings</code> code on your local file system.
</p>
<p>
- To do that, make a small change to <code>hello</code> module’s go.mod
- file.
+ To do that, use the
+ <a href="/ref/mod#go-mod-edit"><code>go
+ mod edit</code> command</a> to edit the <code>example.com/hello</code>
+ module to redirect Go tools from its module path (where the module isn't)
+ to the local directory (where it is).
</p>
<ol>
<li>
- In the hello directory, open the go.mod file, change it so that it looks
- like the following, and save the file.
+ From the command prompt in the hello directory, run the following
+ command:
+
+ <pre>
+$ go mod edit -replace=example.com/greetings=../greetings
+</pre>
+
+ <p>
+ The command specifies that <code>example.com/greetings</code> should be
+ replaced with <code>../greetings</code> for the purpose of locating the
+ dependency. After you run the command, the go.mod file in the hello
+ directory should include a <a href="/doc/modules/gomod-ref#replace">
+ <code>replace</code> directive</a>:
+ </p>
<pre>
-module hello
+module example.com/hello
-go 1.14
+go 1.16
<ins>replace example.com/greetings => ../greetings</ins>
</pre>
-
- <p>
- Here, the
- <a href="/ref/mod#go-mod-file-replace">
- <code>replace</code> directive
- </a>
- tells Go to replace the module path (the URL
- <code>example.com/greetings</code>) with a path you specify. In this
- case, that's a greetings directory next to the hello directory.
- </p>
</li>
<li>
- In the hello directory, run <code>go build</code> to make Go locate the
- module and add it as a dependency to the go.mod file.
+ From the command prompt in the hello directory, run the
+ <a href="/ref/mod#go-mod-tidy">
+ <code>go mod tidy</code> command</a> to synchronize the
+ <code>example.com/hello</code> module's dependencies, adding those
+ required by the code, but not yet tracked in the module.
- <pre>
-$ go build
+ <pre>$ go mod tidy
go: found example.com/greetings in example.com/greetings v0.0.0-00010101000000-000000000000
-</pre
- >
- </li>
+</pre>
+ <p>
+ After the command completes, the <code>example.com/hello</code>
+ module's go.mod file should look like this:
+ </p>
- <li>
- Look at go.mod again to see the changes made by <code>go build</code>,
- including the <code>require</code> directive Go added.
+ <pre>module example.com/hello
- <pre>
-module hello
-
-go 1.14
+go 1.16
replace example.com/greetings => ../greetings
-<ins>require example.com/greetings v0.0.0-00010101000000-000000000000</ins>
-</pre>
+<ins>require example.com/greetings v0.0.0-00010101000000-000000000000</ins></pre>
<p>
- To build the module, Go found the local code in the ../greetings
- directory, then added a
- <a href="/ref/mod#go-mod-file-require">
- <code>require</code> directive
- </a>
- to specify that <code>hello</code> is dependent on (requires)
- <code>example.com/greetings</code>. You created this dependency when
- you imported the <code>greetings</code> package (contained in the
- greetings module) in hello.go. The <code>replace</code> directive
- tells Go where to find the <code>greetings</code> module, because it
- isn't published yet.
+ The command found the local code in the greetings directory, then
+ added a <a href="/doc/modules/gomod-ref#require"><code>require</code>
+ directive</a> to specify that <code>example.com/hello</code>
+ requires <code>example.com/greetings</code>. You created this
+ dependency when you imported the <code>greetings</code> package in
+ hello.go.
</p>
-
<p>
- To reference a published module, a go.mod file would omit the
- <code>replace</code> directive and use a
- <code>require</code> directive with a tagged version number at the
- end.
+ The number following the module path is a <em>pseudo-version number</em>
+ -- a generated number used in place of a semantic version number (which
+ the module doesn't have yet).
+ </p>
+ <p>
+ To reference a <em>published</em> module, a go.mod file would
+ typically omit the <code>replace</code> directive and use a
+ <code>require</code> directive with a tagged version number at the end.
</p>
<pre>require example.com/greetings v1.1.0</pre>
+
+ <p>For more on version numbers, see
+ <a href="/doc/modules/version-numbers">Module version numbering</a>.</p>
</li>
</ol>
- </li>
-
<li>
- In the <code>hello</code> directory, run the <code>hello</code> executable
- (created by <code>go build</code>) to confirm that the code works.
- <ul>
- <li>
- On Linux or Mac:
+ At the command prompt in the <code>hello</code> directory, run your code to
+ confirm that it works.
- <pre>
-$ ./hello
+ <pre>
+$ go run .
Hi, Gladys. Welcome!
-</pre
- >
- </li>
-
- <li>
- On Windows:
-
- <pre>
-$ hello.exe
-Hi, Gladys. Welcome!
-</pre
- >
- </li>
- </ul>
+</pre>
</li>
</ol>
<p>
- Congrats! You've written two functioning modules. In the tutorial's
- <a href="handle-errors.html">next topic</a>, you'll add some error handling.
+ Congrats! You've written two functioning modules.
+</p>
+
+<p>
+ In the next topic, you'll add some error handling.
</p>
<p class="Navigation">
- <a class="Navigation-prev" href="create-module.html"
+ <a class="Navigation-prev" href="/doc/tutorial/create-module.html"
>< Create a Go module</a
>
- <a class="Navigation-next" href="handle-errors.html"
+ <a class="Navigation-next" href="/doc/tutorial/handle-errors.html"
>Return and handle an error ></a
>
</p>
diff --git a/_content/doc/tutorial/compile-install.html b/_content/doc/tutorial/compile-install.html
index 5395ae5..4d59618 100644
--- a/_content/doc/tutorial/compile-install.html
+++ b/_content/doc/tutorial/compile-install.html
@@ -4,17 +4,27 @@
}-->
<p>
- In the last section, you'll learn a new <code>go</code> command. While the
- <code>go run</code> command is a useful shortcut for compiling and running a
- single-file program, it doesn't generate a binary executable you can easily
- run again. If you want one of those, a good choice is to run the
- <a
- href="https://golang.org/cmd/go/#hdr-Compile_and_install_packages_and_dependencies"
- ><code>go install</code> command</a
- >, which compiles your code and installs the resulting binary executable where
- you can run it.
+ In this last topic, you'll learn a couple new <code>go</code> commands. While
+ the <code>go run</code> command is a useful shortcut for compiling and running
+ a program when you're making frequent changes, it doesn't generate a binary
+ executable.</p>
+
+<p>
+ This topic introduces two additional commands for building code:
</p>
+<ul>
+ <li>
+ The <a href="/cmd/go/#hdr-Compile_packages_and_dependencies"><code>go
+ build</code> command</a> compiles the packages, along with their dependencies,
+ but it doesn't install the results.
+ </li>
+ <li>
+ The <a href="/ref/mod#go-install"><code>go
+ install</code> command</a> compiles and installs the packages.
+ </li>
+</ul>
+
<aside class="Note">
<strong>Note:</strong> This topic is part of a multi-part tutorial that begins
with <a href="create-module.html">Create a Go module</a>.
@@ -22,7 +32,49 @@
<ol>
<li>
- At the command line, change to the directory that contains hello/hello.go.
+ From the command line in the hello directory, run the <code>go build</code>
+ command to compile the code into an executable.
+
+ <pre>$ go build</pre>
+ </li>
+
+ <li>
+ From the command line in the hello directory, run the new <code>hello</code>
+ executable to confirm that the code works.
+
+ <p>
+ Note that your result might differ depending on whether you changed
+ your greetings.go code after testing it.
+ </p>
+
+ <ul>
+ <li>
+ On Linux or Mac:
+
+ <pre>
+$ ./hello
+map[Darrin:Great to see you, Darrin! Gladys:Hail, Gladys! Well met! Samantha:Hail, Samantha! Well met!]
+</pre>
+ </li>
+
+ <li>
+ On Windows:
+
+ <pre>
+$ hello.exe
+map[Darrin:Great to see you, Darrin! Gladys:Hail, Gladys! Well met! Samantha:Hail, Samantha! Well met!]
+</pre>
+ </li>
+ </ul>
+ <p>
+ You've compiled the application into an executable so you can run it.
+ But to run it currently, your prompt needs either to be in the executable's
+ directory, or to specify the executable's path.
+ </p>
+ <p>
+ Next, you'll install the executable so you can run it without specifying
+ its path.
+ </p>
</li>
<li>
@@ -31,21 +83,18 @@
<p>
You can discover the install path by running the
- <a href="https://golang.org/cmd/go/#hdr-List_packages_or_modules"
- ><code>go list</code> command</a
- >, as in the following example:
+ <a href="/cmd/go/#hdr-List_packages_or_modules">
+ <code>go list</code> command</a>, as in the following example:
</p>
<pre>
-go list -f '{{.Target}}'
-</pre
- >
+$ go list -f '{{.Target}}'
+</pre>
<p>
- For example, the command's output might say
- <code>/home/gopher/bin/hello</code>, meaning that binaries are installed
- to /home/gopher/bin. This is the install directory you'll need in the next
- step.
+ For example, the command's output might say <code>/home/gopher/bin/hello</code>,
+ meaning that binaries are installed to /home/gopher/bin. You'll need this
+ install directory in the next step.
</p>
</li>
@@ -62,7 +111,7 @@
On Linux or Mac, run the following command:
<pre>
-export PATH=$PATH:/path/to/your/install/directory
+$ export PATH=$PATH:/path/to/your/install/directory
</pre
>
</li>
@@ -71,7 +120,7 @@
On Windows, run the following command:
<pre>
-set PATH=%PATH%;C:\path\to\your\install\directory
+$ set PATH=%PATH%;C:\path\to\your\install\directory
</pre
>
</li>
@@ -80,24 +129,22 @@
<p>
As an alternative, if you already have a directory like
<code>$HOME/bin</code> in your shell path and you'd like to install your
- Go programs there, you can change the install target by setting the GOBIN
- variable using the
- <a href="https://golang.org/cmd/go/#hdr-Print_Go_environment_information"
- ><code>go env</code> command</a
- >:
+ Go programs there, you can change the install target by setting the
+ <code>GOBIN</code> variable using the
+ <a href="/cmd/go/#hdr-Print_Go_environment_information">
+ <code>go env</code> command</a>:
</p>
<pre>
-go env -w GOBIN=/path/to/your/bin
-</pre
- >
+$ go env -w GOBIN=/path/to/your/bin
+</pre>
<p>
or
</p>
<pre>
-go env -w GOBIN=C:\path\to\your\bin
+$ go env -w GOBIN=C:\path\to\your\bin
</pre
>
</li>
@@ -106,14 +153,13 @@
Once you've updated the shell path, run the <code>go install</code> command
to compile and install the package.
- <pre>
-$ go install
-</pre
- >
+ <pre>$ go install</pre>
</li>
<li>
- Run your application by simply typing its name.
+ Run your application by simply typing its name. To make this interesting,
+ open a new command prompt and run the <code>hello</code> executable name
+ in some other directory.
<pre>
$ hello
@@ -124,11 +170,11 @@
</ol>
<p>
- That wraps up this Go tutorial! For a next step that introduces many more of
- Go features, check out the
- <a href="https://tour.golang.org/welcome/1">Tour of Go</a>.
+ That wraps up this Go tutorial!
</p>
<p class="Navigation">
<a class="Navigation-prev" href="add-a-test.html">< Add a test</a>
+ <a class="Navigation-next" href="module-conclusion.html">Conclusion and links
+ to more information ></a>
</p>
diff --git a/_content/doc/tutorial/create-module.html b/_content/doc/tutorial/create-module.html
index cf6558c..3dbe35f 100644
--- a/_content/doc/tutorial/create-module.html
+++ b/_content/doc/tutorial/create-module.html
@@ -6,8 +6,8 @@
<p>
This is the first part of a tutorial that introduces a few fundamental
features of the Go language. If you're just getting started with Go, be sure
- to take a look at the
- <a href="getting-started.html">getting started</a> tutorial, which introduces
+ to take a look at
+ <a href="/doc/tutorial/getting-started.html">Tutorial: Get started with Go</a>, which introduces
the <code>go</code> command, Go modules, and very simple Go code.
</p>
@@ -28,36 +28,36 @@
another module.
</li>
<li>
- <a href="call-module-code.html">Call your code from another module</a> --
+ <a href="/doc/tutorial/call-module-code.html">Call your code from another module</a> --
Import and use your new module.
</li>
<li>
- <a href="handle-errors.html">Return and handle an error</a> -- Add simple
+ <a href="/doc/tutorial/handle-errors.html">Return and handle an error</a> -- Add simple
error handling.
</li>
<li>
- <a href="random-greeting.html">Return a random greeting</a> -- Handle data
+ <a href="/doc/tutorial/random-greeting.html">Return a random greeting</a> -- Handle data
in slices (Go's dynamically-sized arrays).
</li>
<li>
- <a href="greetings-multiple-people.html"
+ <a href="/doc/tutorial/greetings-multiple-people.html"
>Return greetings for multiple people</a
>
-- Store key/value pairs in a map.
</li>
<li>
- <a href="add-a-test.html">Add a test</a> -- Use Go's built-in unit testing
+ <a href="/doc/tutorial/add-a-test.html">Add a test</a> -- Use Go's built-in unit testing
features to test your code.
</li>
<li>
- <a href="compile-install.html">Compile and install the application</a> --
+ <a href="/doc/tutorial/compile-install.html">Compile and install the application</a> --
Compile and install your code locally.
</li>
</ol>
<aside class="Note">
<strong>Note:</strong> For other tutorials, see
- <a href="index.html">Tutorials</a>.
+ <a href="/doc/tutorial/index.html">Tutorials</a>.
</aside>
<h2 id="prerequisites">Prerequisites</h2>
@@ -81,18 +81,18 @@
<h2 id="start">Start a module that others can use</h2>
<p>
- Start by creating a
- <a href="https://golang.org/doc/code.html#Organization">Go module</a>. In a
+ Start by creating a Go module. In a
module, you collect one or more related packages for a discrete and useful set
of functions. For example, you might create a module with packages that have
functions for doing financial analysis so that others writing financial
- applications can use your work.
+ applications can use your work. For more about developing modules, see
+ <a href="/doc/modules/developing">Developing and publishing modules</a>.
</p>
<p>
Go code is grouped into packages, and packages are grouped into modules. Your
- package's module specifies the context Go needs to run the code, including the
- Go version the code is written for and the set of other modules it requires.
+ module specifies dependencies needed to run your code, including the Go
+ version and the set of other modules it requires.
</p>
<p>
@@ -127,7 +127,6 @@
<li>
Create a <code>greetings</code> directory for your Go module source code.
- This is where you'll write your module code.
<p>
For example, from your home directory use the following commands:
@@ -143,16 +142,15 @@
<li>
Start your module using the
<a
- href="https://golang.org/cmd/go/#hdr-Initialize_new_module_in_current_directory"
+ href="/ref/mod#go-mod-init"
><code>go mod init</code> command</a
- >
- to create a go.mod file.
+ >.
<p>
- Run the <code>go mod init</code> command, giving it the path of the module
- your code will be in. Here, use <code>example.com/greetings</code> for the
- module path -- in production code, this would be the URL from which your
- module can be downloaded.
+ Run the <code>go mod init</code> command, giving it your module path --
+ here, use <code>example.com/greetings</code>. If you publish a module,
+ this <em>must</em> be a path from which your module can be downloaded by
+ Go tools. That would be your code's repository.
</p>
<pre>
@@ -162,13 +160,12 @@
>
<p>
- The <code>go mod init</code> command creates a go.mod file that identifies
- your code as a module that might be used from other code. The file you
- just created includes only the name of your module and the Go version your
- code supports. But as you add dependencies -- meaning packages from other
- modules -- the go.mod file will list the specific module versions to use.
- This keeps builds reproducible and gives you direct control over which
- module versions to use.
+ The <code>go mod init</code> command creates a go.mod file to track your
+ code's dependencies. So far, the file includes only the name of your
+ module and the Go version your code supports. But as you add dependencies,
+ the go.mod file will list the versions your code depends on. This keeps
+ builds reproducible and gives you direct control over which module
+ versions to use.
</p>
</li>
@@ -212,10 +209,12 @@
Implement a <code>Hello</code> function to return the greeting.
<p>
This function takes a <code>name</code> parameter whose type is
- <code>string</code>, and returns a <code>string</code>. In Go, a
- function whose name starts with a capital letter can be called by a
- function not in the same package. This is known in Go as an
- <a href="https://tour.golang.org/basics/3"><em>exported</em> name</a>.
+ <code>string</code>. The function also returns a <code>string</code>.
+ In Go, a function whose name starts with a capital letter can be
+ called by a function not in the same package. This is known in Go as
+ an exported name. For more about exported names, see
+ <a href="https://tour.golang.org/basics/3">Exported names</a> in the
+ Go tour.
</p>
<img src="images/function-syntax.png" width="300px" />
</li>
@@ -236,11 +235,12 @@
</li>
<li>
- Use the <code>fmt</code> package's <code>Sprintf</code> function to
- create a greeting message. The first argument is a format string, and
- <code>Sprintf</code> substitutes the <code>name</code> parameter's value
- for the <code>%v</code> format verb. Inserting the value of the
- <code>name</code> parameter completes the greeting text.
+ Use the <code>fmt</code> package's <a href="https://pkg.go.dev/fmt/#Sprintf">
+ <code>Sprintf</code> function</a> to create a greeting message. The
+ first argument is a format string, and <code>Sprintf</code> substitutes
+ the <code>name</code> parameter's value for the <code>%v</code> format
+ verb. Inserting the value of the <code>name</code> parameter completes
+ the greeting text.
</li>
<li>Return the formatted greeting text to the caller.</li>
</ul>
@@ -248,12 +248,11 @@
</ol>
<p>
- In the <a href="call-module-code.html">next step</a>, you'll call this
- function from another module.
+ In the next step, you'll call this function from another module.
</p>
<p class="Navigation">
- <a class="Navigation-next" href="call-module-code.html"
+ <a class="Navigation-next" href="/doc/tutorial/call-module-code.html"
>Call your code from another module ></a
>
</p>
diff --git a/_content/doc/tutorial/getting-started.html b/_content/doc/tutorial/getting-started.html
index fc05867..eff1bb6 100644
--- a/_content/doc/tutorial/getting-started.html
+++ b/_content/doc/tutorial/getting-started.html
@@ -21,7 +21,7 @@
<aside class="Note">
<strong>Note:</strong> For other tutorials, see
- <a href="index.html">Tutorials</a>.
+ <a href="/doc/tutorial/index.html">Tutorials</a>.
</aside>
<h2 id="prerequisites">Prerequisites</h2>
@@ -90,26 +90,35 @@
</li>
<li>
- Initialize a new module for tracking dependencies.
+ Enable dependency tracking for your code.
<p>
- When your code imports packages from another module, a go.mod file lists
- the specific modules and versions providing those packages. That file
- stays with your code, including in your source code repository.
+ When your code imports packages contained in other modules, you manage
+ those dependencies through your code's own module. That module is defined
+ by a go.mod file that tracks the modules that provide those packages. That
+ go.mod file stays with your code, including in your source code
+ repository.
</p>
<p>
- To create a go.mod file, run the
- <a
- href="https://golang.org/cmd/go/#hdr-Initialize_new_module_in_current_directory"
- ><code>go mod init</code> command</a
- >, giving it the name of the module your code will be in (here, just use
- "hello"):
+ To enable dependency tracking for your code by creating a go.mod file, run
+ the
+ <a href="/ref/mod#go-mod-init"><code>go mod init</code> command</a>,
+ giving it the name of the module your code will be in. The name is the
+ module's module path. In most cases, this will be the repository
+ location where your source code will be kept, such as
+ <code>github.com/mymodule</code>. If you plan to publish your module
+ for others to use, the module path <em>must</em> be a location from
+ which Go tools can download your module.
+ </p>
+
+ <p>For the purposes of this tutorial, just use
+ <code>example.com/hello</code>.
</p>
<pre>
-$ go mod init hello
-go: creating new go.mod: module hello
+$ go mod init example.com/hello
+go: creating new go.mod: module example.com/hello
</pre
>
</li>
@@ -143,10 +152,10 @@
</li>
<li>
Import the popular
- <a href="https://golang.org/pkg/fmt/"><code>fmt</code> package</a>,
+ <a href="https://pkg.go.dev/fmt/"><code>fmt</code> package</a>,
which contains functions for formatting text, including printing to the
console. This package is one of the
- <a href="https://golang.org/pkg/">standard library</a> packages you got
+ <a href="https://pkg.go.dev/std">standard library</a> packages you got
when you installed Go.
</li>
<li>
@@ -168,7 +177,7 @@
<p>
The
- <a href="https://golang.org/cmd/go/#hdr-Compile_and_run_Go_program"
+ <a href="/cmd/go/#hdr-Compile_and_run_Go_program"
><code>go run</code> command</a
>
is one of many <code>go</code> commands you'll use to get things done with
@@ -252,7 +261,10 @@
Add new module requirements and sums.
<p>
- Go will add the <code>quote</code> module as a requirement, as well as a go.sum file for use in authenticating the module. For more, see <a href="https://golang.org/cmd/go/#hdr-Module_authentication_using_go_sum">Module authentication using go.sum</a>.
+ Go will add the <code>quote</code> module as a requirement, as well as a
+ go.sum file for use in authenticating the module. For more, see
+ <a href="/ref/mod#authenticating">Authenticating modules</a> in the Go
+ Modules Reference.
</p>
<pre>
$ go mod tidy
@@ -289,5 +301,5 @@
<p>
With this quick introduction, you got Go installed and learned some of the
basics. To write some more code with another tutorial, take a look at
- <a href="create-module.html">Create a Go module</a>.
+ <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
</p>
diff --git a/_content/doc/tutorial/greetings-multiple-people.html b/_content/doc/tutorial/greetings-multiple-people.html
index 8100c08..1d83192 100644
--- a/_content/doc/tutorial/greetings-multiple-people.html
+++ b/_content/doc/tutorial/greetings-multiple-people.html
@@ -6,33 +6,27 @@
<p>
In the last changes you'll make to your module's code, you'll add support for
getting greetings for multiple people in one request. In other words, you'll
- handle a multiple-value input and pair values with a multiple-value output.
+ handle a multiple-value input, then pair values in that input with a
+ multiple-value output. To do this, you'll need to pass a set of names to a
+ function that can return a greeting for each of them.
</p>
<aside class="Note">
<strong>Note:</strong> This topic is part of a multi-part tutorial that begins
- with <a href="create-module.html">Create a Go module</a>.
+ with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
</aside>
<p>
- To do this, you'll need to pass a set of names to a function that can return a
- greeting for each of them. Changing the <code>Hello</code> function's
- parameter from a single name to a set of names would change the function
- signature. If you had already published the <code>greetings</code> module and
- users had already written code calling <code>Hello</code>, that change would
- break their programs. In this situation, a better choice is to give new
- functionality a new name.
-</p>
+ But there's a hitch. Changing the <code>Hello</code> function's
+ parameter from a single name to a set of names would change the function's
+ signature. If you had already published the <code>example.com/greetings</code>
+ module and users had already written code calling <code>Hello</code>, that
+ change would break their programs.</p>
<p>
- In the last code you'll add with this tutorial, update the code as if you've
- already published a version of the <code>greetings</code> module. Instead of
- changing the <code>Hello</code> function, add a new function
- <code>Hellos</code> that takes a set of names. Then, for the sake of
- simplicity, have the new function call the existing one. Keeping both
- functions in the package leaves the original for existing callers (or future
- callers who only need one greeting) and adds a new one for callers that want
- the expanded functionality.
+ In this situation, a better choice is to write a new function with a different
+ name. The new function will take multiple parameters. That preserves the old
+ function for backward compatibility.
</p>
<ol>
@@ -111,27 +105,28 @@
mapped to greeting messages.
</li>
<li>
- Have the new Hellos function call the existing Hello function. This
- leaves both functions in place.
+ Have the new <code>Hellos</code> function call the existing
+ <code>Hello</code> function. This helps reduce duplication while also
+ leaving both functions in place.
</li>
<li>
- Create a <code>messages</code>
- <a href="https://blog.golang.org/maps">map</a> to associate each of the
+ Create a <code>messages</code> map to associate each of the
received names (as a key) with a generated message (as a value). In Go,
you initialize a map with the following syntax:
<code>make(map[<em>key-type</em>]<em>value-type</em>)</code>. You have
- the <code>Hellos</code> function return this map to the caller.
+ the <code>Hellos</code> function return this map to the caller. For more
+ about maps, see <a href="https://blog.golang.org/maps">Go maps in
+ action</a> on the Go blog.
</li>
<li>
Loop through the names your function received, checking that each has a
non-empty value, then associate a message with each. In this
<code>for</code> loop, <code>range</code> returns two values: the index
of the current item in the loop and a copy of the item's value. You
- don't need the index, so you use the Go
- <a href="https://golang.org/doc/effective_go.html#blank"
- >blank identifier (an underscore)</a
- >
- to ignore it.
+ don't need the index, so you use the Go blank identifier (an underscore)
+ to ignore it. For more, see
+ <a href="/doc/effective_go.html#blank">The blank
+ identifier</a> in Effective Go.
</li>
</ul>
</li>
@@ -193,7 +188,7 @@
<li>
At the command line, change to the directory that contains hello/hello.go,
- then run hello.go to confirm that the code works.
+ then use <code>go run</code> to confirm that the code works.
<p>
The output should be a string representation of the map associating names
@@ -201,7 +196,7 @@
</p>
<pre>
-$ go run hello.go
+$ go run .
map[Darrin:Hail, Darrin! Well met! Gladys:Hi, Gladys. Welcome! Samantha:Hail, Samantha! Well met!]
</pre
>
@@ -210,18 +205,18 @@
<p>
This topic introduced maps for representing name/value pairs. It also
- introduced the idea of
- <a href="https://blog.golang.org/module-compatibility"
- >preserving backward compatibility</a
- >
+ introduced the idea of preserving backward compatibility
by implementing a new function for new or changed functionality in a module.
- In the tutorial's <a href="add-a-test.html">next topic</a>, you'll use
- built-in features to create a unit test for your code.
+ For more about backward compatibility, see
+ <a href="https://blog.golang.org/module-compatibility">Keeping your modules
+ compatible</a>.
</p>
+<p>Next, you'll use built-in Go features to create a unit test for your code.</p>
+
<p class="Navigation">
- <a class="Navigation-prev" href="random-greeting.html"
+ <a class="Navigation-prev" href="/doc/tutorial/random-greeting.html"
>< Return a random greeting</a
>
- <a class="Navigation-next" href="add-a-test.html">Add a test ></a>
+ <a class="Navigation-next" href="/doc/tutorial/add-a-test.html">Add a test ></a>
</p>
diff --git a/_content/doc/tutorial/handle-errors.html b/_content/doc/tutorial/handle-errors.html
index 4dfd4b1..76f7a4f 100644
--- a/_content/doc/tutorial/handle-errors.html
+++ b/_content/doc/tutorial/handle-errors.html
@@ -11,7 +11,7 @@
<aside class="Note">
<strong>Note:</strong> This topic is part of a multi-part tutorial that begins
- with <a href="create-module.html">Create a Go module</a>.
+ with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
</aside>
<ol>
@@ -55,14 +55,13 @@
Change the function so that it returns two values: a
<code>string</code> and an <code>error</code>. Your caller will check
the second value to see if an error occurred. (Any Go function can
- <a href="https://golang.org/doc/effective_go.html#multiple-returns"
- >return multiple values</a
- >.)
+ return multiple values. For more, see
+ <a href="/doc/effective_go.html#multiple-returns">Effective Go</a>.)
</li>
<li>
Import the Go standard library <code>errors</code> package so you can
use its
- <a href="https://golang.org/pkg/errors/#example_New"
+ <a href="https://pkg.go.dev/errors/#example-New"
><code>errors.New</code> function</a
>.
</li>
@@ -106,7 +105,7 @@
log.SetFlags(0)</ins>
// Request a greeting message.
- message, err := greetings.Hello("")
+ <ins>message, err := greetings.Hello("")</ins>
<ins>// If an error was returned, print it to the console and
// exit the program.
if err != nil {
@@ -126,7 +125,7 @@
<ul>
<li>
Configure the
- <a href="https://golang.org/pkg/log/"><code>log</code> package</a> to
+ <a href="https://pkg.go.dev/log/"><code>log</code> package</a> to
print the command name ("greetings: ") at the start of its log messages,
without a time stamp or source file information.
</li>
@@ -163,7 +162,7 @@
</p>
<pre>
-$ go run hello.go
+$ go run .
greetings: empty name
exit status 1
</pre
@@ -172,17 +171,19 @@
</ol>
<p>
- That's essentially how error handling in Go works: Return an error as a value
- so the caller can check for it. It's pretty simple. In the tutorial's
- <a href="random-greeting.html">next topic</a>, you'll use a Go slice to return
- a randomly-selected greeting.
+ That's common error handling in Go: Return an error as a value so the caller
+ can check for it.
+</p>
+
+<p>
+ Next, you'll use a Go slice to return a randomly-selected greeting.
</p>
<p class="Navigation">
- <a class="Navigation-prev" href="call-module-code.html"
+ <a class="Navigation-prev" href="/doc/tutorial/call-module-code.html"
>< Call your code from another module</a
>
- <a class="Navigation-next" href="random-greeting.html"
+ <a class="Navigation-next" href="/doc/tutorial/random-greeting.html"
>Return a random greeting ></a
>
</p>
diff --git a/_content/doc/tutorial/index.html b/_content/doc/tutorial/index.html
index 80f9c01..1bbb78d 100644
--- a/_content/doc/tutorial/index.html
+++ b/_content/doc/tutorial/index.html
@@ -20,13 +20,13 @@
<tbody>
<tr class="DocTable-row">
<td class="DocTable-cell">
- <a href="getting-started.html">Getting started</a>
+ <a href="/doc/tutorial/getting-started.html">Getting started</a>
</td>
<td class="DocTable-cell">Say Hello, World with Go.</td>
</tr>
<tr class="DocTable-row">
<td class="DocTable-cell">
- <a href="create-module.html">Create a module</a>
+ <a href="/doc/tutorial/create-module.html">Create a module</a>
</td>
<td class="DocTable-cell">
A multi-part tutorial that introduces common programming language
@@ -38,7 +38,8 @@
<a href="https://tour.golang.org/welcome/1">A Tour of Go</a>
</td>
<td class="DocTable-cell">
- An interactive introduction to Go: basic syntax and data structures; methods and interfaces; and Go's concurrency primitives.
+ An interactive introduction to Go: basic syntax and data structures;
+ methods and interfaces; and Go's concurrency primitives.
</td>
</tr>
</tbody>
diff --git a/_content/doc/tutorial/module-conclusion.html b/_content/doc/tutorial/module-conclusion.html
new file mode 100644
index 0000000..f86af3a
--- /dev/null
+++ b/_content/doc/tutorial/module-conclusion.html
@@ -0,0 +1,31 @@
+<!--{
+ "Title": "Conclusion",
+ "Path": "/doc/tutorial/module-conclusion"
+}-->
+
+<p>
+ In this tutorial, you wrote functions that you packaged into two modules: one
+ with logic for sending greetings; the other as a consumer for the first.
+</p>
+
+<aside class="Note">
+ <strong>Note:</strong> This topic is part of a multi-part tutorial that begins
+ with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
+</aside>
+
+<p>
+ For more on managing dependencies in your code, see
+ <a href="/doc/modules/managing-dependencies">Managing dependencies</a>. For
+ more about developing modules for others to use, see
+ <a href="/doc/modules/developing">Developing and publishing modules</a>.
+</p>
+
+<p>For many more features of the Go language, check out the
+ <a href="https://tour.golang.org/welcome/1">Tour of Go</a>.
+</p>
+
+<p class="Navigation">
+ <a class="Navigation-prev" href="/doc/tutorial/compile-install.html"
+ >< Compile and install the application</a
+ >
+</p>
diff --git a/_content/doc/tutorial/random-greeting.html b/_content/doc/tutorial/random-greeting.html
index d5a45be..c6c8da7 100644
--- a/_content/doc/tutorial/random-greeting.html
+++ b/_content/doc/tutorial/random-greeting.html
@@ -10,15 +10,20 @@
<aside class="Note">
<strong>Note:</strong> This topic is part of a multi-part tutorial that begins
- with <a href="create-module.html">Create a Go module</a>.
+ with <a href="/doc/tutorial/create-module.html">Create a Go module</a>.
</aside>
<p>
- To do this, you'll use a Go slice. A
- <a href="https://blog.golang.org/slices-intro"><em>slice</em></a> is like an
- array, except that it's dynamically sized as you add and remove items. It's
- one of the most useful types in Go. You'll add a small slice to contain three
- greeting messages, then have your code return one of the messages randomly.
+ To do this, you'll use a Go slice. A slice is like an array, except that its
+ size changes dynamically as you add and remove items. The slice is one of Go's
+ most useful types.
+</p>
+
+<p>
+ You'll add a small slice to contain three greeting messages, then have your
+ code return one of the messages randomly. For more on slices,
+ see <a href="https://blog.golang.org/slices-intro">Go slices</a> in the Go
+ blog.
</p>
<ol>
@@ -82,24 +87,22 @@
<li>
In <code>randomFormat</code>, declare a <code>formats</code> slice with
three message formats. When declaring a slice, you omit its size in the
- brackets, like this: <code>[]string</code>. This tells Go that the array
- underlying a slice can be dynamically sized.
+ brackets, like this: <code>[]string</code>. This tells Go that the size
+ of the array underlying the slice can be dynamically changed.
</li>
<li>
Use the
- <a href="https://golang.org/pkg/math/rand/"
+ <a href="https://pkg.go.dev/math/rand/"
><code>math/rand</code> package</a
>
to generate a random number for selecting an item from the slice.
</li>
<li>
- Add an
- <a href="https://golang.org/doc/effective_go.html#init"
- ><code>init</code> function</a
- >
- to seed the <code>rand</code> package with the current time. Go executes
- <code>init</code> functions automatically at program startup, after
- global variables have been initialized.
+ Add an <code>init</code> function to seed the <code>rand</code> package
+ with the current time. Go executes <code>init</code> functions
+ automatically at program startup, after global variables have been
+ initialized. For more about <code>init</code> functions, see
+ <a href="/doc/effective_go.html#init">Effective Go</a>.
</li>
<li>
In <code>Hello</code>, call the <code>randomFormat</code> function to
@@ -109,48 +112,70 @@
<li>Return the message (or an error) as you did before.</li>
</ul>
- <p>
- Your hello.go needn't change.
- </p>
</li>
<li>
- At the command line, change to the hello directory, then run hello.go to
- confirm that the code works. Run it multiple times, noticing that the
- greeting changes.
+ In hello/hello.go, change your code so it looks like the following.
- <p>
- Oh -- don't forget to add Gladys's name (or a different name, if you like)
- as an argument to the <code>Hello</code> function call in hello.go:
- <code>greetings.Hello("Gladys")</code>
- </p>
+ <p>You're just adding Gladys's name (or a different name, if you like)
+ as an argument to the <code>Hello</code> function call in hello.go.</p>
+
+ <pre>package main
+
+import (
+ "fmt"
+ "log"
+
+ "example.com/greetings"
+)
+
+func main() {
+ // Set properties of the predefined Logger, including
+ // the log entry prefix and a flag to disable printing
+ // the time, source file, and line number.
+ log.SetPrefix("greetings: ")
+ log.SetFlags(0)
+
+ // Request a greeting message.
+ <ins>message, err := greetings.Hello("Gladys")</ins>
+ // If an error was returned, print it to the console and
+ // exit the program.
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // If no error was returned, print the returned message
+ // to the console.
+ fmt.Println(message)
+}</pre>
+ </li>
+
+ <li>
+ At the command line, in the hello directory, run hello.go to confirm that
+ the code works. Run it multiple times, noticing that the greeting changes.
<pre>
-$ go build
-$ ./hello
+$ go run .
Great to see you, Gladys!
-$ ./hello
+$ go run .
Hi, Gladys. Welcome!
-$ ./hello
+$ go run .
Hail, Gladys! Well met!
-</pre
- >
+</pre>
</li>
</ol>
<p>
- That's an introduction to a Go slice. To get even more use out of this type,
- you'll use a slice to greet multiple people. That's in the tutorial's
- <a href="greetings-multiple-people.html">next topic</a>.
+ Next, you'll use a slice to greet multiple people.
</p>
<p class="Navigation">
- <a class="Navigation-prev" href="handle-errors.html"
+ <a class="Navigation-prev" href="/doc/tutorial/handle-errors.html"
>< Return and handle an error</a
>
- <a class="Navigation-next" href="greetings-multiple-people.html"
+ <a class="Navigation-next" href="/doc/tutorial/greetings-multiple-people.html"
>Return greetings for multiple people ></a
>
</p>