content/static/doc/tutorial/call-module-code.html

<!--{
    "Title": "Call your code from another module",
    "Path":  "/doc/tutorial/call-module-code"
}-->

<p>
  In the <a href="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="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>
      For example, if your current directory in the command prompt is the
      greetings directory, you could use the following commands:
    </p>

    <pre>
cd ..
mkdir hello
cd 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 go 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).
      </li>
      <li>
        Get a greeting by calling the <code>greetings</code> package’s
        <code>Hello</code> function.
      </li>
    </ul>
  </li>

  <li>
    Create a new module for this hello package.

    <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.
    </p>

    <p>
      To do that, make a small change to <code>hello</code> module’s go.mod
      file.
    </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.

        <pre>
module hello

go 1.14

<ins>replace example.com/greetings => ../greetings</ins>
</pre>

        <p>
          Here, the
          <a href="https://golang.org/ref/mod#tmp_15"
            ><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.

        <pre>
$ go build
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>
module hello

go 1.14

replace example.com/greetings => ../greetings

<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="https://golang.org/ref/mod#tmp_13"
            ><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.
        </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.
        </p>

        <pre>require example.com/greetings v1.1.0</pre>
      </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:

        <pre>
$ ./hello
Hi, Gladys. Welcome!
</pre
        >
      </li>

      <li>
        On Windows:

        <pre>
$ hello.exe
Hi, Gladys. Welcome!
</pre
        >
      </li>
    </ul>
  </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.
</p>

<p class="Navigation">
  <a class="Navigation-prev" href="create-module.html"
    >&lt; Create a Go module</a
  >
  <a class="Navigation-next" href="handle-errors.html"
    >Return and handle an error &gt;</a
  >
</p>