blob: 16b1f4023cb027df7d99461aee1cf515c722fc5a [file] [log] [blame]
<!--{
"Title": "Call your code from another module",
"Breadcrumb": true
}-->
<p>
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
<code>greetings</code> module.
</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>
<ol>
<li>
Create a <code>hello</code> directory for your Go module source code. This
is where you'll write your caller.
<p>
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>&lt;home&gt;/
|-- greetings/
|-- hello/</pre>
<p>
For example, if your command prompt is in the greetings directory, you
could use the following commands:
</p>
<pre>
cd ..
mkdir hello
cd hello
</pre
>
</li>
<li>
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>
<li>
Write code to call the <code>Hello</code> function, then print the
function's return value.
<p>
To do that, paste the following code into hello.go.
</p>
<pre>
package main
import (
"fmt"
"example.com/greetings"
)
func main() {
// Get a greeting message and print it.
message := greetings.Hello("Gladys")
fmt.Println(message)
}
</pre>
<p>
In this code, you:
</p>
<ul>
<li>
Declare a <code>main</code> package. In Go, code executed as an
application must be in a <code>main</code> package.
</li>
<li>
Import two packages: <code>example.com/greetings</code> and
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
<code>Hello</code> function.
</li>
</ul>
</li>
<li>
Edit the <code>example.com/hello</code> module to use your local
<code>example.com/greetings</code> module.
<p>
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, 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>
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 example.com/hello
go 1.16
<ins>replace example.com/greetings => ../greetings</ins>
</pre>
</li>
<li>
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 mod tidy
go: found example.com/greetings in example.com/greetings v0.0.0-00010101000000-000000000000
</pre>
<p>
After the command completes, the <code>example.com/hello</code>
module's go.mod file should look like this:
</p>
<pre>module example.com/hello
go 1.16
replace example.com/greetings => ../greetings
<ins>require example.com/greetings v0.0.0-00010101000000-000000000000</ins></pre>
<p>
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 <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>
At the command prompt in the <code>hello</code> directory, run your code to
confirm that it works.
<pre>
$ go run .
Hi, Gladys. Welcome!
</pre>
</li>
</ol>
<p>
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="/doc/tutorial/create-module.html"
>&lt; Create a Go module</a
>
<a class="Navigation-next" href="/doc/tutorial/handle-errors.html"
>Return and handle an error &gt;</a
>
</p>