Go Packages: Main, Imports, and Folders

Go organizes code into packages. This is a core concept. It keeps projects clean and modular.

Understanding packages is key to writing good Go code. This guide explains the essentials.

We will cover the main package, import statements, and folder layout.

What Is a Go Package?

A package is a collection of Go source files. They live in the same directory.

Every file begins with a package declaration. This names the package.

Packages help you reuse code. They also manage dependencies and scope.

If you're new, learn more about What Is Go (Golang) and Why Use It? first.

The Special "main" Package

The main package is unique. It defines an executable program.

It must have a function named main. This is the program's entry point.

Other packages are for building libraries. They cannot be run directly.

// File: hello.go
package main // Declares this as the main package

import "fmt"

// The main function is the entry point
func main() {
    fmt.Println("Hello, from the main package!")
}
    

Save this file and run it. Use the terminal command go run hello.go.

$ go run hello.go
Hello, from the main package!
    

Using Import Statements

The import keyword brings in other packages. You can use their functions.

Imports are declared right after the package line. Use parentheses for multiple packages.

Go has a rich standard library. Packages like fmt and net/http are built-in.

package main

import (
    "fmt"       // For formatted I/O
    "math/rand" // For random numbers
    "time"      // For time functions
)

func main() {
    rand.Seed(time.Now().UnixNano())
    num := rand.Intn(100)
    fmt.Printf("Your random number is: %d\n", num)
}
    

You can also import third-party packages. Use go get to download them first.

Organizing Code with Folder Structure

Folder structure is vital in Go. It defines your package's identity and dependencies.

A package's name is the last element of its import path. This matches its folder name.

Keep your project inside the Go workspace. This is typically your GOPATH or a Go module root.

Basic Project Layout

Here is a simple but effective structure for a project named "myapp".

myapp/
├── go.mod          # Module definition file
├── main.go         # Main package, entry point
└── pkg/
    └── calculator/
        ├── calc.go # Package 'calculator'
        └── calc_test.go
    

The pkg/calculator folder holds a library package. The main.go file uses it.

Example: A Multi-Package Project

Let's build a small project. It uses a custom package for math operations.

First, create the library package.

// File: pkg/calculator/calc.go
package calculator // Package name is 'calculator'

// Add returns the sum of two integers
func Add(a int, b int) int {
    return a + b
}

// Multiply returns the product of two integers
func Multiply(a int, b int) int {
    return a * b
}
    

Now, create the main application file.

// File: main.go
package main

import (
    "fmt"
    "myapp/pkg/calculator" // Import our custom package
)

func main() {
    sum := calculator.Add(5, 3)
    product := calculator.Multiply(5, 3)

    fmt.Printf("Sum: %d\n", sum)
    fmt.Printf("Product: %d\n", product)
}
    

Initialize a Go module first. Run go mod init myapp in the project root.

Then run the program.

$ go run main.go
Sum: 8
Product: 15
    

Notice the import path. It is "myapp/pkg/calculator". This matches the folder structure.

Key Rules and Best Practices

Follow these rules for clean and functional Go code.

1. Package Naming

Use short, lowercase, single-word names. Make them descriptive.

Package names are part of the public API. Choose them carefully.

2. Exported vs Unexported Identifiers

Capitalized names are exported. They are visible outside the package.

Lowercase names are unexported. They are private to the package.

package mypkg

var PublicVar int = 10 // Exported, can be used by other packages
var privateVar int = 5 // Unexported, only usable within mypkg

func PublicFunc() {}  // Exported function
func privateFunc() {} // Private function
    

3. The init() Function

A package can have an init function. It runs automatically when the package is imported.

Use it for setup tasks. You can have multiple init functions per file.

Conclusion

Mastering packages is a fundamental step in learning Go.

The main package creates executables. Import statements bring in functionality.

A logical folder structure keeps your code maintainable. It aligns with Go's design philosophy.

Remember to use capital letters to export identifiers. Keep package names simple.

Start with these basics. They will help you build larger, more complex applications with ease.

For more on Go's advantages, revisit What Is Go (Golang) and Why Use It?.