These are the notes for Go episode 2. You will learn what the Go toolchain is, how to install Go and check its version, how Go releases work, the difference between go run and go build, what a module and go.mod are, how to build your program for Windows, Mac and Linux from one computer, and the helper tools go install, go fmt, go vet, go doc and go env. Terminal outputs below are real (Go 1.24.7 on linux/amd64, in the folder /root/hello); compiler examples run as-is in the SyntaxPilot compiler.
The problem: Riya wants your program
You built a profile card in episode 1. Your friend Riya says "send it to me!" The obvious move is to send main.go. She double-clicks it and it opens as plain text. Source code is not an app: the computer can only run the compiled executable. Making one is the toolchain's job.
What a toolchain is: a mechanic's toolkit
| A mechanic | Go |
|---|---|
| One toolkit, carried everywhere | one program: the go command |
| Many tools inside it | subcommands: go run, go build, go vet, ... |
| Each tool does one job | build, check, format, explain |
The toolchain is the compiler plus all these helper tools. A subcommand is the word after go that picks the tool.
Installing Go and opening a terminal
- Download the installer for your computer from go.dev/dl (Windows, macOS, Linux).
- Run it, keeping the default options.
- Open a terminal: a window where you type commands instead of clicking (Windows: PowerShell; Mac and Linux: Terminal).
$ go version
go version go1.24.7 linux/amd64
| Part | Meaning |
|---|---|
go1.24.7 |
the Go version |
linux |
the operating system the Go tools run on |
amd64 |
the processor family: common 64-bit Intel/AMD chips |
Go versions and the Go 1 promise
Like phone updates: new features, and old apps keep working.
- The Go 1 compatibility promise (go.dev/doc/go1compat): "It is intended that programs written to the Go 1 specification will continue to compile and run correctly, unchanged, over the lifetime of that specification."
- A major release every six months, in February and August:
| Release | Date |
|---|---|
| Go 1.24 | 11 February 2025 |
| Go 1.25 | 12 August 2025 |
| Go 1.26 | 10 February 2026 |
| Go 1.27 | 19 August 2026 |
- Minor releases (1.27.1, 1.27.2, ...) fix bugs and security problems. As of this episode the newest is Go 1.27.3 (19 October 2026).
- Support: "Each major Go release is supported until there are two newer major releases."
- The SyntaxPilot compiler used in these videos runs Go 1.24; thanks to the promise, everything in this course works the same on newer versions.
A program can ask which Go built it:
package main
import (
"fmt"
"runtime"
)
func main() {
fmt.Println(runtime.Version())
fmt.Println(runtime.GOOS, runtime.GOARCH)
}
go1.24.7
linux amd64
runtimeis a standard-library package that describes the running program.- GOOS = Go operating system (
linux,windows,darwinfor macOS, ...). - GOARCH = Go architecture, the kind of processor (
amd64,arm64, ...).
go run vs go build
go run |
go build |
|
|---|---|---|
| What it does | compiles into a hidden temporary folder, runs, throws the result away | compiles and keeps the executable |
| Like | a chef who cooks and serves, keeps no plate | a packed tiffin you can hand over |
| Use it for | learning, quick experiments (the online compiler uses it) | apps you share or deploy |
The obvious attempt fails
$ mkdir hello
$ cd hello
# (put main.go here)
$ go build
go: go.mod file not found in current directory or any parent directory; see 'go help modules'
Go needs a module.
Modules: your project's ID card
| A shop | A Go project |
|---|---|
| A registered shop | a module: a folder of Go code (its packages), built and versioned together |
| Its registration card | go.mod: the module path and the Go version |
| A unique address | the module path, e.g. github.com/you/hello (where the code will live online) |
$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello
go: to add module requirements and sums:
go mod tidy
$ cat go.mod
module example.com/hello
go 1.24.7
module example.com/hellois the module path.example.com/...is fine for practice.go 1.24.7is the Go version this module expects.go mod tidymanages other people's code your module uses (the modules episode covers it).catjust prints a file.
Before modules: GOPATH
- Before modules, all your Go code had to live in one workspace folder, GOPATH (by default a folder named
goin your home folder:$HOME/goon Unix,%USERPROFILE%\goon Windows). - There was no way to say which version of someone else's code you needed.
- Modules arrived in Go 1.11 (2018) and became the default in Go 1.16.
- Today a project with a
go.modcan live in any folder. GOPATH still exists: it holds the download cache (GOPATH/pkg/mod) and installed programs (GOPATH/bin).
go build makes an app
$ go build
$ ls
go.mod hello main.go
$ du -h hello
2.2M hello
$ ./hello
Hello from my app!
- Silence means success in Go's tools.
- The executable is named after the module (
hello).du -hshows its size. - It is statically linked: everything it needs is inside this one file, so Riya doesn't need Go installed.
Cross-compilation: build for any computer
You built on Linux, so hello is a Linux app. Riya uses Windows. Like a phone charger that needs a different plug in each country, the program stays the same and only the outside must match the machine. Set GOOS and GOARCH in front of go build:
$ GOOS=windows GOARCH=amd64 go build
$ file hello.exe
hello.exe: PE32+ executable (console) x86-64, for MS Windows, 15 sections
$ GOOS=darwin GOARCH=arm64 \
go build -o hello-mac
$ file hello-mac
hello-mac: Mach-O 64-bit arm64 executable, flags:<|DYLDLINK|PIE>
-onames the output file.filetells you what kind of file something is.- Building for a different computer than the one you're on is cross-compilation.
- On Windows PowerShell the syntax is
$env:GOOS="windows"; $env:GOARCH="amd64"; go build.
How many targets?
$ go tool dist list | wc -l
48
They include android/arm64, darwin/arm64, ios/arm64, js/wasm, linux/amd64, linux/arm64, linux/riscv64, wasip1/wasm, windows/amd64, windows/arm64 and more. WebAssembly (wasm) is a format that runs inside web browsers.
go install and PATH
| Command | Where the app goes |
|---|---|
go build |
the current folder |
go install |
GOPATH/bin ($HOME/go/bin), or GOBIN if you set it |
$ go install
$ ls ~/go/bin
hello
PATH is the list of folders your terminal searches for commands, like a delivery person who checks only certain streets. Add $HOME/go/bin to PATH once, and every Go tool you install becomes a command you can type from any folder.
go fmt
go fmt runs gofmt on every file in the package, prints the names of the files it changed (main.go) and rewrites them in Go's official style.
go vet: a bug the compiler lets through
fmt.Printf prints with a template. %d is a verb (placeholder) meaning "a whole number goes here"; \n is a new line.
package main
import "fmt"
func main() {
fmt.Printf("Score: %d\n", "Aarav")
}
Score: %!d(string=Aarav)
It compiles and runs, but the output is wrong: %!d(string=Aarav) is Printf saying "you asked for a number and gave me a string". go vet looks for code that compiles but is probably a mistake:
$ go vet
# example.com/hello
# [example.com/hello]
./main.go:6:5: fmt.Printf format %d has arg "Aarav" of wrong type string
Fix: fmt.Printf("Score: %d\n", 95) prints Score: 95. Run go vet before sharing code; go test runs many vet checks automatically.
go doc
$ go doc fmt.Println
package fmt // import "fmt"
func Println(a ...any) (n int, err error)
Println formats using the default formats for its operands and writes to
standard output. Spaces are always added between operands and a newline
is appended. It returns the number of bytes written and any write error
encountered.
The text is the function's doc comment. The same documentation is on pkg.go.dev. Operands are the values you pass in. The first line is the function's signature (its inputs and outputs), covered in the functions episode.
go env, GOROOT and GOPATH
Environment variables are named settings that programs read.
$ go env GOOS GOARCH
linux
amd64
$ go env GOROOT GOPATH
/usr/local/go1.24.7
/root/go
- GOROOT: where Go itself is installed (compiler + standard library). You almost never change it.
- GOPATH: the
gofolder in your home folder (this machine's home folder is/root).
No install? The Go Playground
- go.dev/play: the official Go Playground, runs code in the browser.
- The SyntaxPilot compiler: practise every episode's code.
Both run one small program at a time. For real projects, install Go and start with go mod init.
Common mistakes (and the real error messages)
| You did | Real error / output | Fix |
|---|---|---|
go build with no go.mod |
go: go.mod file not found in current directory or any parent directory; see 'go help modules' |
go mod init example.com/hello |
go mod init a second time |
go: /root/hello/go.mod already exists |
keep the existing go.mod |
go mod init with no path |
go: cannot determine module path for source directory ... (outside GOPATH, module path must be specified) |
go mod init example.com/m |
Printf("%d", "Aarav") |
%!d(string=Aarav) (no error) |
run go vet, pass a number |
sent main.go to a friend |
it opens as text | go build (with GOOS/GOARCH for their computer) |
Mini project: ship your profile card
mkdir card && cd card- Save the profile card from episode 1 as
main.go. go mod init example.com/cardgo vet(no output means no problems), thengo buildand./card.GOOS=windows GOARCH=amd64 go buildand sendcard.exeto a Windows friend.
Practice
- Which command prints the operating system the Go tools run on?
- Build your module for Linux on ARM (
arm64). What doesfilesay? - Write
fmt.Printf("%d items\n", "five"), run it, then catch it withgo vet. - What is the difference between
go buildandgo install?
Solutions and hints
go env GOOS(also visible ingo version).GOOS=linux GOARCH=arm64 go build;filereports an ARM aarch64 ELF executable.- Output
%!d(string=five) items; vet reportsfmt.Printf format %d has arg "five" of wrong type string. go buildleaves the executable in the current folder;go installputs it inGOPATH/bin(orGOBIN).
Quick quiz
You are on Linux. Riya has a Windows laptop. Which command builds a program she can run?
- A.
go run main.go - B.
go build - C.
GOOS=windows GOARCH=amd64 go build - D.
go vet
Answer
C. Plain go build makes an app for the computer you're on (Linux). GOOS=windows GOARCH=amd64 targets Windows and produces hello.exe.
Interview questions
- What is the difference between
go run,go buildandgo install? - What is a Go module? What is in
go.mod? - What were GOPATH's problems, and when did modules become the default?
- How do you cross-compile a Go program? What are GOOS and GOARCH?
- What does
go vetcatch that the compiler doesn't? Give an example. - What is the Go 1 compatibility promise? How often is Go released and how long is a release supported?
- What is GOROOT?
Glossary
| Term | Meaning | Example |
|---|---|---|
| Toolchain | the compiler plus the helper tools, all behind the go command |
go build, go vet |
| Subcommand | the word after go that chooses the tool |
run in go run |
| Terminal | a window where you type commands | PowerShell, Terminal |
| go version | prints the installed Go version, OS and architecture | go version go1.24.7 linux/amd64 |
| Go 1 compatibility promise | Go 1 programs keep compiling and running unchanged | code from 2015 still builds |
| Major / minor release | a new feature release / a bug-and-security fix release | 1.27 / 1.27.3 |
| runtime package | describes the running program | runtime.Version() |
| GOOS | the target operating system | linux, windows, darwin |
| GOARCH | the target processor architecture | amd64, arm64 |
| go run | compile to a temporary place, run, discard | go run main.go |
| go build | compile and keep the executable | go build |
| Executable | a file the computer runs directly | hello, hello.exe |
| Module | a project: Go packages built and versioned together | example.com/hello |
| go.mod | the module's ID card: module path and Go version | module example.com/hello |
| Module path | the module's unique name, usually its online location | github.com/you/hello |
| go mod init | creates go.mod |
go mod init example.com/hello |
| go mod tidy | adds/removes the dependencies your code needs | covered in the modules episode |
| GOPATH | Go's workspace folder; today the cache and bin folder |
$HOME/go |
| GOROOT | where Go itself is installed | /usr/local/go |
| Statically linked | everything the program needs is inside the one file | no Go needed to run it |
| Cross-compilation | building for a different OS/CPU than your own | GOOS=windows go build |
| -o | names the output file | go build -o hello-mac |
| WebAssembly (wasm) | a format that runs inside web browsers | js/wasm |
| go install | builds and puts the executable in GOPATH/bin |
go install |
| PATH | the folders your terminal searches for commands | add ~/go/bin |
| GOBIN | where go install puts programs, if set |
|
| go fmt | formats every file in the package | prints main.go |
| fmt.Printf | prints using a template with verbs | Printf("%d\n", 95) |
| Verb | a placeholder in a Printf template | %d = whole number |
%!d(string=...) |
Printf's sign of a wrong-type argument | %!d(string=Aarav) |
| go vet | finds code that compiles but is probably wrong | wrong Printf verb |
| go doc | shows documentation in the terminal | go doc fmt.Println |
| Signature | a function's inputs and outputs | func Println(a ...any) (n int, err error) |
| pkg.go.dev | the website with documentation for Go packages | |
| Environment variable | a named setting that programs read | GOOS=windows |
| go env | prints Go's settings | go env GOPATH |
| Go Playground | the official in-browser Go runner | go.dev/play |
Summary
- The toolchain is one
gocommand with many subcommands. - A new Go version ships every February and August; the Go 1 promise keeps old code working; each release is supported until two newer ones exist.
go runruns and discards;go buildkeeps a single statically linked executable.- A module (
go mod init) gives a project itsgo.modID card; modules replaced GOPATH (Go 1.11, default in 1.16). - GOOS + GOARCH = cross-compilation to 48 targets.
go install+ PATH,go fmt,go vet(catches what compiles),go doc,go env.
Next episode: variables, zero values and scope. A chai price changes in one place but not another, and you invent variables: var, :=, zero values and scope.
Sources: go.dev/doc/devel/release (release dates and support policy), go.dev/doc/go1compat (compatibility promise), go.dev/wiki/Modules (modules since Go 1.11, July 2018), go.dev/blog/go116-module-changes (module mode by default in Go 1.16), go help gopath (default GOPATH).