What is the purpose of declaring a package?

Question

Each Go file starts with package <something> .

As far as I understand - and probably where I do not have enough information, for <something> there are only two possible values: the name of the directory in which it is located, * or main . If it is main , all other files in this directory can have only main . If this is something else, the project contradicts / violates the agreement.

Now, if this is a directory name, it is redundant because the same information, well, in the directory name.

If this is main , this is useless because, as far as I see, there is no way to say go build "please create all the main packages."

^{* Because, in other words, one directory is one package.}

Answer 1

The package name must not match the directory name. In the xyz/go-foobar directory, you can have package foobar . In this case, xyz/go-foobar becomes the import path , but the package name that you use to ensure the quality of identifiers (functions, types, etc.) will be foobar .

Here is an example to make it more specific: I created a test package http://godoc.org/github.com/dmitris/go-foobar (source at https://github.com/dmitris/go-foobar ) - you can see on the documentation page that the import path is "github.com/dmitris/go-foobar" but the package name is foobar , so you call the function that it provides as foobar.Demo() (not go-foobar.Demo() ).

A similar real-life example is the import path for the NSQ Messaging platform is "github.com/nsqio/go-nsq" and the package name is "nsq": http://godoc.org/github.com/nsqio/go-nsq . However, for convenience and simplicity, the standard and recommended practice is to keep the last parts of the import path and package name the same whenever possible.

package main not useless - it tells the Go compiler to create an executable file, not a library .a file (with go install or go get ; go build discards the compilation result). The executable file has a name after the name of the directory in which the file or package main files are placed. And again a specific example - I made a test program https://github.com/dmitris/go-foobar-client , you installed it with go get github.com/dmitris/go-foobar-client , and you should get an executable file go-foobar-client in the $ GOPATH / bin directory. This is from the name of the directory where the package main file is located, which the Go compiler accepts the name of the executable file. The name of the .go file that contains the main() function does not matter - in the above example, we can rename main.go to client.go or something else, but for now the calling directory is called go-foobar-client , the way the resulting executable will be called.

For additional accessible and practically oriented reading about Go packages, I recommend Dave Cheney's article “Five suggestions for creating a Go project” http://dave.cheney.net/2014/12/01/five-suggestions-for-setting-up-a -go-project .

Answer 2

The invalid information that you have is that the package name must not match the directory name.

It is perfectly fine to use a package name other than a folder name. If you do this, you will still have to import the package based on the directory structure, but after importing you should refer to it by the name that you used in the package offer.

For example, if you have a folder $GOPATH/src/mypck , and there is a.go file in it:

 package apple const Pi = 3.14 

Using this package:

 package main import ( "mypck" "fmt" ) func main() { fmt.Println(apple.Pi) } 

Just as you are allowed to use relative imports, but it is not recommended, you can use other package names that contain their folder, but it is also not recommended to avoid further misunderstanding.

Note that the specification does not even require that all files belonging to the same package be in the same folder (but this may be an implementation requirement). Spec: Package Offer:

A set of files that have the same PackageName is an implementation of the package. An implementation may require that all source files for a package be in the same directory.

What use is this?

Simple Package Name - Go identifier :

 identifier = letter { letter | unicode_digit } . 

That allows you to use Unicode characters in identifiers, for example. αβ is a valid identifier in Go. File and file names are not processed by Go, but by the operating system, and different file systems have different restrictions. In fact, there are many file systems that will not allow all valid Go identifiers as folder names, so you won’t be able to name your packages, which would otherwise allow the language specification.

Thus, in one hand, not all valid Go identifiers may be valid folder names. On the other hand, not all valid folder names are valid Go identifiers, for example go-math is a valid folder name on most (all?) File systems, but it is not a valid Go identifier (since identifiers cannot contain dashes - ).

Having the ability to use package names other than their containing folders, you have the opportunity to really name your packages, which allows the language specification, regardless of the base operating system and file system, and place it in a folder with the name, the base OS and file system allow you to - regardless of the package name.