SyntaxPilot
Courses/Go Programming/Lesson 2

Go Programming · Lesson 2 of 89 · 13 min

The Go toolchain

installing Gogo versiongo rungo buildgo installgo mod initgo.mod basicsmodule pathgo fmtgo vetgo docgo envGOPATH vs modulesGOROOT

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

  1. Download the installer for your computer from go.dev/dl (Windows, macOS, Linux).
  2. Run it, keeping the default options.
  3. 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
  • runtime is a standard-library package that describes the running program.
  • GOOS = Go operating system (linux, windows, darwin for 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/hello is the module path. example.com/... is fine for practice.
  • go 1.24.7 is the Go version this module expects.
  • go mod tidy manages other people's code your module uses (the modules episode covers it).
  • cat just 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 go in your home folder: $HOME/go on Unix, %USERPROFILE%\go on 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.mod can 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 -h shows 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>
  • -o names the output file. file tells 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 go folder 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

  1. mkdir card && cd card
  2. Save the profile card from episode 1 as main.go.
  3. go mod init example.com/card
  4. go vet (no output means no problems), then go build and ./card.
  5. GOOS=windows GOARCH=amd64 go build and send card.exe to a Windows friend.

Practice

  1. Which command prints the operating system the Go tools run on?
  2. Build your module for Linux on ARM (arm64). What does file say?
  3. Write fmt.Printf("%d items\n", "five"), run it, then catch it with go vet.
  4. What is the difference between go build and go install?
Solutions and hints
  1. go env GOOS (also visible in go version).
  2. GOOS=linux GOARCH=arm64 go build; file reports an ARM aarch64 ELF executable.
  3. Output %!d(string=five) items; vet reports fmt.Printf format %d has arg "five" of wrong type string.
  4. go build leaves the executable in the current folder; go install puts it in GOPATH/bin (or GOBIN).

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 build and go 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 vet catch 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 go command 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 run runs and discards; go build keeps a single statically linked executable.
  • A module (go mod init) gives a project its go.mod ID 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).