05: Basic Syntax: Packages

WARNING This exercise is in DRAFT status, so there may be errors. If you find any, please email me at help@learncodethehardway.com so I can fix them.

Go organizes code into modules and packages. Your whole projext ex04 is a module, and other people's code that you install is also called a module. A package is a component inside a module that you use, but this gets a little confusing because your own code also has packages you can create. In this exercise I'll try to give a simple introduction so you can start using modules and packages early.

Go Got it Wrong

I want to explain that Go inverted the names people normally use for this concept. In every other language you install other people's "packages" and inside those packages are "modules." Go however decided that you would install other people's "modules" and that inside those are "packages."

It's confusing, and if you also do JavaScript, Python, or many other languages, you'll have to get used to this being inverted.

What is a Module?

In Go a module is a container for code, and that code is typically organized into packages. You'll usually get a module from someone else, as either a published package or as part of the Go standard library.

In your ex03 code your module was named MY/ex03. Open your ex03/go.mod file to see that's what specified at the top:

View Source file ex05/go.mod Only

module MY/ex03

go 1.25.1

What is a Package?

A package is subsections of code inside a module. Think of it like a library. The library has rows of books in a certain category, and inside those rows are books. The rows of books in History is the "History Module" and the books in that section are "History's Packages." Your code is then the pages in those books.

What is a Dependency?

A dependency is simply the module that another module needs to work. If you install a module named network/tester it might need another module named github.com/testing/complete. The go mod tool will install these dependencies for you by looking at what each module needs and getting it from the internet.

Your ex03/main.go file has an import "fmt" line which makes it depend on the fmt package. This package lives in the standard library module and is available in all Go projects.

Using go mod

Go comes with a handy tool called go mod that attempts to automatically manage your modules. It will download modules you need, and also download all of the dependencies...even if you don't need them. I also say that go mod "attempts" to automatically manage your modules because there's been a few times when it refuses to update or remove things when asked, but 90% of the time it's correct.

When you created your first project you ran go mod init MY/ex03 to create your project's module. Later we'll use go mod tidy to add dependencies we need to complete projects.

Installing and Using a Tool

You can install a very useful tool called pkgsite to have access to Go's documentation locally. It also gives you access to the documentation for anything you use. The easiest way to install a tool is:

1. Run go install golang.org/x/pkgsite/cmd/pkgsite@latest.
2. This will install pkgsite into your GOBIN directory so you can simply run it like any other command line tool in your Terminal.
3. Once that's done you can type pkgsite -open while in any of your project directories and it will gather your documentation and open a browser.

The other way to install a tool is with go get -tool but I'll cover that another time.

Creating a Sub-Package

Go only has modules and packages, but I like to call code that's organized in your packages a sub-package. This isn't official but I find it helps make a difference between packages you're using and your own code you're working on. A "sub-package' is simply a directory in your code that you place .go files. All of these files need to have the first line with the same name for the package.

To try this feature follow these steps in your ex03 directory:

First, Create a directory with:

mkdir testpkg

2. Create a file in testpkg with the code below:

View Source file ex05/testpkg/thing.go Only

package testpkg

import (
    "fmt"
)

func Test() {
    fmt.Println("Testing Testing 123")
}

3. Then modify your main.go file like this:

View Source file ex05/main.go Only

package main

import (
    "fmt"
    "MY/ex03/testpkg"
)

func main() {
    fmt.Println("Hello World")
    testpkg.Test()
}

The change I made there is in the import statement and added MY/ex03/testpkg. If you did it right then you should be able to build and get new output:

go build .
./ex03

Give it a try but don't worry if this is over your head right now. It'll make more sense as we continue.

Possible Footguns

A "footgun" is a feature of a programming language that makes it easy to shoot your foot off if you're not careful. With Go if you have something other than package main at the top of your main.go file then go build . will build nothing. Try it out by changing the first line of ex03.go to this:

package test

Remove the ex03 binary with rm ex03 and then run go build . again. If you look in the directory with ls you'll see that nothing is created, even though you told go to build. Remember this next time it seems like "go is doing nothing." It's probably this.

Next Steps

Don't worry if you don't understand all of this now. You'll get plenty of practice as we continue with the course. The next exercise will finally get back to actually writing Go code.