Understanding Go Packages

Without this basic knowledge your productivity with Go will fall down quickly.

What are Go packages?

Go packages are grouping units for code and helps you to organize your project. As the name implies as “package”, it allows you to “ pack ” one or more source code files in a single unit, as a package.

Go packages allow reusability by letting you to use your own or other packages in your code. When you don’t reuse, you’ll be repeating yourself and that is time-consuming and boring.

For example: If you have a code which does some calculation for weather statistics and is being used by more than one code in your program, you would put this calculation code in a separate package, maybe named as: statistics.

Any code written in Go belongs to a package. 
There is no Go code which doesn’t belong to a package. Go programs are composed of single or many packages_._

A package represents a single concept.
So, they’are not generic like: common, utility, helper etc. They’re more like: http, json, xml, crypto, fmt. So, you shouldn’t put any code beyond the package’s sole purpose, and it’s important to name the packages appropriately.

For example : Go’s zip package provides only one concept: zipping things. Or, http package provides only one concept again: client/server interactions of http. Or, fmt package: Handling the formatting of input/output.

A package can contain zero or more functionality and state.
There can be a package that only contains one function such as that calculating the tax ratio for some countries. This is totally valid. Go packages don’t need to be big as in some other languages.

A package can be used by other packages.
And, of course, a package can use its own functionalities which some of are not available to the other packages, and some are only available to the package itself.

A package imported only once. 
You can import the same package in many packages, and, it will be imported only once.

No packages?

Without packages there would be almost no code reusability, and organization.

It’d kill the simplicity and explicitness (which are some of the virtues of Go). Take a look at Go’s standard library, here. Without packages, how would you use Go’s massive standard library in your own code? Functionalities would be in everywhere, scattered, and it’d be impossible to work with.

How a Go package looks like?

“example” package. This is just a directory in your computer. A package resides in a directory.

All the source files in the example package directory have the same package name: example.

Physically, a package is just a directory. By convention, in Go, directory names and the package names should be the same. Go tools and almost all of the Go community uses this convention. So, stick to it.

In a package directory, all source files belong to only one package. package keyword declares that the file belongs to example package. A source code file should have a package, always.

Importing packages

import keyword allows you to use other packages. It’s used after the package keyword at the top of your source file.

Let’s try something basic

This file belongs to package main. You can run this code here. I ran it through my command line interface (CLI) by typing: go run main.go.

Belongs to main package.

Output of main.go.

An Exercise for You

To really learn something, you need to try it on your own.

• Open the sample code and import time package by typing import time.
• Display the time by typing fmt.Println(time.Now()) in a new line after fmt.Println(“i am main.”) line and run the code.
• Code for the exercise is here. Compare it with yours. Now, delete all the lines and type the program from your memory by yourself, without looking to the exercise sample.

Another Exercise for You

• Open the code and change package main to package notmain and run it by clicking the Run button above
• Then, look at the error message at the bottom. That’s because, every runnable program should have at least one main package.
• Try to change other things like, delete import fmt line to see what happens.

Because this post became too long, I’ve splitted it into the following posts:

Using Go Packages
👉 How to use your own, others’ and Go standard library’s packages?

Special Packages and Directories in Go
👉 There are some special packages and directories in Go which allows go tools and us to manage the behavior of our code.

Packages Provide Encapsulation
👉 Encapsulation allows us to expose or hide some part of our code to the outside code.

Code organization tips with packages
👉 How to organize Go code with packages?

Summary of Go Packages
👉 One bit at a time summary about Go packages.

How to use $GOPATH and $GOROOT
👉 What are they and what values they should have?

❤️ Please share this post on twitter, reddit and hackernews. ❤️

I’m mostly tweeting about Go, you can follow me on twitter: @inancgumus.

I’m also creating an online course to teach Go. To get notified about it, please follow this publication and join the email list!

You will receive Go tips, tutorials and notifications about my upcoming online Go course.

Click on the image to subscribe to “I’m Learning Go” email list! Thank you!

Originally published on September 26, 2017 in “Learn Go Programming.” publication. Click to the link to go to the tutorial series.