Go/Packages

Packages in Go

Every Go source file is part of some package. To declare what package it is a part of, you use package <packagename> at the top of the file:

package main

The above package declaration must be the first line of code in your Go source file. All the functions, types, and variables defined in your Go source file become part of the declared package.

Variables and functions can be public or private.

Using a package

To use a package, e.g., the "fmt" package in the standard Go library, you import it:

package main

import "fmt"

Import multiple libraries using multiple import statements, or putting () around the package names:

package main

// either
import "fmt"
import "math"

// or
import (
    "fmt"
    "math"
)

Creating a package

To create a package, start in your Go workspace. This is set by GOPATH (see Go/Installing#Paths for more on these environment variables).

All import paths are relative to the src directory of your Go workspace. Suppose your GOPATH is at ~/go. Then your Go workspace will be organized like this:

/home/username/go
            pkg/      # holds package archives
            bin/      # holds binary executables
            src/      # holds source code

Layout of (existing) repo and packages

You can lay out the package as you wish, just remember that using "import" will import the library from $GOPATH/src and not from $GOPATH.

Typically, we organize related functions into packages, and we keep one or more packages in a repository. We then keep a copy of this repository in our $GOPATH.

Let's look at an example: suppose we have a package named greasy_grimy_gopher_guts on Github. Then one way of organizing the directory might be:

/home/username/go
            src/
                github.com/
                    username/
                        greasy_grimy_gopher_guts/
                            # This is the top level of our repository,
                            # which contains one or more packages

Then we would have one directory in the repository for each package that we wanted to define. We would also include a main package somewhere in the repository, so we have an entry point for our program. When we tell go to install the main package, it will turn that main package into a command line executable that will execute the main function of this program.

Adding a package to the repo dir

Suppose we have a package called "primecheck" that just provides a single function to check if a number is prime. Then we can add it to the repository contents like so:

/home/username/go/src/github.com/username/greasy_grimy_gopher_guts/
            numbers/
                primecheck.go

Here is the prime number check function in primecheck.go:

package numbers

import "math"

// Checks if a number is prime or not
func IsPrime(num int) bool {
    for i := 2; i <= int(math.Floor(math.Sqrt(float64(num)))); i++ {
        if num%i == 0 {
            return false
        }
    }
    return num > 1
}

Next we will add a Go file with a main package, and use go install to turn the main method into a command line utility.

Let's write a main method that prints out all prime numbers under 10, and make it into a command line utility called gopherguts. Here is the directory structure:

/home/username/go/src/github.com/username/greasy_grimy_gopher_guts/
            numbers/
                primecheck.go
            gopherguts/
                app.go

Here is the contents of the app.go file. Here we are going to import the numbers package we created:

package main

import (
	"fmt"
        "github.com/username/greasy_grimy_gopher_guts/numbers"
)

func main() {
    for i:=0; i<10; i++ {
        if numbers.IsPrime(i) {
            fmt.Println(i)
        }
    }
}

An alternate directory layout

Alternatively, we could go with a simpler directory layout:

/home/username/go
            src/
                greasy_grimy_gopher_guts/
                    # This is the top level of our package's repository

In this case, the import statement in our repository's main package get simpler too:

package main

import (
	"fmt"
        "greasy_grimy_gopher_guts/numbers"
)

func main() {
    for i:=0; i<10; i++ {
        if numbers.IsPrime(i) {
            fmt.Println(i)
        }
    }
}

Github Packages

(Fill in here...)

Travis CI Testing of Packages

(More details to here)

Resources

nice explanation, top-down: https://golang.org/doc/code.html

https://www.callicoder.com/golang-packages/