Everything you need to know about Packages in Go by Uday Hiwarale

Creating a package

As we discussed, there are two types of packages. An executable packageand an utility package. A executable package is your main application since you will be running it. An utility package is not self executable, instead it enhances functionality of an executable package by providing utility functions and other important assets.

As we know, a package nothing but a directory, let’s create greet directory inside src and crate few files in it. This time, we will write package greetdeclaration on the top of each file to state that this is an utility package.

Export members

An utility package is supposed to provide some variables to a package who imports it. Like export syntax in JavaScript, Go exports a variable if a variable name starts with Uppercase. All other variables not starting with an uppercase letter is private to the package.

I am going to use variable word from now on in this article, to describe an export member but export members can be of any type like constant, map, function, struct, array, slice etc.

Let’s export a greeting variable from day.go file.

In above program, Morning variable will be exported from the package but morning variable won’t be since it starts with lowercase letter.

Importing a package

Now, we need an executable package which will consume our greetpackage. Let’s create an app directory inside src and create entry.go file with main package declaration and main function. Note here, Go packages do not have any entry file naming system like index.js in Node. For an executable package, a file with main function is entry file for execution.

To import a package, we use import syntax followed by package name. Go first searches for package directory inside GOROOT/src directory and if it doesn’t find the package, then it looks for GOPATH/src. Since, fmt package is part of Go’s standard library which is located in GOROOT/src, it is imported from there. Since Go can not find greet package inside GOROOT, it will lookup inside GOPATH/src and we have it there.

Above program throws compilation error, as morning variable is not visible from package greet. As you can see, we use . (dot) notation to access exported members from a package. When you import a package, Go creates a global variable using package declaration of the package. In above case, greet is the global variable created by Go because we used package greetdeclaration in programs contained in greet package.

We can group fmt and greet package imports together using grouping syntax (parentheses). This time, our program will compile just fine, because Morning variable is available from outside the package.

Nested package

We can nest a package inside a package. Since for Go, a package is just a directory, it’s like creating a sub directory inside an already existing package. All we have to do is provide relative path of nested package.

Package compilation

As discussed in previous lesson, go run command compiles and executes a program. We know, go install command compiles packages and creates binary executable files or package archive files. This is to avoid compilation of package(s) every single time a (program where these packages are imported) is compiled . go install pre-compiles a package and Go refers to .a files.

Generally, when you install a 3rd party package, Go compiles the package and create package archive file. If you have written package locally, then your IDEmight create package archive as soon as you save the file in the package or when package gets modified. VSCode compiles the package when you save it if you have Go plugin installed.

Package initialization

When we run a Go program, Go compiler follows a certain execution order for packages, files in a package and variable declaration in the package.

Package scope

A scope is a region in code block where a defined variable is accessible. A package scope is a region within a package where a declared variable is accessible from within a package (across all files in the package). This region is the top-most block of any file in the package.

Take a look at go run command. This time, instead of executing one file, we gave a glob pattern to include all files inside app package for execution. Go is smart enough to figure out an entry point of the application which is entry.go because it has main function. We can also use command like below (file name order doesn’t matter).

go run src/app/version.go src/app/entry.go

go install or go build command requires a package name, which includes all the files inside a package, so we don’t have to specify them like above.

Coming back to our main issue, we can use variable version declared in version.go file from anywhere in the package even through it is not exported (like Version), because it is declared in package scope. If versionvariable would have been declared in a function, it wouldn’t have been in package scope and above program would have failed to compile.

You are not allowed to re-declare global variable with same name in the same package. Hence, once version variable is declared, it can not be re-declared in the package scope. But you are free to re-declare elsewhere.

Variable initialization

When a variable a depends on another variable b, b should be defined beforehand, else program won’t compile. Go follows this rule inside functions.

But when these variables are defined in package scope, they are declared in initialization cycles. Let’s have a look at simple example below.

In above example, first c is declared because its value is already declared. In later initialization cycle, b is declared, because it depends on c and value of c is already declared. In final initialization cycle, a is declared and assigned to the value of b. Go can handle complex initialization cycles like below.

In above example, first c will be declared and then b as it’s value depends on c and finally a as its value depends on b. You should avoid any initialization loop like below where initialization get’s into a recursive loop.

Another example of package scope would be, having function f in separate file which references variable c from main file.

Init function

Like main function, init function is called by Go when a package is initialized. It does not take any arguments and doesn’t return any value. init function is implicitly declared by Go, hence you can not reference it from anywhere (or call it like init()). You can have multiple init functions in a file or a package. Order of the execution of init function in a file will be according to the order of their appearances.

You can have init function anywhere in the package. These init functions are called in lexical file name order (alphabetical order).

After all init functions are executed, main function is called. Hence, main job of init function is to initialize global variables that can not be initialized in global context. For example, initialization of an array.

Since, for syntax is not valid in package scope, we can initialize array integers of size 10 using for loop inside init function.

Package alias

When you import a package, Go create a variable using package declaration of the package. If you are importing multiple packages with same name, this will lead into a conflict.

// parent.go
package greet

var Message = "Hey there. I am parent."

// child.go
package greet<

var Message = "Hey there. I am child."

Hence, we use package alias. We state a variable name in between importkeyword and package name which is new variable to references the package.

In above example, greet/greet package now is referenced by childvariable. If you notice, we aliased greet package with underscore. Underscore is a special character in Go which act as null container. Since, we are importing greet package but not using it, Go compiler will complain about it. To avoid that, we are storing reference of that package into _ and Go compiler will simply ignore it.

Aliasing a package with underscore which seems to do nothing is quite useful sometimes when you want to initialize a package but not use it.

// parent.go
package greet

import "fmt"

var Message = "Hey there. I am parent."

func init() {
  fmt.Println("greet/parent.go ==> init()")
}

// child.go
package greet

import "fmt"

var Message = "Hey there. I am child."

func init() {
  fmt.Println("greet/greet/child.go ==> init()")
}

A main thing to remember is, an imported package is initialized only once per package. Hence if you have many import statements in a package, an imported package is going to be initialized only once in the lifetime of main package execution.

Program execution order

So far, we understood everything there is about packages. Now, let’s combine our understanding about how a program initializes in Go.

go run *.go
├── Main package is executed
├── All imported packages are initialized
|  ├── All imported packages are initialized (recursive definition)
|  ├── All global variables are initialized 
|  └── init functions are called in lexical file name order
└── Main package is initialized
   ├── All global variables are initialized
   └── init functions are called in lexical file name order

Here is a small example to prove it.

// version/get-version.go
package version

import "fmt"

func init() {
 fmt.Println("version/get-version.go ==> init()")
}

func getVersion() string {
 fmt.Println("version/get-version.go ==> getVersion()")
 return "1.0.0"
}

/***************************/

// version/entry.go
package version

import "fmt"

func init() {
 fmt.Println("version/entry.go ==> init()")
}

var Version = getLocalVersion()

func getLocalVersion() string {
 fmt.Println("version/entry.go ==> getLocalVersion()")
 return getVersion()
}

/***************************/

// app/fetch-version.go
package main

import (
 "fmt"
 "version"
)

func init() {
 fmt.Println("app/fetch-version.go ==> init()")
}

func fetchVersion() string {
 fmt.Println("app/fetch-version.go ==> fetchVersion()")
 return version.Version
}

/***************************/

// app/entry.go
package main

import "fmt"

func init() {
 fmt.Println("app/fetch-version.go ==> init()")
}

var myVersion = fetchVersion()

func main() {
 fmt.Println("app/fetch-version.go ==> fetchVersion()")
 fmt.Println("version ===> ", myVersion)
}