Code Packages and Package Imports

Let's view a small program which imports a standard code package. (Assume the source code of this program is stored in a file named simple-import-demo.go.)

package main

import "fmt"

func main() {
	fmt.Println("Go has", 25, "keywords.")
}

Some explanations:

• The first line specifies the name of the package containing the source file simple-import-demo.go. The main entry function of a program must be put in a package named main.
• The third line imports the fmt standard package by using the import keyword. The identifier fmt is the package name. It is also used as the import name of, and represents, this standard package in the scope of containing source file. (Import names will be explained a below section.) There are many format functions declared in this standard package for other packages to use. The Println function is one of them. It will print the string representations of an arbitrary number of arguments to the standard output.
• The sixth line calls the Println function. Note that the function name is prefixed with a fmt. in the call, where fmt is the name of the package which contains the called function. The form aImportName.AnExportedIdentifier is called a qualified identifier. AnExportedIdentifier is called an unqualified identifier.
• A fmt.Println function call has no requirements for its arguments, so in this program, its three arguments will be deduced as values of their respective default types, string, int and string.
• For each fmt.Println call, a space character is inserted between each two consecutive string representations and a newline character is printed at the end.

Running this program, you will get the following output:

$ go run simple-import-demo.go
Go has 25 keywords.

Please note, only exported code elements in a package can be used in the source file which imports the package. An exported code element uses an exported identifier as its name. For example, the first character of the identifier Println is an upper case letter (so the Println function is exported), which is why the Println function declared in the fmt standard package can be used in the above example program.

The built-in functions, print and println, have similar functionalities as the corresponding functions in the fmt standard package. Built-in functions can be used without importing any packages.

Note, the two built-in functions, print and println, are not recommended to be used in the production environment, for they are not guaranteed to stay in the future Go versions.

All standard packages are listed here. We can also run a local server to view Go documentation.

A package import is also called an import declaration formally in Go. An import declaration is only visible to the source file which contains the import declaration. It is not visible to other source files in the same package.

Let's view another example:

package main

import "fmt"
import "math/rand"

func main() {
	fmt.Printf("Next pseudo-random number is %v.\n", rand.Uint32())
}

This example imports one more standard package, the math/rand package, which is a sub-package of the math standard package. This package provides some functions to produce pseudo-random numbers.

Some explanations:

• In this example, the package name rand is used as the import name of the imported math/rand standard package. A rand.Uint32() call will return a random uint32 integer number.
• Printf is another commonly used function in the fmt standard package. A call to the Printf function must take at least one argument. The first argument of a Printf function call must be a string value, which specifies the format of the printed result. The %v in the first argument is called a format verb, it will be replaced with the string representation of the second argument. As we have learned in the article basic types and their literals, the \n in a double-quoted string literal will be escaped as a newline character.

The above program will always output:

Next pseudo-random number is 2596996162.

Note: before Go 1.20, if we expect the above program to produce a different random number at each run, we should set a different seed by calling the rand.Seed function when the program just starts.

If multiple packages are imported into a source file, we can group them in one import declaration by enclosing them in a ().

Example:

package main

// Multiple packages can be imported together.
import (
	"fmt"
	"math/rand"
	"time"
)

func main() {
	// Set the random seed (only needed before Go 1.20).
	rand.Seed(time.Now().UnixNano())
	fmt.Printf("Next pseudo-random number is %v.\n", rand.Uint32())
}

Some explanations:

• this example imports one more package, the time standard package, which provides many time related utilities.
• function time.Now() returns the current time, as a value of type time.Time.
• UnixNano is a method of the time.Time type. The method call aTime.UnixNano() returns the number of nanoseconds elapsed since January 1, 1970 UTC to the time denoted by aTime. The return result is a value of type int64, which is also the parameter type of the rand.Seed function (note: the rand.Seed function has been deprecated since Go 1.20). Methods are special functions. We can learn methods in the article methods in Go for details later.

In Go 101, only the following listed format verbs will be used.

• %v, which will be replaced with the general string representation of the corresponding argument.
• %T, which will be replaced with the type name or type literal of the corresponding argument.
• %x, which will be replaced with the hex string representation of the corresponding argument. Note, the hex string representations for values of some kinds of types are not defined. Generally, the corresponding arguments of %x should be strings, integers, integer arrays or integer slices (arrays and slices will be explained in a later article).
• %s, which will be replaced with the string representation of the corresponding argument. The corresponding argument should be a string or byte slice.
• Format verb %% represents a percent sign.

An example:

package main

import "fmt"

func main() {
	a, b := 123, "Go"
	fmt.Printf("a == %v == 0x%x, b == %s\n", a, a, b)
	fmt.Printf("type of a: %T, type of b: %T\n", a, b)
	fmt.Printf("1%% 50%% 99%%\n")
}

Output:

a == 123 == 0x7b, b == Go
type of a: int, type of b: string
1% 50% 99%

For more Printf format verbs, please read the online fmt package documentation, or view the same documentation by running a local documentation server. We can also run go doc fmt to view the documentation of the fmt standard package, and run go doc fmt.Printf to view the documentation of the fmt.Printf function, in a terminal.

A code package may consist of several source files. These source files are located in the same folder. The source files in a folder (not including subfolders) must belong to the same package. So, a folder corresponds to a code package, and vice versa. The folder containing the source files of a code package is called the folder of the package.

For Go Toolchain, a package whose import path containing an internal folder name is viewed as a special package. It can only be imported by the packages in and under the direct parent directory of the internal folder. For example, package .../a/b/c/internal/d/e/f and .../a/b/c/internal can only be imported by the packages whose import paths have a .../a/b/c prefix.

When one source file in a package imports another package, we say the importing package depends on the imported package.

Go doesn't support circular package dependencies. If package a depends on package b and package b depends on package c, then source files in package c can't import package a and b, and source files in package b can't import package a.

Surely, source files in a package can't, and don't need to, import the package itself.

Later, we will call the packages named with main and containing main entry functions as program packages (or command packages), and call other packages as library packages. Program packages are not importable. Each Go program should contain one and only one program package.

The name of the folder of a package is not required to be the same as the package name. However, for a library package, it will make package users confused if the name of the package is different from the name of the folder of the package. The cause of the confusion is that the default import path of a package is the name of the package but what is contained in the import path of the package is the folder name of the package. So please try to make the two names identical for each library package.

On the other hand, it is recommended to give each program package folder a meaningful name other than its package name, main.

Here is a simple example which contains two init functions:

package main

import "fmt"

func init() {
	fmt.Println("hi,", bob)
}

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

func init() {
	fmt.Println("hello,", smith)
}

func titledName(who string) string {
	return "Mr. " + who
}

var bob, smith = titledName("Bob"), titledName("Smith")

The output of this program:

hi, Mr. Bob
hello, Mr. Smith
bye

At run time, a package will be loaded after all its dependency packages. Each package will be loaded once and only once.

All init functions in all involved packages in a program will be invoked sequentially. An init function in an importing package will be invoked after all the init functions declared in the dependency packages of the importing package for sure. All init functions will be invoked before invoking the main entry function.

The invocation order of the init functions in the same source file is from top to bottom. Go specification recommends, but doesn't require, to invoke the init functions in different source files of the same package by the alphabetical order of filenames of their containing source files. So it is not a good idea to have dependency relations between two init functions in two different source files.

All package-level variables declared in a package are initialized before any init function declared in the same package is invoked.

Go runtime will try to initialize package-level variables in a package by their declaration order, but a package-level variable will be initialized after all of its depended variables for sure. For example, in the following code snippet, the initializations the four package-level variables happen in the order y, z, x, and w.

func f() int {
	return z + y
}

func g() int {
	return y/2
}

var (
	w       = x
	x, y, z = f(), 123, g()
)

About more detailed rule of the initialization order of package-level variables, please read the article expression evaluation order.

In fact, the full form of an import declaration is

import importname "path/to/package"

where importname is optional, its default value is the name (not the folder name) of the imported package.

In fact, in the above used import declarations, the importname portions are all omitted, for they are identical to the respective package names. These import declarations are equivalent to the following ones:

import fmt "fmt"        // <=> import "fmt"
import rand "math/rand" // <=> import "math/rand"
import time "time"      // <=> import "time"

If the importname portion presents in an import declaration, then the prefix tokens used in qualified identifiers must be importname instead of the name of the imported package.

The full import declaration form is not used widely. However, sometimes we must use it. For example, if a source file imports two packages with the same name, to avoid making compiler confused, we must use the full import form to set a custom importname for at least one package in the two.

Here is an example of using full import declaration forms.

package main

import (
	format "fmt"
	random "math/rand"
	"time"
)

func main() {
	random.Seed(time.Now().UnixNano())
	format.Print("A random number: ", random.Uint32(), "\n")

	// The following line fails to compile,
	// for "rand" is not identified.
	/*
	fmt.Print("A random number: ", rand.Uint32(), "\n")
	*/
}

Some explanations:

• we must use format and random as the prefix token in qualified identifiers, instead of the real package names fmt and rand.
• Print is another function in the fmt standard package. Like Println function calls, a Print function call can take an arbitrary number of arguments. It will print the string representations of the passed arguments, one by one. If two consecutive arguments are both not string values, then a space character will be automatically inserted between them in the print result.

The importname in the full form import declaration can be a dot (.). Such imports are called dot imports. To use the exported elements in the packages being dot imported, the prefix part in qualified identifiers must be omitted.

Example:

package main

import (
	. "fmt"
	. "time"
)

func main() {
	Println("Current time:", Now())
}

In the above example, Println instead of fmt.Println, and Now instead of time.Now must be used.

Generally, dot imports reduce code readability, so they are not recommended to be used in formal projects.

The importname in the full form import declaration can be the blank identifier (_). Such imports are called anonymous imports (some articles elsewhere also call them blank imports). The importing source files can't use the exported code elements in anonymously imported packages. The purpose of anonymous imports is to initialize the imported packages (each of init functions in the anonymously imported packages will be called once).

In the following example, all init functions declared in the net/http/pprof standard package will be called before the main entry function is called.

package main

import _ "net/http/pprof"

func main() {
	... // do somethings
}

Except anonymous imports, other imports must be used at least once. For example, the following example fails to compile.

package main

import (
	"net/http" // error: imported and not used
	. "time"   // error: imported and not used
)

import (
	format "fmt"  // okay: it is used once below
	_ "math/rand" // okay: it is not required to be used
)

func main() {
	format.Println() // use the imported "fmt" package
}

• About Go 101 - why this book is written.
• Acknowledgments

• An Introduction of Go - why Go is worth learning.
• The Go Toolchain - how to compile and run Go programs.

• Become Familiar With Go Code
  • Introduction of Source Code Elements
  • Keywords and Identifiers
  • Basic Types and Their Value Literals
  • Constants and Variables - also introduces untyped values and type deductions.
  • Common Operators - also introduces more type deduction rules.
  • Function Declarations and Calls
  • Code Packages and Package Imports
  • Expressions, Statements and Simple Statements
  • Basic Control Flows
  • Goroutines, Deferred Function Calls and Panic/Recover

• Go Type System
  • Go Type System Overview - a must read to master Go programming.
  • Pointers
  • Structs
  • Value Parts - to gain a deeper understanding into Go values.
  • Arrays, Slices and Maps - first-class citizen container types.
  • Strings
  • Functions - function types and values, including variadic functions.
  • Channels - the Go way to do concurrency synchronizations.
  • Methods
  • Interfaces - value boxes used to do reflection and polymorphism.
  • Type Embedding - type extension in the Go way.
  • Type-Unsafe Pointers
  • Generics - use and read composite types
  • Reflections - the reflect standard package.

• Some Special Topics
  • Line Break Rules
  • More About Deferred Function Calls
  • Some Panic/Recover Use Cases
  • Explain Panic/Recover Mechanism in Detail - also explains exiting phases of function calls.
  • Code Blocks and Identifier Scopes
  • Expression Evaluation Orders
  • Value Copy Costs in Go
  • Bounds Check Elimination

• Concurrent Programming
  • Concurrency Synchronization Overview
  • Channel Use Cases
  • How to Gracefully Close Channels
  • Other Concurrency Synchronization Techniques - the sync standard package.
  • Atomic Operations - the sync/atomic standard package.
  • Memory Order Guarantees in Go
  • Common Concurrent Programming Mistakes

• Memory Related
  • Memory Blocks
  • Memory Layouts
  • Memory Leaking Scenarios

• Some Summaries
  • Some Simple Summaries
  • nil in Go
  • Value Conversion, Assignment and Comparison Rules
  • Syntax/Semantics Exceptions
  • Go FAQ 101

• More Go Related Topics