In this tutorial, we will talk about packages.

So what are packages?

A package is nothing but a directory containing one or more Go source files, or other Go packages.

This means every Go source file must belong to a package and package declaration is done at top of every source file as follows.

package <package_name>

So far, we've done everything inside of package main. By convention, executable programs (by that I mean the ones with the main package) are called Commands, others are simply called Packages.

The main package should also contain a main() function which is a special function that acts as the entry point of an executable program.

Let's take a look at an example by creating our own package custom and adding some source files to it such as code.go.

package custom

Before we proceed any further, we should talk about imports and exports. Just like other languages, go also has a concept of imports and exports but it's very elegant.

Basically, any value (like a variable or function) can be exported and visible from other packages if they have been defined with an upper case identifier.

Let's try an example in our custom package.

package custom

var value int = 10 // Will not be exported
var Value int = 20 // Will be exported

As we can see lower case identifiers will not be exported and will be private to the package it's defined in. In our case the custom package.

That's great but how do we import or access it? Well, same as we've been doing so far unknowingly. Let's go to our main.go file and import our custom package.

Here we can refer to it using the module we had initialized in our go.mod file earlier.

---go.mod---
module example

go 1.18

---main.go--
package main

import "example/custom"

func main() {
    custom.Value
}

Notice how the package name is the last name of the import path

We can import multiple packages as well like this.

package main

import (
    "fmt"

    "example/custom"
)

func main() {
    fmt.Println(custom.Value)
}

We can also alias our imports to avoid collisions like this.

package main

import (
    "fmt"

    abcd "example/custom"
)

func main() {
    fmt.Println(abcd.Value)
}

External Dependencies

In Go, we are not only limited to working with local packages, we can also install external packages using go install command as we saw earlier.

So let's download a simple logging package github.com/rs/zerolog/log.

$ go install github.com/rs/zerolog

package main

import (
    "github.com/rs/zerolog/log"

    abcd "example/custom"
)

func main() {
    log.Print(abcd.Value)
}

Also, make sure to checkout the go doc of packages you install, which is usually located in the project's readme file. go doc parses the source code and generates documentation in HTML format. Reference to It is usually located in readme files.

Lastly, I will add that, Go doesn't have a particular "folder structure" convention, always try to organize your packages in a simple and intuitive way.

This article is part of my open source Go Course available on Github.