Your First Go Program

Every language has a notion of where a program starts. Go's is a type declaration: the main package. A package is a directory of Go files sharing one name, and exactly one of those names — main — tells the toolchain "this directory builds an executable, not a library." Inside it, func main() is the function the operating system calls first. Nothing invokes main for you implicitly; its existence is the whole contract.

Start clean:

mkdir hello && cd hello
go mod init example.com/hello

go mod init writes a two-line go.mod declaring the module path. Without it, go run . refuses with go.mod file not found in current directory or any parent directory, because directory-based commands resolve packages through the module. (A single named file that imports only the standard library is the exception: go run hello.go works standalone — until you need a second file, at which point the module earns its keep.)

Now the program:

package main

import "fmt"

func main() {
	boilingC := 100.0
	boilingF := boilingC*9.0/5.0 + 32.0
	fmt.Printf("water boils at %.1f°C = %.1f°F\n", boilingC, boilingF)
}

Read it as four decisions. package main marks this as a program. import "fmt" pulls in the formatting package so the code can talk to the terminal — Go loads packages by import path, and fmt lives in the standard library that shipped inside your toolchain. func main() is the entry point, with braces that open on the same line because Go's automatic semicolon insertion ends a line at } and other closing tokens, making your brace style a requirement rather than a preference. The body converts Celsius to Fahrenheit using ordinary arithmetic and prints with fmt.Printf, whose %.1f verbs format a float to one decimal place.

Run it:

go run .
# water boils at 100.0°C = 212.0°F

go run compiles the package and executes the result; nothing is written to your directory. If the code instead said package hello, the compiler would happily build a library — and go run would stop with go run: cannot run non-main package. The toolchain does not need to be told twice: main means program, anything else means code that other programs import. That distinction is the first half of Packages and Exported Identifiers, which covers what libraries look like and how names cross package boundaries. The declarations you just used — boilingC := 100.0 and the constant 100.0 — get their full treatment in Variables and Constants; for now they behave exactly as you would guess.

Your first program has two ways to execute, and the difference is entirely about the artifact left behind.

go run .        # compile, execute, discard — directory unchanged
go build         # compile, write ./hello (hello.exe on Windows), nothing runs

go run builds the binary into a temporary location and launches it, so your working directory stays clean. It is the edit-compile-run loop: change a line, run again, see output. go build is the production shape of the same act — it writes an executable named after the module directory's final element (a module path like example.com/cmd/server produces server; a plain hello directory produces hello), with .exe appended when the target is Windows. The -o flag overrides the name:

go build -o bin/hello .     # explicit path, the shape build scripts want
./bin/hello                 # no compiler needed to run it

That resulting file is the deployment story. It contains your compiled code and the standard library it uses — no runtime to install, no version to match, no dependency manifest to reconcile on the server. Copy it to a machine of the same OS and architecture and it runs. For a different platform, set GOOS/GOARCH as shown in Installing the Go Toolchain and build again.

Two behaviors of go build are worth internalizing now, because they explain surprises later:

• Building a main package writes the executable. Building a library package compiles it to verify it is valid, then discards the object — the output lives in the build cache, and no file appears in your directory. Silence means success.
• The command you use decides which files get compiled. go build . compiles every non-test .go file in the directory as one package. go build hello.go compiles exactly that file — so a helper defined in other.go vanishes from the build and the compiler reports undefined: helper.

That last one is the most common first-week confusion: the code exists, the error says otherwise, and the truth is that file-list mode takes your file list literally. Prefer directory and package patterns (go run ., go build ./...) so the package is the unit of compilation, which is also how tests and CI will invoke it.

A quick side-by-side to fix the roles in memory:

Once a build succeeds reliably, the next question is what the compiler silently refuses to accept — which is where Go's strictness starts teaching you.

Write a slightly bigger program and the first wall you hit will not be logic. It will be an error about something you considered harmless:

package main

import (
	"fmt"
	"strings"
)

func main() {
	name := "gopher"
	fmt.Println(strings.ToUpper(name))
}

Remove the strings call and the compiler answers:

./main.go:4:2: "strings" imported and not used

Declare a variable and never read it:

./main.go:7:6: count declared and not used

Both are compile errors in Go, not warnings you can ignore. This is deliberate. An unused import pulls a dependency into the binary's import graph for no reason — build time and artifact size spent on code that never runs — while an unused local variable usually means a missing line of logic above it, and naming it early is cheaper than debugging a symptom three functions away. Languages that downgrade these to warnings accumulate dead imports and orphaned variables until no one can tell which code is load-bearing. Go makes cleanup part of the build, so the code that compiles is the code that runs.

The mirror image of the rule: if you call fmt.Println without importing fmt, the compiler says undefined: fmt. It never searches for you. Imports are explicit, one line per package, and the resolution is exactly the name you wrote.

When an error appears, it arrives as file:line:column, and the column points at the offending token, not the line's start. The convention of reading errors bottom-up — the last line first, the original location after — applies here as everywhere. You will also notice errors from the semicolon rule if you write this:

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

Go inserts a semicolon after func main() because a newline follows an identifier-and-parenthesis sequence, and a lone { cannot follow it. The language's answer to "where do braces go" is that the opening brace belongs on the line of the declaration — the compiler enforces it before you ever argue about style in a code review.

Notice what has not complained yet: the code above is misformatted, comments are absent, and naming could improve. Formatting and static analysis are separate tools with separate jobs — Formatting and Inspection Tools covers gofmt, go doc, and go vet — and comments deserve their own treatment in Comments and Doc Comments. The compiler's contract is narrower and absolute: the program is well-formed, every name resolves, and nothing declared is dead. Hold that contract as the baseline, and every later tool feels like added power rather than duplicated noise.

The program above fits in one file. Real programs do not, and the first structural fact to absorb is that a package is a directory, not a file. Every .go file in the directory starts with the same package clause and contributes declarations to one namespace:

hello/
├── go.mod
├── main.go        package main
└── report.go      package main  — same clause, same package

Add a function to report.go:

package main

import "fmt"

func report(label string, celsius float64) {
	f := celsius*9.0/5.0 + 32.0
	fmt.Printf("%s: %.1f°C / %.1f°F\n", label, celsius, f)
}

and call it from main.go with no import of anything — same-package declarations are visible to each other without ceremony, because they are one unit of compilation. Run go run . and both files compile together. Run go run main.go and you get undefined: report: file-list mode compiles only the files you named, which is occasionally useful for a quick experiment and almost always wrong otherwise.

The directory boundary is also the visibility boundary. Declarations in another package are unreachable unless their names begin with an uppercase letter — exported names — and even then require an import of that package's path. fmt exposes Println; it does not expose whatever internal helper computed it. That rule is the entire mechanism behind Go's small, opinionated public APIs, and Packages and Exported Identifiers works through how a directory becomes an importable unit, how names are chosen, and how packages stay acyclic.

Two practical consequences for a first project:

• Tests live beside the code: main_test.go in the same directory, same package clause, compiled only by go test. You will meet the pattern in Unit Tests with the testing Package.
• A subdirectory is a new package. hello/internal/config with package config is imported by path, not by proximity, and its names are shared only through exports.

So the working loop for anything larger than a single file is: keep one package per directory, compile with patterns (go run ., go build ./..., go test ./...) instead of file lists, and let the package — never the individual file — be the thing you reason about. With entry point, commands, compiler rules, and layout settled, you have everything the syntax needs; comments are what make the next reader's experience match yours.