Based on experimentation and from looking at the language spec, I want to try to pin-down how Go packaging works.
Honestly, I haven’t found Go’s packaging and import mechanism that intuitive so far. It is possible that I’m just not viewing things right - maybe I’m too used to how things are done in languages like Python, Java and C++.
But it could also be I don’t have the full picture, because I’ve been reading the language spec, which leaves certain decisions open to the toolchain. The toolchain provides several commands for building and running (
run), and several ways to specify what to build (by package, by file path or using wildcards).
So, here are the rules as far as I can tell.
For a library
- The name of the containing folder becomes the name of the binary library file. E.g. source files under a folder called
mystuffare compiled into
- The containing folder’s name and its path relative to
$GOPATH/srcform the package import-path. E.g. you would import the
github.com/munckymagik/mystuff, if this is the path to the
.afile relative to
- All source files within the package must declare the same package-name; but, this name does not need to be the same as the containing folder name. E.g. within the
mystufffolder, I could use the package-name
mystuffxxxwithin the source files. Then in client code, I would still import the package as
github.com/munckymagik/mystuff, but I would refer to its symbols using the package-name, like:
mystuffxxx.SymbolName. However, the convention (unsurprisingly) is to use a package-name that matches the containing folder name. I see this more as an indication of how things are actually working under the hood.
- The individual names of source files in the containing folder have no effect on the package name, how it’s imported, or how its symbols are resolved. The only reason to split a packages source into several files is to avoid having excessively large files. Nothing marked private within any of those files is private to any other file in the same folder!
- Source files that compile to executables must contain a
main()function and must be declared in the
mainpackage, regardless of what their folder path is relative to
- An executable source file can be built, run or installed by specifying its folder path relative to
go install path/to/myexe, in this case only one file within the
myexefolder may contain a
mainfunction, otherwise go will report a “main redeclared” error.
- An executable source file can be built or run directly using
go run path/to/myexe/filename.go. In this case, many files within the
myexefolder may contain
mainfunctions, go ignores the other files in the folder unless you list them on the command-line too.
- Within a folder containing one or more executable source files, shared source code may be placed into separate files. These files must also be declared in the
So folders are the unit-of-packaging and package names must match the containing folder names. Except for folders that contain executable