Getting Started

Purpose and Scope

This page helps a new Go user move from an installed distribution to the first repeatable development loop: create a directory, initialize a module, write a small program, run it, build it, and add a test. In Go documentation, a module is the unit that records dependency metadata, while a package is a directory of Go source files compiled together. A command is a package named main that builds to an executable. The official getting-started workflow begins in a terminal and uses the go command as the single front door for module setup, execution, building, testing, and later dependency discovery.

The repository evidence for this page is intentionally split between user-facing distribution information and lower-level toolchain entry points. The root README identifies Go as an open source programming language for simple, reliable, and efficient software, points new users to official binary downloads, and explains that source installation is available when a binary distribution is not available for a target operating system and architecture. That framing matters because the first go command workflow assumes an installed Go distribution on your PATH, not a checkout of this repository. Sources: README.md

Once Go is installed, most beginners do not invoke the compiler, assembler, cgo processor, or diagnostic tools directly. They invoke go run, go build, and go test, and the toolchain coordinates the necessary internal commands. The source files in src/cmd show the shape of those internal commands: the compiler parses flags and source files, type-checks a package, compiles functions to machine code, and writes package data; the assembler configures architecture-specific object generation; cgo records Go files, C references, generated declarations, and link flags; addr2line supports pprof-oriented address translation. Sources: src/cmd/compile/internal/gc/main.go, src/cmd/asm/main.go, src/cmd/cgo/main.go, src/cmd/addr2line/main.go

Relevant Source Files

• README.md — Introduces the Go repository, directs users to official downloads and install instructions, and distinguishes binary installation from installing from source.
• misc/go_android_exec/main.go — Shows how the Go toolchain can execute built test binaries through a platform-specific wrapper, using GOOS/GOARCH-style naming and Android adb integration.
• src/cmd/addr2line/main.go — Documents the bundled go tool addr2line helper used by pprof to map program counters to function names and source locations.
• src/cmd/asm/main.go — Provides the assembler entry point, including flag parsing, architecture selection, object-file writing, and assembly failure handling.
• src/cmd/cgo/main.go — Defines cgo package and file structures used when Go source imports C declarations through import "C".
• src/cmd/compile/internal/gc/main.go — Provides the compiler driver entry point for parsing flags and source files, type-checking, compiling functions, and writing compiled package output.

Core Primitives

Start with four primitives: the terminal, a module, a package, and the go command. The terminal is where you run commands; any editor can create the source files. A module is introduced by a go.mod file created with go mod init, and it stays with your code so the Go command can track dependency requirements over time. A package is the compilation boundary for ordinary Go files in one directory. A command package is a package named main with a main function, which lets go run execute it and go build produce an executable.

The go command is the beginner-facing orchestration layer. It hides the fact that building a program may involve compiler packages, architecture-specific assembly, link steps, cgo processing, or test-binary execution. The compiler source makes this separation visible: its Main function receives architecture initialization, prepares a link context, parses compiler flags, creates pseudo-packages such as builtin and unsafe, and drives front-end and machine-code generation work. A beginner does not need these phases to print Hello, world, but knowing they exist explains why one command can support many operating systems and architectures. Sources: src/cmd/compile/internal/gc/main.go

The same pattern appears around specialized tools. The assembler entry point checks the configured architecture, builds an object context, initializes architecture-specific parsing, and writes object output. The cgo entry point models a package as Go files, generated gcc files, C preambles, link flags, exported functions, and references to C.xxx names. The addr2line command is explicitly documented as a minimal go tool addr2line binary helper for pprof rather than a general getting-started command. These files show what the beginner workflow delegates to when projects grow. Sources: src/cmd/asm/main.go, src/cmd/cgo/main.go, src/cmd/addr2line/main.go

Environment also matters. Go names target platforms with operating-system and architecture concepts such as GOOS and GOARCH. The Android execution wrapper is a concrete example of platform-aware test execution: it can be used as go_android_GOARCH_exec by the Go tool, serializes adb use, waits for a device to boot, copies a GOROOT, stages temporary directories, runs binaries, and captures reliable exit codes. This is not part of a normal desktop Hello, world path, but it explains why the same testing workflow can be adapted for cross-platform builders. Sources: misc/go_android_exec/main.go

First Program Workflow

Create a new directory outside the Go repository and initialize a module. In real projects, choose a module path that matches where the code will live, such as a repository path. For a local first program, an example path is fine. The key result is the go.mod file: it gives the Go command a module root, so future imports from other modules can be resolved and recorded consistently.

mkdir hello
cd hello
go mod init example/hello

Add a file named hello.go with a package named main. The package name tells the Go toolchain this directory builds an executable command rather than a reusable library package. The fmt package comes from the standard library, so this first program does not require downloading external modules. At this point the directory contains ordinary source code plus module metadata, which is the same shape used by larger Go applications.

package main
 
import "fmt"
 
func main() {
    fmt.Println("Hello, world")
}

Run the command directly during development. go run . loads the package in the current directory, compiles it, links it as needed, and executes the resulting program. When the program is ready to keep as an executable, use go build; that produces a binary for the current platform. These commands are intentionally higher-level than go tool compile or go tool asm, even though the repository contains those underlying programs. Sources: src/cmd/compile/internal/gc/main.go, src/cmd/asm/main.go

go run .
go build

Adding a First Test

Testing uses a naming convention that keeps tests close to the code they verify. Files ending in _test.go are test source files, and functions named TestName that accept *testing.T are run by go test. For a first command, it is often useful to move reusable behavior into a normal function so tests can call it without starting the whole executable. The official tutorial demonstrates this pattern with a greeting function, a test for a successful name, and a test for an empty input that should return an error.

A minimal local pattern is to add a function in a normal package file and a matching test file. The important point is not the exact greeting text; it is the workflow. Edit code, run go test, read failures, fix code, and repeat. go test builds a test binary and runs it, using the same toolchain foundation as other builds. On unusual targets, execution wrappers such as the Android helper can participate after compilation so the test binary runs in the right environment. Sources: misc/go_android_exec/main.go, src/cmd/compile/internal/gc/main.go

go test ./...

When a test fails, prefer making the failure message explain the input, the observed value, and the expected value. The testing.T value is the reporting channel for failures and logs. Running go test ./... from a module root walks the packages below that module, which makes it a good default before committing changes. Later, benchmarks, fuzz tests, coverage, and race detection extend the same basic command family rather than requiring a separate test framework.

System-to-Code Mapping

The beginner workflow can be understood as a stack. At the top is your module directory, containing go.mod and Go source files. The go command reads that structure and chooses an action: run, build, test, fetch dependencies, or invoke a tool. Beneath it, compiler and assembler commands process source into object code; cgo bridges Go packages with C declarations when source imports C; diagnostic tools such as addr2line support profiling and debugging workflows after programs exist.

Next Steps

After this first loop works, continue in the order that matches your goal. If you want to write reusable code, learn package organization and examples next. If you want to depend on someone else’s code, continue with module creation, import resolution, and dependency management. If you want confidence while editing, deepen the go test workflow with table-driven tests, examples, fuzzing, coverage, and race detection. If you are curious about what the go command delegates to, read the toolchain command reference and compiler architecture pages, which explain these lower-level commands as public or internal parts of the distribution.

Related pages: Download and Install, Writing Go Code, Create a Module, Add a Test, The go Command, Build and Install, Testing