_content/doc/tutorial/call-module-code.html

<!--{
    "Title": "Call your code from another module"
}-->

<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>