.GO File Format – File structure

Encoding

Source code is Unicode text encoded in UTF-8 (spec: Source code representation). The text is not normalised, so an accented character written as one code point and the same character built from a letter and a combining accent are different.

• Invalid UTF-8 is rejected by the gc compiler with invalid UTF-8 encoding.
• Byte order mark. A compiler may ignore a UTF-8 byte order mark (U+FEFF) as the first code point and may reject one anywhere else. gc does both.
• NUL. A compiler may reject the NUL character (U+0000) in the source. gc does.
• Line endings. Only line feed (U+000A) ends a line. A carriage return is ordinary white space, so CRLF files compile. Carriage returns inside raw string literals are discarded from the value. gofmt writes line feeds only.

Layout of a source file

SourceFile   = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
TopLevelDecl = Declaration | FunctionDecl | MethodDecl .
Declaration  = ConstDecl | TypeDecl | VarDecl .

// Package greet builds greetings.
package greet

import (
	"fmt"
	"strings"
)

// Prefix starts every greeting.
const Prefix = "Hello"

// Hello returns a greeting for name.
func Hello(name string) string {
	return fmt.Sprintf("%s, %s", Prefix, strings.TrimSpace(name))
}

Comments, blank lines and build constraints may come before the package clause. Imports must come after it and before all other declarations. Top-level declarations may appear in any order and may refer to each other regardless of position, because their scope is the package block.

Package clause

PackageClause = "package" PackageName .
PackageName   = identifier .

The package name must not be the blank identifier (spec: Package clause). All the files that share a package name form that package. The specification allows an implementation to require them to be in one folder, and the go command does.

• A folder holds one package. The single exception is an external test package named with a _test suffix.
• package main is a program; its folder must declare func main(). See Packages and modules.
• The package clause is not a declaration. The name appears in no scope; it sets the default name used by importers.
• By convention the package name is the last element of the folder path, in lower case with no underscores. Neither is required by the language.

Import declarations

ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
ImportSpec = [ "." | PackageName ] ImportPath .
ImportPath = string_lit .

• The imported name is declared in the file block, so each file needs its own imports.
• It is an error to import a package and not use it. It is also an error for a package to import itself, directly or indirectly: import cycles are not allowed.
• The meaning of the import path is left to the implementation. The go command treats it as a standard library path or a path inside a module.
• gofmt sorts the imports within each group; groups are separated by a blank line.

File names and what the go command reads

The language does not care what a source file is called. The go command decides which files make up a package from their names and their build constraints.

• The _test suffix is stripped before these suffix rules apply, so foo_linux_test.go is a Linux-only test file.
• The suffix needs something before it. A file called linux.go has had no implicit constraint since Go 1.4.
• The constraint from the name is added to any explicit build constraint in the file.
• Other extensions in the same folder are also examined: .s and .S assembler, .c, .h and C++ sources (only useful with cgo or SWIG, otherwise C files are an error), .syso object files.

Test files

Files ending in _test.go are compiled only by go test. Their package clause may name either the package under test or a separate external test package with a _test suffix, which imports the package like any other client.

Build constraints

A build constraint, or build tag, decides whether a file takes part in a build. It is a line comment of the form //go:build followed by an expression, near the top of the file, preceded only by blank lines and other comments. In a Go file it must come before the package clause and should be followed by a blank line, so that it is not read as package documentation. A file may have only one //go:build line.

//go:build (linux && 386) || (darwin && !cgo)

package hello

• With GOOS=android, tags and files for linux also match. The same holds for illumos and solaris, and for ios and darwin.
• The tag purego is a convention for a version of a package written only in Go, without assembly.
• In modules with Go 1.21 or later, a go1.N term sets a minimum: the language version of the file becomes the minimum version the constraint implies, and this can lower it below the module’s version (see Versions).
• The older syntax, // +build, was used up to Go 1.16. gofmt adds the matching //go:build line when it finds the old form.

The cgo preamble

A file that uses cgo imports the pseudo-package "C". If the import is immediately preceded by a comment, that comment, the preamble, is used as a C header when compiling the C parts of the package. It may contain any C code. Go code reaches the declarations through the package name C; names that start with a lower-case letter work too. Static variables in the preamble cannot be used from Go; static functions can.

package main

// #cgo CFLAGS: -DPNG_DEBUG=1
// #cgo amd64 386 CFLAGS: -DX86=1
// #cgo LDFLAGS: -lpng
// #include <png.h>
import "C"

A #cgo pkg-config: line takes package names and obtains the flags from the pkg-config tool. A Go function can be made callable from C with a //export Name comment before it.

Directives

A directive is a comment that the toolchain reads. It must be on its own line, with only spaces and tabs before it, and with no space between // and the directive name. Apart from line, compiler directives have the form //go:name. Tools that do not know a directive skip it as a comment.

Generated files are marked with a line matching the regular expression ^// Code generated .* DO NOT EDIT\.$ before the first text that is not a comment or blank.

Embedding files with go:embed

A //go:embed directive (Go 1.16) above a package-level variable declaration fills the variable with file contents at build time. The file must import "embed", even if only as a blank import. Only blank lines and // comments may come between the directive and the declaration, which must declare a single variable.

package server

import "embed"

//go:embed hello.txt
var greeting string

//go:embed image/* template/*
//go:embed html/index.html
var content embed.FS

• The variable must be of a string type, a slice of a byte type, or embed.FS. For a string or byte slice there must be exactly one pattern matching one file.
• Patterns use path.Match syntax with forward slashes, relative to the package folder. They may not contain . or .. elements, or start or end with a slash. Use * for the current folder. A pattern with spaces can be written as a Go string literal.
• A pattern naming a folder embeds its whole subtree, except files whose names begin with . or _. The prefix all: includes those too.
• Patterns cannot match files outside the module, symbolic links, vendor/, or folders containing a go.mod. Each pattern must match at least one file or non-empty folder, or the build fails.

Documentation comments

A comment placed directly before a top-level package, const, func, type or var declaration is its documentation comment. The go doc command and pkg.go.dev read these. The language gives them no meaning. By convention a comment starts with a complete sentence naming what it documents. A package comment goes directly before the package clause and starts with Package; it should be in only one file of the package, and if several files have one they are concatenated. A paragraph starting Deprecated: is a deprecation notice.

gofmt

gofmt prints Go source in one canonical layout. It uses tabs for indentation and blanks for alignment, and assumes a fixed-width font. Most Go code is formatted by it. go fmt runs gofmt -l -w on the named packages.

gofmt only rearranges layout, comments and import order. It does not change what the code means, apart from what -r and -s ask for. See Semicolons for why the opening brace must stay on the same line.