🫶 The 'main()' function, 'main' package and 'main.go' file in Go

To run an application in Go as an executable program you need an entry point - the place where the program execution begins. Such an entry point is the main() function in the package named main. When you compile your Go program, the main() function in the main package is automatically compiled into an executable file. This executable file can then be executed on any machine that has a compatible operating system and architecture.

The main package

In Go, every .go file starts with a package declaration:

1
2
3
4

package main

// the rest of the .go file
// ...

The package name is arbitrary, but a package named main has a special meaning. When you name your package like this, it is an indicator to the Go environment that it should be compiled into an executable program. In this package, the compiler will look for the main() function, which is the entry point of the application.

The main() function

The main() function is the entry point of any executable program. It is the function that the Go runtime calls to start the program. The main() function must have no arguments and no return values.

Here is an example of a basic main() function in Go:

1
2
3
4
5
6
7

package main

import "fmt"

func main() {
    fmt.Println("Hello, world!")
}

In this example, the main() function is the starting point of the program. It simply prints out "Hello, world!" to the console using the fmt.Println() function. As you already know, the main() function must be defined in a file with a package main. This tells the Go compiler that the file contains the entry point for an executable program.

The main() function can include any Go code that you want to execute when the program starts. It is the first function that is executed when you run the app. Typically, it sets up the initial state of the program, performs any necessary initialization, and then starts the program’s main loop.

The main.go file

The file main.go is the conventional name of the file in which the entry point to the program is located, that is, the main() function in the main package. In fact, this file can have any name you like, e.g. start.go, but it is good to follow the convention and always call such a file main.go. This makes it easier to find the starting point in the project.

Run the main.go file

Once you have the main() function defined in the main package in the main.go file, you can go ahead and run your program. To run a main.go file, you can follow these steps:

1. Open your Terminal or command prompt.
2. Navigate to the directory where your main.go file is located.
3. Type the command go run main.go in the Terminal and press Enter. This command will compile and run your Go program. If there are no errors in your code, you should see the output in the Terminal.

Alternatively, if you want to compile your Go program into an executable file, you can follow these steps:

1. Open your Terminal and navigate to the directory where your main.go file is located.
2. Use the command go build in the Terminal. This will generate an executable with the same name as your source code directory. You can then run this file by typing ./myapp in the Terminal.

FAQ

We cover more advanced topics in the form of answers to frequently asked questions.

Where to put the main.go file in the project?

The location of the main.go file can vary depending on the specific project and development environment you are using. In theory, the location inside the project can be whatever you want, the only thing to remember is that all files in the directory where main.go is located must be of the main package.

In practice, however, there are two common approaches to locating the main.go file.

• Putting the main.go file in the root directory of the project - if you are creating a small project or a single-file Go program.

myapp/
├── somecode.go
├── ...
└── main.go

• For larger projects, it is common to organize code into packages and subdirectories. Commands (executable programs) are usually placed in a directory named cmd. In the cmd directory, you can create a subdirectory for each command you want to build, and each subdirectory contains a main.go file with the main package and main() function.

myapp/
├── cmd
│   ├── app1
│   |   └── main.go
│   └── app2
│       └── main.go
├── pkg/
│   └── ...
├── internal/
│   └── ...
└── ...

Is the main.go file, the main package and the main() function required in a Go project?

No, a Go project does not need to have a file, package and function main. Then it is not intended to be built as an executable program, but rather as a package (library) that can be imported and used by other programs.

The main() function in the main package is required in a Go project that is intended to be built as an executable program. This function is the entry point of the program and it is where the execution of the program begins.

Is it possible to import the main package?

No, you cannot import the main package in Go. The main is a special package that is used to create executable programs. It is not intended to be imported by other packages. Trying to do this you will get an error from the compiler: import "<package-name>" is a program, not an importable package.

Other packages that you create can be imported by the main package, but the main itself cannot be imported by any other package.

What is the difference between the main() and init() functions in Go?

The init() and main() are two distinct functions with different purposes.

The init() is a special function that is executed automatically when a Go program starts. Its purpose is to perform any initialization tasks that need to be done before the main() function runs. The init() can be defined in any package, and multiple such functions can be defined in the same package. They are then run all before the main() function.

The main() function is the entry point of a Go program. It is the function that is executed when the application starts. It can be defined only once in a program, and it must be defined in the main package.

To summarize, the init() function is used for initialization tasks, and it is executed automatically before the main() function. The main() is the entry point of a Go program, and it is executed after the init() function (if it exists).

Can I have multiple main() functions in one project?

In Go, it is not possible to have multiple main() functions in the same main package. This is because the main() is a special function that serves as the entry point for the executable program.

However, you can have multiple main packages in the same project, each with its own main() function. The only requirement is that each of these main packages be in a separate folder. This is how you organize the code in projects that have multiple executables. Each command (executable program) is placed in a separate subfolder in the cmd directory. Each such subfolder contains the main.go file with the main() function in the main package. See the answer to the question “Where to put the main.go file in the project?” for more details.

Can the main package in Go consist of multiple files?

Yes, the main package in Go can consist of multiple files. The only disadvantage you need to keep in mind is that you need to specify all the files containing the main package when running through the go run command. Also, a multi-file main package, like a single-file package, can only contain one main() function.

Let’s assume that you want to split the main package into two files: main.go and foo.go:

myapp/
├── foo.go
└── main.go

An example code of the main.go file:

package main

func main() {
    foo()
}

An example code of the foo.go file:

package main

import "fmt"

func foo() {
    fmt.Println("foo")
}

As you can see, both files belong to the main package.

If you run the above program with the go run main.go command, you will get an error: ./main.go:4:2: undefined: foo. This is because you have not specified all the main package files that are needed to run the application. If you run this program with the go run main.go foo.go command, then it will run without errors:

foo

Providing a list of all the files of the main package to the go run can be troublesome especially if this package is split into many files. Therefore, some simplification has been made and the multi-file main package can also be run via the go run . command, which runs all the files in the current folder.

If you run the go build or go install commands you must also remember to specify all the files of the main package: go build main.go foo.go or use the default versions of these commands that build/install files from the current directory: go build and go install.

Does the main package have to contain the main() function?

Yes, in Go, the main package must contain a function named main(). When you run a program, the Go compiler looks for the main() function in the main package and executes it. If the main() function is not present or has a different signature, the compiler will not be able to execute the program, and you will get a compile-time error: runtime.main_main·f: function main is undeclared in the main package.