How Go code is organized

Every program in this course was one file, main.go. Real Go projects have many files, and Go groups them into packages. A package is a folder of .go files that work together. Every file starts with the name of its package.

package main is special. A package named main with a function named main is a program you can run. Every other package is a library: code that programs can use, but cannot run on its own.

Using a package

You have used packages from Go's standard library, the packages that come with Go, since the first lesson. import brings a package in, and you then write its name, a dot, and the thing you want:

package main

import (
	"fmt"
	"math"
	"strings"
)

func main() {
	fmt.Println(strings.ToUpper("go"))
	fmt.Println(math.Sqrt(81))
}

Output:

GO
9

An import path can have several parts, like encoding/json. In the code you use only the last part, json.

Capital letters export a name

Go has no public or private keywords. Instead, the first letter of a name decides who can use it:

Name starts withWho can use it
a capital letter, like ToUpperany package that imports this one
a small letter, like toUpperonly code inside the same package

A name with a capital letter is exported. You met this rule in the JSON lesson, where only exported struct fields were encoded. Here is what happens if you try a name that strings does not export:

package main

import (
	"fmt"
	"strings"
)

func main() {
	fmt.Println(strings.toUpper("go"))
}

Output:

# command-line-arguments
./main.go:9:22: undefined: strings.toUpper

The compiler cannot see a small-letter name from outside its package, so it reports it as undefined. You get the same error for a small-letter name that really exists inside strings, such as strings.indexFunc. This keeps a package's helper code private. The package can change those parts later without breaking the programs that use it.

Your own packages

A bigger project puts related code in its own folder and package. Here a shop program keeps its price code in a package called prices:

shop/
├── go.mod
├── main.go         package main
└── prices/
    └── prices.go   package prices

prices/prices.go exports one function and keeps one constant private:

package prices

const taxRate = 0.2

func WithTax(price float64) float64 {
	return price * (1 + taxRate)
}

main.go imports the package by its full path and calls prices.WithTax. It cannot use prices.taxRate.

package main

import (
	"example.com/shop/prices"
	"fmt"
)

func main() {
	fmt.Println(prices.WithTax(10))
}

Modules

The full path example.com/shop/prices comes from the module. A module is a whole project: a set of packages that are built and versioned together. Its root folder has a file named go.mod, which stores the module's name, the Go version, and the other modules it uses. You create it with one command in the project folder:

go mod init example.com/shop

The module name is usually where the code lives online, such as a GitHub address. To use a package that someone else wrote, you run go get with its path. Go downloads it and records the version in go.mod. go mod tidy adds anything missing and removes what you no longer use.

The editor in this course runs one main.go file, so you do not need go.mod here. You will need it as soon as you start a project on your own computer.

In the exercise, choose the function name that code in another package can use.