Packages, exported names and initialisation

In the kirana module of this lesson, pricing.Total(bill) works from another package and pricing.tax(4800) stops the build, and the only difference between them is the case of the first letter. Go has no public or private keyword: folders make packages, a capital letter exports a name, and two more rules decide who may import whom, the go command’s rule for folders named internal and the specification’s ban on packages that import each other.

You will split a program into packages, decide what each one exports, keep a package inside your own tree, break an import cycle, and predict the order in which a program’s packages start before main runs. Every message quoted here was printed by Go 1.27.1.

A package is one folder of files that share a name

The kirana module bills a customer of a kirana, a neighbourhood grocery shop in India, in paise. Its go.mod declares the module path example.com/kirana, and each folder below it that holds .go files is one package. A package is the set of .go files in one folder, compiled together: every file starts with the same package clause, and anything declared at the top level of one file, a function, a type, a variable or a constant, can be used by the other files of that folder without an import. Here are two of the packages:

// Package pricing works out what a customer pays, in paise.
package pricing

// Line is one line of a bill: what was bought, and how many.
type Line struct {
	Name       string
	Qty        int
	pricePaise int64 // the price of one item, set only by NewLine
}

// NewLine makes a bill line for qty items at pricePaise each.
func NewLine(name string, qty int, pricePaise int64) Line {
	return Line{Name: name, Qty: qty, pricePaise: pricePaise}
}

// Total adds up the lines and the tax on them, in paise.
func Total(lines []Line) int64 {
	var sum int64
	for _, l := range lines {
		sum += l.pricePaise * int64(l.Qty)
	}
	return sum + tax(sum)
}

// tax is 5 per cent of amount in this example, rounded to the nearest paisa.
func tax(amount int64) int64 {
	return (amount*5 + 50) / 100
}

// Command billing prints one customer's bill.
package main

import (
	"fmt"

	"example.com/kirana/internal/ledger"
	"example.com/kirana/pricing"
)

func main() {
	bill := []pricing.Line{
		pricing.NewLine("rice 1 kg", 2, 6400),
		pricing.NewLine("toor dal 500 g", 1, 8950),
	}
	total := pricing.Total(bill)
	ledger.Record(total)
	fmt.Printf("total: Rs %d.%02d\n", total/100, total%100)
	fmt.Println(ledger.Summary())
}

The program in cmd/billing says package main; the other folders say the name their code is used by, such as package pricing. A package’s import pathimport path: The string an import declaration names, such as example.com/kirana/pricing: the module path followed by the package's folder in the module. Standard-library packages, such as fmt, have no module path in front. is the module pathmodule path: The name on the module line of a go.mod file, such as example.com/kirana. It begins the import path of every package of the module and tells the go command where the module can be downloaded. joined with its folder, and go list ./... prints the import path of every package in the module:

from session import run

# The packages of the kirana module and their import paths, then the program that uses two of them.
run("""
cat kirana/go.mod
cd kirana && go list ./...
cd kirana && go run ./cmd/billing
""")

$ cat kirana/go.mod
module example.com/kirana

go 1.27
$ cd kirana && go list ./...
example.com/kirana/cmd/billing
example.com/kirana/cmd/peek
example.com/kirana/internal/ledger
example.com/kirana/pricing
$ cd kirana && go run ./cmd/billing
total: Rs 228.38
takings so far: Rs 228.38

The four paths are the four folders with example.com/kirana/ in front, and go run built the program from three of them and printed a bill of Rs 228.38. Step through the build of cmd/billing and watch each import line turn into a folder:

By convention a package is named after the last element of its import path, so example.com/kirana/internal/ledger is used as ledger.Record. Only main breaks the convention, because the program needs that name.

A capital first letter exports a name, and nothing else does

cmd/peek is a second program in the same module that reaches for two names pricing keeps to itself, the field pricePaise and the function tax. It does not compile:

from session import run

# cmd/peek reaches for an unexported field and an unexported function of package pricing.
run(
    """
cd kirana && go build ./cmd/peek
""",
    expect_failure=["cd kirana && go build ./cmd/peek"],
)

$ cd kirana && go build ./cmd/peek
# example.com/kirana/cmd/peek
cmd/peek/main.go:12:48: cannot refer to unexported field pricePaise in struct literal of type pricing.Line
cmd/peek/main.go:13:22: name tax not exported by package pricing
[exit status 1]

The compiler names both mistakes: cannot refer to unexported field pricePaise in struct literal of type pricing.Line, and name tax not exported by package pricing. The rule is short. A name is exportedexported name: A name that other packages can use. A Go name is exported when its first character is an upper-case letter and it is declared at the package level, or when it names a field or a method. when its first character is an upper-case letter, Unicode category Lu, and it is declared at the top level of the package, or is the name of a field or a method. Line, NewLine, Total, Name and Qty pass both tests; tax and pricePaise fail the first, so they are visible in every file of the pricing folder and in no other package.

The unexported field is deliberate. Other packages can read and set Name and Qty, but only code in pricing, such as NewLine, can read or set the price, so pricing decides how a price gets into a line, and it can change how it stores prices without breaking any caller.

internal/ keeps a package inside your own tree

An exported name can be used by any code that imports its package, even code in another module. Sometimes you want a package that every part of your module may share and nobody else may use, such as kirana’s ledger, which keeps the day’s takings. The go command has a rule for that, and no keyword is involved: an internal packageinternal package: A package in or below a folder named internal. The go command lets only code whose import path starts with the path of the folder above internal import it., one in or below a folder named internal, can be imported only by code whose import path starts with the path of the folder above internal.

rival is a second module next to kirana. Its go.mod points example.com/kirana at the folder beside it with a replace line, so the build reads kirana from disk, and its main.go imports the ledger:

from session import run

# rival is another module. Its go.mod points example.com/kirana at the folder next to it, and its main.go imports
# kirana's internal package.
run(
    """
cat rival/go.mod
cd rival && go build .
""",
    expect_failure=["cd rival && go build ."],
)

$ cat rival/go.mod
module example.com/rival

go 1.27

require example.com/kirana v0.0.0

replace example.com/kirana => ../kirana
$ cd rival && go build .
package example.com/rival
	main.go:7:2: use of internal package example.com/kirana/internal/ledger not allowed
[exit status 1]

The build stops at the import: use of internal package example.com/kirana/internal/ledger not allowed. The ledger’s parent folder is the module root, example.com/kirana, and example.com/rival does not start with it. Step through three packages that import the ledger:

This makes internal the place for code you share inside a module but do not want to support for others: other modules cannot import it, so you can rename, split or delete it without breaking anyone outside your tree.

An import cycle does not compile, so make the imports go one way

In the cafe module, Order’s Receipt method calls invoice.Render, and Render takes an orders.Order, so orders imports invoice and invoice imports orders, an import cycleimport cycle: Packages that import one another, directly or through other packages. Go refuses to build them, so the imports of a program always form a graph without loops.. The specification forbids that: a package may not import itself, directly or indirectly. cyclefix is the same module with one change, an interface declared in invoice:

// Package invoice formats receipts for anything that can be billed.
package invoice

import (
	"fmt"
	"strings"
)

// Billable is what invoice needs to know about an order, and no more.
type Billable interface {
	Lines() []string
	TotalPaise() int64
}

// Render formats a bill as one line.
func Render(b Billable) string {
	p := b.TotalPaise()
	return fmt.Sprintf("%s: Rs %d.%02d", strings.Join(b.Lines(), ", "), p/100, p%100)
}

// Package orders holds what a customer ordered.
package orders

import "example.com/cafe/invoice"

// Order is one customer's order.
type Order struct {
	Items []string
	Paise int64
}

// Lines and TotalPaise make Order an invoice.Billable.
func (o Order) Lines() []string   { return o.Items }
func (o Order) TotalPaise() int64 { return o.Paise }

// Receipt formats the order as a receipt.
func (o Order) Receipt() string { return invoice.Render(o) }

The session builds the module with the cycle, then runs the fixed one and lists what each package imports:

from session import run

# orders and invoice import each other in cycle/; in cyclefix/ invoice declares the interface it needs and imports
# nothing of the module, so the imports go one way.
run(
    """
cd cycle && go build ./...
cd cyclefix && go run ./cmd/cafe
cd cyclefix && go list -f '{{.ImportPath}} imports {{join .Imports ", "}}' ./...
""",
    expect_failure=["cd cycle && go build ./..."],
)

$ cd cycle && go build ./...
package example.com/cafe/invoice
	imports example.com/cafe/orders from invoice.go
	imports example.com/cafe/invoice from orders.go: import cycle not allowed
[exit status 1]
$ cd cyclefix && go run ./cmd/cafe
masala dosa, filter coffee: Rs 140.00
$ cd cyclefix && go list -f '{{.ImportPath}} imports {{join .Imports ", "}}' ./...
example.com/cafe/cmd/cafe imports example.com/cafe/orders, fmt
example.com/cafe/invoice imports fmt, strings
example.com/cafe/orders imports example.com/cafe/invoice

The first build failed with the whole loop spelled out, imports example.com/cafe/orders from invoice.go, then imports example.com/cafe/invoice from orders.go: import cycle not allowed. After the fix, invoice imports only fmt and strings, and the receipt printed. Step through the change:

There are two dependable fixes. The one shown asks for less: the package that needs something declares a small interface with only the methods it uses, and any type with those methods satisfies it without importing anything. The other moves what both packages share, here the Order type, into a third package that both import and that imports neither. Choose the interface when one package only calls a few methods of the other, and the third package when both really work on the same data.

Variables first, then init, package by package, before main

Before main runs, Go initialises every package of the program. Inside one package the package-level variablespackage-level variable: A variable declared outside every function. It exists for the whole run, and Go gives it its value before main starts, setting each one after the variables its value depends on. More in “Variables, short declarations and zero values” come first, then the init functionsinit function: A function named init, with no parameters and no results, declared at the package level. It runs once, after the package's variables have their values, and no code can call it.. The variables of this program are declared in the order total, price, qty:

// initvars.go: the order in which one package starts.
package main

import "fmt"

var total = show("total", price*qty)
var price = show("price", 4800)
var qty = show("qty", 3)

func show(name string, v int) int {
	fmt.Println("variable", name, "=", v)
	return v
}

func init() { fmt.Println("first init: total is", total) }

func init() { fmt.Println("second init") }

func main() { fmt.Println("main") }

variable price = 4800
variable qty = 3
variable total = 14400
first init: total is 14400
second init
main

It set price, then qty, then total, 14400. The specification’s rule is to initialise, step by step, the variable that comes first in declaration order among those whose values no longer depend on an uninitialised variable. total depends on price and qty, so it waits for both. Then the two init functions ran in the order they are written, and main last. When a package has several files, the specification encourages build tools to hand them to the compiler in file-name order, so that the order of declarations across files is the same on every build.

Across packages, a package starts only after every package it imports. The shopinit module has three: cart imports prices, greeting and prices import nothing of the module, and main imports cart and greeting:

from session import run

# Which package imports which, then the order in which they start when the program runs.
run("""
cd initorder && go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
cd initorder && go run .
""")

$ cd initorder && go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
example.com/shopinit: example.com/shopinit/cart example.com/shopinit/greeting fmt
example.com/shopinit/cart: example.com/shopinit/prices fmt
example.com/shopinit/greeting: fmt
example.com/shopinit/prices: fmt
$ cd initorder && go run .
greeting: variable Text
greeting: init
prices: variable List
prices: init
cart: variable Items, sees 2 prices
cart: init
main: variable started
main: init
main: main runs; Namaste! 2 items

greeting started first, then prices, then cart, then main, although main.go imports cart before greeting. Since Go 1.21 the specification defines the order exactly: sort all packages by import path, then repeatedly initialise the first package in that list whose imports have all been initialised. Step through it:

Because the order is defined, a package can rely on the packages it imports being ready, as cart relied on the price list. Nothing else is promised, so never rely on a package that you do not import having started.

An import with the name _, the blank identifierblank identifier: The name _ (an underscore), which takes a value and throws it away. It lets code ignore a result on purpose, or import a package only for what it does when it starts. More in “Your first Go program: go run and go build”, imports a package only for its initialisation. The image package’s documentation names the standard case: decoding a PNG needs the decoder that image/png registers in its init, so a program writes import _ "image/png". The two programs below differ only in that line:

// register_png.go: a blank import runs the init of image/png.
package main

import (
	"bytes"
	"encoding/hex"
	"fmt"
	"image"
	_ "image/png" // its init registers the "png" format with package image
)

// A grey image of 2 by 1 pixels, encoded as PNG (73 bytes).
const pngHex = "89504e470d0a1a0a0000000d4948445200000002000000010800000000d149205600" +
	"00001049444154789c000300fcff02ff00030002070102e07a5cf80000000049454e44ae426082"

func main() {
	data, _ := hex.DecodeString(pngHex)
	cfg, format, err := image.DecodeConfig(bytes.NewReader(data))
	fmt.Printf("format %q, %dx%d, error: %v\n", format, cfg.Width, cfg.Height, err)
}

format "png", 2x1, error: <nil>

// register_none.go: the same program without the blank import.
package main

import (
	"bytes"
	"encoding/hex"
	"fmt"
	"image"
)

// A grey image of 2 by 1 pixels, encoded as PNG (73 bytes).
const pngHex = "89504e470d0a1a0a0000000d4948445200000002000000010800000000d149205600" +
	"00001049444154789c000300fcff02ff00030002070102e07a5cf80000000049454e44ae426082"

func main() {
	data, _ := hex.DecodeString(pngHex)
	cfg, format, err := image.DecodeConfig(bytes.NewReader(data))
	fmt.Printf("format %q, %dx%d, error: %v\n", format, cfg.Width, cfg.Height, err)
}

format "", 0x0, error: image: unknown format

With the blank import, image.DecodeConfig recognised the format, png, 2x1; without it, the same bytes gave image: unknown format. That is the kind of work init is for: cheap, local registration that cannot fail. An init function takes no arguments, returns nothing and cannot be called, so it can report a failure only by panicking, and it runs in every program and test binary that imports its package, needed or not. Open files, network connections and anything that can fail belong in a function that the program calls from main and that returns an error.

Name a package for what it gives its callers

A package’s name appears at every place it is used, in front of each name it exports, so it is part of every call. The Go blog’s guidance on package names comes down to a few rules: short, lower case, no under_scores or mixedCaps, a name that says what the package provides, and exported names that do not repeat it:

The standard library follows the same rules, as in http.Server, bufio.Reader and time.Now. If no short name fits what a package does, the package probably does two things and should be split. A quick test is to write the call site first: when pricing.Total(bill) reads like a phrase, the package and its names fit together.

Practise

Most questions use packages you have not met here, such as mail, cart or numwords, so each one asks you to apply a rule rather than recall the kirana example. The session opens with the idea your earlier answers mark as weakest:

Interview questions

Warm-up (fresher): What makes a name in a Go package exported?

Its first character is an upper-case letter and it is declared at the package level, or it is the name of a field or a method. Total in package pricing is exported and other packages call it as pricing.Total; tax and a field named pricePaise are not, so only the files of the pricing folder can use them. There is no public or private keyword, and a folder named internal adds a separate rule about which packages may import it.

Two longer questions of this module build on this lesson:

Key takeaways

• A package is the .go files of one folder, compiled together, and its import path is the module path followed by its folder, as go list ./... printed for kirana.
• A name is exported when its first letter is upper case and it is declared at the package level or names a field or method; unexported names are shared only inside the package’s folder.
• A package under internal/ can be imported only by code whose path starts with the folder above internal, so example.com/rival could not import kirana’s ledger.
• Two packages may not import each other, directly or through others; a small interface in the package that needs it, or a third package for shared data, makes the imports go one way.
• Each package starts after the packages it imports, its variables in dependency order and then its init functions, and main runs last; init is for cheap registration that cannot fail.
• Name a package for what it provides, short and lower case, and never repeat the package name in its exported names.