diff options
| author | Steve Traut <straut@google.com> | 2021-03-01 10:42:43 -0500 |
|---|---|---|
| committer | Steve Traut <straut@google.com> | 2021-03-02 21:51:57 +0000 |
| commit | 02ef8fa5ddb8111aa8752ffb8267e67c4e209649 (patch) | |
| tree | 13085d9e3c6b067ff0aa923aabcd93c5dc7975b3 /_content/doc | |
| parent | 65c83740113547629052d38de46b57b708ec6e2b (diff) | |
| download | go-x-website-02ef8fa5ddb8111aa8752ffb8267e67c4e209649.tar.xz | |
_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>
Diffstat (limited to '_content/doc')
| -rw-r--r-- | _content/doc/code.html | 19 | ||||
| -rw-r--r-- | _content/doc/modules/developing.md | 23 | ||||
| -rw-r--r-- | _content/doc/modules/gomod-ref.md | 154 | ||||
| -rw-r--r-- | _content/doc/modules/major-version.md | 8 | ||||
| -rw-r--r-- | _content/doc/modules/managing-dependencies.md | 114 | ||||
| -rw-r--r-- | _content/doc/modules/managing-source.md | 21 | ||||
| -rw-r--r-- | _content/doc/modules/publishing.md | 8 | ||||
| -rw-r--r-- | _content/doc/modules/release-workflow.md | 45 | ||||
| -rw-r--r-- | _content/doc/modules/version-numbers.md | 58 | ||||
| -rw-r--r-- | _content/doc/tutorial/add-a-test.html | 42 | ||||
| -rw-r--r-- | _content/doc/tutorial/call-module-code.html | 224 | ||||
| -rw-r--r-- | _content/doc/tutorial/compile-install.html | 124 | ||||
| -rw-r--r-- | _content/doc/tutorial/create-module.html | 81 | ||||
| -rw-r--r-- | _content/doc/tutorial/getting-started.html | 48 | ||||
| -rw-r--r-- | _content/doc/tutorial/greetings-multiple-people.html | 71 | ||||
| -rw-r--r-- | _content/doc/tutorial/handle-errors.html | 29 | ||||
| -rw-r--r-- | _content/doc/tutorial/index.html | 7 | ||||
| -rw-r--r-- | _content/doc/tutorial/module-conclusion.html | 31 | ||||
| -rw-r--r-- | _content/doc/tutorial/random-greeting.html | 101 |
19 files changed, 653 insertions, 555 deletions
diff --git a/_content/doc/code.html b/_content/doc/code.html index a1b9bd20..99a1729a 100644 --- a/_content/doc/code.html +++ b/_content/doc/code.html @@ -78,7 +78,7 @@ go: creating new go.mod: module example.com/user/hello $ cat go.mod module example.com/user/hello -go 1.14 +go 1.16 $ </pre> @@ -323,16 +323,17 @@ func main() { </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 @@ Hello, Go! $ 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 bcaabfe8..c1cbe4cd 100644 --- a/_content/doc/modules/developing.md +++ b/_content/doc/modules/developing.md @@ -25,7 +25,7 @@ To support developing, publishing, and using modules, you use: [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 @@ To support developing, publishing, and using modules, you use: 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 @@ and versioning workflow](release-workflow). 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 @@ functions in the module while the module is still in development. For more 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 @@ along with the module version number you use to tag the module for release, to 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 @@ runs the `go get` command to download its source code to compile with. 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 @@ For more on developing major version updates, see [Developing a major version 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 bdbe853e..7a7c2b7d 100644 --- a/_content/doc/modules/gomod-ref.md +++ b/_content/doc/modules/gomod-ref.md @@ -8,9 +8,12 @@ properties, including its dependencies on other modules and on versions of Go. 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 @@ These properties include: 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 @@ $ go mod init example.com/mymodule 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 @@ replace example.com/thatmodule => ../thatmodule 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 @@ with the module version. module example.com/mymodule/v2 ``` -### Notes +### Notes {#module-notes} + +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. + +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. -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. +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. -<a id="go" ></a> -## go +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 @@ Specifies the minimum Go version required by the module. <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 @@ minimum version of the module required. v0.0.0-20200921210052-fa0125251cc4.</dd> </dl> -### Examples +### Examples {#require-examples} * Requiring a released version v1.2.3: ``` @@ -163,7 +181,7 @@ minimum version of the module required. 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 @@ command. 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 @@ replacement path when resolving the dependency. 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 @@ replacement path when resolving the dependency. 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 @@ replacement path when resolving the dependency. ``` 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 @@ replacement path. 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 @@ The `replace` directive can be useful in situations such as the following: 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 @@ dependency graph. 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 @@ Use the `exclude` and `replace` directives to control build-time dependency 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 fe1555bf..9143634f 100644 --- a/_content/doc/modules/major-version.md +++ b/_content/doc/modules/major-version.md @@ -13,7 +13,7 @@ different meaning for a module's users. Those users rely on these differences to 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 @@ version numbers, see [Module version numbering](version-numbers). * 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 @@ the following: 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 @@ the source for your new version: * 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 671ec5ad..1385a6fe 100644 --- a/_content/doc/modules/managing-dependencies.md +++ b/_content/doc/modules/managing-dependencies.md @@ -16,24 +16,23 @@ useful. **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 @@ each, see the sections in this topic. 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 @@ This process is supported by: 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 @@ This process is supported by: 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 @@ After your code imports the package, enable dependency tracking and get the 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 @@ run the command as in the following example: $ 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 @@ project. 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 @@ was published -- for example, the developer changed the contents of the commit -- 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 might want to do this if: * 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 @@ command](https://golang.org/cmd/go/#hdr-Add_dependencies_to_current_module_and_i ``` 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 @@ your module's dependencies, along with the latest version available for that 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 @@ Here are a couple of examples. $ 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 @@ available versions, then add a different version as a dependency. [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 @@ about removed modules. $ 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 might want to do this when: * 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 @@ as the code that requires it. You might find this useful when you are: 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 @@ require example.com/theirmodule v0.0.0-unpublished 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 @@ $ go get -d example.com/theirmodule@v0.0.0-unpublished **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 @@ replace example.com/theirmodule v1.2.3 => example.com/myfork/theirmodule v1.2.3- 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 @@ $ go mod edit -replace=example.com/theirmodule@v1.2.3=example.com/myfork/theirmo **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 @@ whose source is in a git repository. $ 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 @@ $ go get example.com/theirmodule@none 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 ac14da33..cb41dceb 100644 --- a/_content/doc/modules/managing-source.md +++ b/_content/doc/modules/managing-source.md @@ -14,7 +14,7 @@ workflow](release-workflow). 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 @@ Mercurial, Bazaar, and Fossil. 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 @@ rely on naming rules that have repository paths and repository tags indicating a 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 @@ code imports, the command does the following: 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 commit -m "mycode: initial commit" $ 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 @@ minor and patch versions, branch into new major versions, and so on. However, if 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 @@ directory path. 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 @@ Each subdirectory that is a module root directory must have its own go.mod file. 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 db5ec4ff..f98f07c3 100644 --- a/_content/doc/modules/publishing.md +++ b/_content/doc/modules/publishing.md @@ -19,9 +19,9 @@ a new version. * 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 @@ Use the following steps to publish a module. ``` 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 78f0cb62..097a57af 100644 --- a/_content/doc/modules/release-workflow.md +++ b/_content/doc/modules/release-workflow.md @@ -13,11 +13,11 @@ modules](developing). **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 @@ example new module. For more about each step, see the sections in this topic. 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 @@ example new module. For more about each step, see the sections in this topic. 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 @@ the `replace` directive in the client module's go.mod file. For more 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 @@ You publish a pre-release by tagging the module code in your repository, 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 @@ You publish an unstable release by tagging the module code in your repository, 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 @@ does not signal stability or backward compatibility guarantees. As a result, 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 @@ You publish a first stable release by tagging the module code in your 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 @@ upgrading to the patch of your module could wind up accidentally pulling in a 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 @@ You publish a patch release by tagging the module code in your repository, 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 @@ this kind of release guarantees backward compatibility and stability for 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 @@ You publish a minor release by tagging the module code in your repository, 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 @@ using the module's previous versions. 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 @@ steps. 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 @@ steps. 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 ca1acddc..70ec30bf 100644 --- a/_content/doc/modules/version-numbers.md +++ b/_content/doc/modules/version-numbers.md @@ -10,18 +10,23 @@ changes since the preceding release. 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 @@ module's stability and backward compatibility. </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 @@ The version number can take one of the following forms: **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 @@ semantic version tag yet. 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 @@ _baseVersionPrefix_-_timestamp_-_revisionIdentifier_ * **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 @@ break backward compatibility for code using the v0 versions. For this reason, a 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 @@ vx.x.x-beta.2 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 @@ In other words, this version might include enhancements through new functions 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 @@ An update that increments this number is only for minor changes such as bug 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 @@ module example.com/mymodule/v2 v2.0.0 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 d52f3d3b..dffd4924 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 @@ func TestHelloEmpty(t *testing.T) { 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 @@ func TestHelloEmpty(t *testing.T) { 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 @@ func TestHelloEmpty(t *testing.T) { <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 @@ FAIL example.com/greetings 0.182s </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 3c3602b8..bce43d72 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 @@ cd hello </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 @@ func main() { message := greetings.Hello("Gladys") fmt.Println(message) } -</pre - > +</pre> <p> In this code, you: @@ -71,16 +99,16 @@ func main() { <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 @@ func main() { </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> - - <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> + <p> + After the command completes, the <code>example.com/hello</code> + module's go.mod file should look like this: + </p> - <pre> -module hello + <pre>module example.com/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> + 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 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. + 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 -Hi, Gladys. Welcome! -</pre - > - </li> - - <li> - On Windows: - - <pre> -$ hello.exe + <pre> +$ go run . 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 5395ae51..4d596185 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 @@ go list -f '{{.Target}}' 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 @@ export PATH=$PATH:/path/to/your/install/directory 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 @@ set PATH=%PATH%;C:\path\to\your\install\directory <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 @@ go env -w GOBIN=C:\path\to\your\bin 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 @@ map[Darrin:Hail, Darrin! Well met! Gladys:Great to see you, Gladys! Samantha:Hai </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 cf6558c0..3dbe35f4 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 @@ cd %HOMEPATH% <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 @@ cd greetings <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 @@ go: creating new go.mod: module example.com/greetings > <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 @@ func Hello(name string) string { 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 @@ message = fmt.Sprintf("Hi, %v. Welcome!", name) </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 @@ message = fmt.Sprintf("Hi, %v. Welcome!", name) </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 fc05867f..eff1bb69 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 @@ cd hello </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 @@ func main() { </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 @@ Hello, World! <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 @@ func main() { 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 @@ Don't communicate by sharing memory, share memory by communicating. <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 8100c080..1d83192d 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 @@ func randomFormat() string { 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 @@ func main() { <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 @@ func main() { </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 @@ map[Darrin:Hail, Darrin! Well met! Gladys:Hi, Gladys. Welcome! Samantha:Hail, Sa <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 4dfd4b13..76f7a4f3 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 @@ func Hello(name string) <ins>(</ins>string<ins>, error)</ins> { 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 @@ func main() { 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 @@ func main() { <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 @@ func main() { </p> <pre> -$ go run hello.go +$ go run . greetings: empty name exit status 1 </pre @@ -172,17 +171,19 @@ exit status 1 </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 80f9c018..1bbb78d0 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 00000000..f86af3af --- /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 d5a45be6..c6c8da72 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 @@ func randomFormat() string { <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 @@ func randomFormat() string { <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> |
