Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc/code.html: update code.html to use go modules #28218

Open
wants to merge 2 commits into
base: master
from
Open
Changes from all commits
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -26,13 +26,25 @@ <h2 id="Organization">Code organization</h2>

<h3 id="Overview">Overview</h3>

<p>
When it comes to structuring our Go projects, we have two options
to choose from. We can either leverage the more traditional <i>GOPATH</i>,
or we could use <i>modules</i> which have recently been added to the language.
</p>

<p>
If you are just starting out with Go, then it is recommended that you start your
journey into Go using the new modules feature.
</p>

<ul>
<li>Go programmers typically keep all their Go code in a single <i>workspace</i>.</li>
<li>A workspace contains many version control <i>repositories</i>
(managed by Git, for example).</li>
<li>Each repository contains one or more <i>packages</i>.</li>
<li>Each repository can contain one or more <i>modules</i>.</li>
<li>Each of these modules can contain one or more <i>packages</i>.</li>
<li>Each package consists of one or more Go source files in a single directory.</li>
<li>The path to a package's directory determines its <i>import path</i>.</li>
<li>The path to a package is determined by a combination of the module path in the go.mod file,
and the relative path from the go.mod file to the package directory.</li>
</ul>

<p>
@@ -41,6 +53,20 @@ <h3 id="Overview">Overview</h3>
control repositories.
</p>

<h4 id="GOPATH">The GOPATH Way</h4>

<p>
If you choose to use the <i>GOPATH</i> over <i>modules</i>, then you should be aware of
some subtle differences in the organization of your Go projects.
By choosing to use the <i>GOPATH</i>, you will be constrained to
developing your applications in a folder structure underneath your <i>GOPATH</i>.
</p>

<p>
<b>Note: </b>For the rest of this document, I'll be highlighting the differences and
showing both methods of approaching our task.
</p>

<h3 id="Workspaces">Workspaces</h3>

<p>
@@ -125,7 +151,7 @@ <h3 id="GOPATH">The <code>GOPATH</code> environment variable</h3>
</p>

<p>
If you would like to work in a different location, you will need to
If you would like to work in a different location, you can choose to use
<a href="https://golang.org/wiki/SettingGOPATH">set <code>GOPATH</code></a>
to the path to that directory.
(Another common setup is to set <code>GOPATH=$HOME</code>.)
@@ -202,25 +228,47 @@ <h3 id="ImportPaths">Import paths</h3>
</p>

<p>
We'll use <code>github.com/user</code> as our base path. Create a directory
inside your workspace in which to keep source code:
Create a new directory on your machine in a location you find most convenient, this
will contain all of the source code for our Go program:
</p>

<pre>
$ <b>mkdir -p $GOPATH/src/github.com/user</b>
$ <b>mkdir -p ~/myproject/hello</b> // using Go Modules.
$ <b>mkdir -p $GOPATH/src/myproject/hello</b> // Using the GOPATH.
</pre>


<h3 id="Command">Your first program</h3>

<p>
To compile and run a simple program, first choose a package path (we'll use
<code>github.com/user/hello</code>) and create a corresponding package directory
inside your workspace:
<code>github.com/user/hello</code>) and create a new directory on your machine in which your Go program will live.
<b>Note:</b> you should ensure this directory lies outside your <code>$GOPATH</code> unless you have explicitly set
<code>GO111MODULE</code> to <code>on</code>. You can find more about this here: <a href="https://golang.org/wiki/Modules#how-to-use-modules">How to Use Modules</a>
</p>

<pre>
$ <b>mkdir -p ~/myproject/hello</b>
$ <b>cd ~/myproject/hello</b>
$ <b>go mod init github.com/user/hello</b>
</pre>

<p>
This will generate a <code>go.mod</code> file within your project's root directory.
The <code>go.mod</code> file will contain the name of our newly created module, in this case,
<code>github.com/user/hello</code>.
</p>

<pre>
$ <b>mkdir $GOPATH/src/github.com/user/hello</b>
module github.com/user/hello
</pre>

<p>
If we to do this using the <i>GOPATH</i>, there would be some subtle differences:
</p>

<pre>
$ <b>mkdir -p $GOPATH/src/github.com/user/hello</b>
$ <b>cd $GOPATH/src/github.com/user/hello</b>
</pre>

<p>
@@ -239,28 +287,28 @@ <h3 id="Command">Your first program</h3>
</pre>

<p>
Now you can build and install that program with the <code>go</code> tool:
Now you can build that program with the <code>go</code> tool:
</p>

<pre>
$ <b>go install github.com/user/hello</b>
$ <b>go build ./...</b> # Using Go Modules
$ <b>go build main.go</b> # Using the GOPATH
</pre>

<p>
Note that you can run this command from anywhere on your system. The
<code>go</code> tool finds the source code by looking for the
<code>github.com/user/hello</code> package inside the workspace specified by
<code>GOPATH</code>.
</p>
<p>This will compile your Go code into a <code>hello</code> binary that can be executed.</p>

<pre>
$ <b>./hello</b>
<b>Hello, world.</b>
</pre>

<p>
You can also omit the package path if you run <code>go install</code> from the
package directory:
Note that you can also use the <code>install</code> command to add your compiled binary
executable to <code>$HOME/go/bin/hello</code>.
</p>

<pre>
$ <b>cd $GOPATH/src/github.com/user/hello</b>
$ <b>go install</b>
$ <b>go install github.com/user/hello</b>
</pre>

<p>
@@ -302,9 +350,9 @@ <h3 id="Command">Your first program</h3>
</p>

<pre>
$ <b>cd $GOPATH/src/github.com/user/hello</b>
$ <b>cd ~/myproject/hello</b>
$ <b>git init</b>
Initialized empty Git repository in /home/user/work/src/github.com/user/hello/.git/
Initialized empty Git repository in ~/myproject/hello/.git/
$ <b>git add hello.go</b>
$ <b>git commit -m "initial commit"</b>
[master (root-commit) 0b4507d] initial commit
@@ -324,12 +372,14 @@ <h3 id="Library">Your first library</h3>
</p>

<p>
Again, the first step is to choose a package path (we'll use
<code>github.com/user/stringutil</code>) and create the package directory:
Add a new directory within your <code>~/myproject/hello</code> directory
called <code>stringutil</code>. This directory will contain all of our new
library code
</p>

<pre>
$ <b>mkdir $GOPATH/src/github.com/user/stringutil</b>
$ <b>mkdir -p ~/myproject/hello/stringutil</b> # Using Go Modules
$ <b>mkdir -p $GOPATH/src/myproject/hello/stringutil</b> # Using the GOPATH
</pre>

<p>
@@ -352,19 +402,11 @@ <h3 id="Library">Your first library</h3>
</pre>

<p>
Now, test that the package compiles with <code>go build</code>:
</p>

<pre>
$ <b>go build github.com/user/stringutil</b>
</pre>

<p>
Or, if you are working in the package's source directory, just:
Now, test that your package compiles with <code>go build</code>:
</p>

<pre>
$ <b>go build</b>
$ <b>go build github.com/user/hello/stringutil</b>
</pre>

<p>
@@ -373,9 +415,9 @@ <h3 id="Library">Your first library</h3>
</p>

<p>
After confirming that the <code>stringutil</code> package builds,
modify your original <code>hello.go</code> (which is in
<code>$GOPATH/src/github.com/user/hello</code>) to use it:
Once you have verified your new package builds, you can then
modify your original <code>hello.go</code> (which is in either
<code>~/myProject/hello</code>, or <code>$OPATH/src/myProject/hello</code>) to use it:
</p>

<pre>
@@ -384,7 +426,7 @@ <h3 id="Library">Your first library</h3>
import (
"fmt"

<b>"github.com/user/stringutil"</b>
<b>"github.com/user/hello/stringutil"</b>
)

func main() {
@@ -410,18 +452,34 @@ <h3 id="Library">Your first library</h3>
</pre>

<p>
After the steps above, your workspace should look like this:
After the steps above, your workspace should look like this if you are
using Go Modules:
</p>

<pre>
bin/
hello # command executable
$GOPATH/bin/
hello # command executable

~/myproject/hello/
stringutil/
reverse.go # package source
hello.go # command source
go.mod
go.sum
</pre>

<p>
Or this, if you are using the <i>GOPATH</i>
</p>

<pre>
/bin/
hello # command executable
src/
github.com/user/
hello/
hello.go # command source
stringutil/
reverse.go # package source
myproject/hello/
hello.go # command source
stringutil/
reverse.go # package source
</pre>

<h3 id="PackageNames">Package names</h3>
@@ -460,7 +518,6 @@ <h3 id="PackageNames">Package names</h3>
Go's naming conventions.
</p>


<h2 id="Testing">Testing</h2>

<p>
@@ -479,8 +536,8 @@ <h2 id="Testing">Testing</h2>

<p>
Add a test to the <code>stringutil</code> package by creating the file
<code>$GOPATH/src/github.com/user/stringutil/reverse_test.go</code> containing
the following Go code.
<code>reverse_test.go</code> within the same location as your existing
<code>reverse.go</code> file containing the following Go code.
</p>

<pre>
@@ -510,8 +567,8 @@ <h2 id="Testing">Testing</h2>
</p>

<pre>
$ <b>go test github.com/user/stringutil</b>
ok github.com/user/stringutil 0.165s
$ <b>go test github.com/user/hello/stringutil</b>
ok github.com/user/hello/stringutil 0.165s
</pre>

<p>
@@ -521,7 +578,7 @@ <h2 id="Testing">Testing</h2>

<pre>
$ <b>go test</b>
ok github.com/user/stringutil 0.165s
ok github.com/user/hello/stringutil 0.165s
</pre>

<p>
@@ -562,22 +619,24 @@ <h2 id="remote">Remote packages</h2>
</p>

<pre>
bin/
hello # command executable
src/
github.com/golang/example/
.git/ # Git repository metadata
hello/
hello.go # command source
~/myProject/hello/
stringutil/
reverse.go # package source
reverse_test.go # test source
hello.go # command source
go.mod
go.sum

$GOPATH/
bin/
hello # command executable
src/github.com/golang/
example/
stringutil/
reverse.go # package source
reverse_test.go # test source
github.com/user/
reverse.go # package source
reverse_test.go # test source
hello/
hello.go # command source
stringutil/
reverse.go # package source
reverse_test.go # test source
...
</pre>

<p>
@@ -606,6 +665,45 @@ <h2 id="remote">Remote packages</h2>
</p>


<h2 id="Modules">Modules</h2>

<p>
Go recently introduced support for modules in the v1.12 release. A <i>Module</i> is
a collection of related Go packages that are versioned together as a single unit.
</p>

<p>
You'll tend to find one module map to one version-control repository. However, there are
exceptions to this rule.
</p>

<p>
With the introduction of modules came the introduction of the <code>go.mod</code> file which
encapsulates a module's definition as well as it's dependencies like so:
</p>

<pre>
module github.com/my/thing

require (
github.com/some/dependency v1.2.3
github.com/another/dependency/v4 v4.0.0
)
</pre>

<p>
We have already seen how to initialize a project with the <code>go mod init github.com/user/hello</code>
command at the root of our project. And when we include new dependencies at the
top of any of our Go packages, the <code>go build</code> command will automatically
fetch in any of the dependencies needed for our program before compiling.
</p>

<p>
For more help, run <code>go mod help</code> to see a full list of commands and see the
<a href="https://github.com/golang/go/wiki/Modules">Go Modules</a> Wiki page for more detail.
</p>


<h2 id="next">What's next</h2>

<p>
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.