Skip to content
Permalink
Browse files

Attempting to explain both GOPATH and Go Modules

  • Loading branch information...
elliotforbes committed Jan 12, 2019
1 parent 28bbe51 commit 012ead1e931959fa1f237e9d126b32ec28704003
Showing with 62 additions and 9 deletions.
  1. +62 −9 doc/code.html
@@ -26,6 +26,17 @@ <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>A workspace contains many version control <i>repositories</i>
(managed by Git, for example).</li>
@@ -42,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>
@@ -126,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>.)
@@ -208,7 +233,8 @@ <h3 id="ImportPaths">Import paths</h3>
</p>

<pre>
$ <b>mkdir -p ~/myproject/hello</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>
@@ -219,6 +245,7 @@ <h3 id="Command">Your first program</h3>
<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>
@@ -235,6 +262,15 @@ <h3 id="Command">Your first program</h3>
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>
Next, create a file named <code>hello.go</code> inside that directory,
containing the following Go code.
@@ -255,7 +291,8 @@ <h3 id="Command">Your first program</h3>
</p>

<pre>
$ <b>go build ./...</b>
$ <b>go build ./...</b> # Using Go Modules
$ <b>go build main.go</b> # Using the GOPATH
</pre>

<p>This will compile your Go code into a <code>hello</code> binary that can be executed.</p>
@@ -341,7 +378,8 @@ <h3 id="Library">Your first library</h3>
</p>

<pre>
$ <b>mkdir ~/myproject/hello/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>
@@ -378,8 +416,8 @@ <h3 id="Library">Your first library</h3>

<p>
Once you have verified your new package builds, you can then
modify your original <code>hello.go</code> (which is in
<code>~/myProject/hello</code>) to use it:
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>
@@ -414,7 +452,8 @@ <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>
@@ -429,6 +468,20 @@ <h3 id="Library">Your first library</h3>
go.sum
</pre>

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

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

<h3 id="PackageNames">Package names</h3>

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

<p>
Add a test to the <code>stringutil</code> package by creating the file
<code>~/myproject/hello/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>

0 comments on commit 012ead1

Please sign in to comment.
You can’t perform that action at this time.