257

Note: this question is related to this one, but two years is a very long time in Go history.

What is the standard way to organize a Go project during development ?

My project is a single package mypack, so I guess I put all the .go files in a mypack directory.

But then, I would like to test it during development so I need at least a file declaring the main package, so that I can do go run trypack.go

How should I organize this ? Do I need to do go install mypack each time I want to try it ?

Aakash Goyal
  • 1,051
  • 4
  • 12
  • 44
Blacksad
  • 14,906
  • 15
  • 70
  • 81
  • 16
    This brief screencast is awesome: http://www.youtube.com/watch?v=XCsL89YtqCs – Matt May 28 '13 at 16:17
  • [This](http://www.goinggo.net/2013/07/how-packages-work-in-go-language.html) is another helpful link in understanding how to organize a project with packages. Easier to follow than the official How to Write go Code I think. – IamNaN Apr 09 '15 at 06:33
  • For the new Go modules system, this [answer](https://stackoverflow.com/a/57314494/11210494) covers module structure, arranging packages within a module, whether or not to have multiple modules in single repository, etc. Eventually, the official ["How to Write Go Code"](http://golang.org/doc/code.html) intro document will be updated for modules, but that hasn't happened yet. (If you are new to Go and new to Go modules, it is still worth reading that "How to Write Go Code" document before reading more about modules given much of the modules documentation assumes familiarity with GOPATH). – thepudds Aug 02 '19 at 20:36

7 Answers7

176

I would recommend reviewing this page on How to Write Go Code

It documents both how to structure your project in a go build friendly way, and also how to write tests. Tests do not need to be a cmd using the main package. They can simply be TestX named functions as part of each package, and then go test will discover them.

The structure suggested in that link in your question is a bit outdated, now with the release of Go 1. You no longer would need to place a pkg directory under src. The only 3 spec-related directories are the 3 in the root of your GOPATH: bin, pkg, src . Underneath src, you can simply place your project mypack, and underneath that is all of your .go files including the mypack_test.go

go build will then build into the root level pkg and bin.

So your GOPATH might look like this:

~/projects/
    bin/
    pkg/
    src/
      mypack/
        foo.go
        bar.go
        mypack_test.go

export GOPATH=$HOME/projects

$ go build mypack
$ go test mypack

Update: as of >= Go 1.11, the Module system is now a standard part of the tooling and the GOPATH concept is close to becoming obsolete.

jdi
  • 90,542
  • 19
  • 167
  • 203
  • 31
    Use $HOME instead of ~ when exporting variables. – Johan S May 20 '13 at 17:22
  • 7
    Why is $HOME recommended over ~ when exporting variables? – 425nesp Aug 01 '14 at 21:28
  • 10
    Because ~ is not a variable, just an alias. – Pih Aug 03 '14 at 18:06
  • 7
    @425nesp Johan is mistaken -- it's not. Shells vary, but [bash expands `~` when setting environmental variables](https://www.gnu.org/software/bash/manual/html_node/Tilde-Expansion.html), and so does the busybox bourne shell, for instance. Try it yourself: `export BOB=~ && env | grep ^BOB` will yield `BOB=/your/homedir` – Austin Adams Jul 03 '15 at 19:49
  • 6
    `$HOME` works in more shells then `~`, for example in `fish` – hoijui Mar 23 '19 at 06:24
61

jdi has the right information concerning the use of GOPATH. I would add that if you intend to have a binary as well you might want to add one additional level to the directories.

~/projects/src/
    myproj/
        mypack/
            lib.go
            lib_test.go
            ...
        myapp/
            main.go

running go build myproj/mypack will build the mypack package along with it's dependencies running go build myproj/myapp will build the myapp binary along with it's dependencies which probably includes the mypack library.

Community
  • 1
  • 1
Jeremy Wall
  • 23,907
  • 5
  • 55
  • 73
  • This would make sense, of course, if he did actually have a main cmd. Seemed like he is just creating a library package. – jdi Apr 03 '12 at 03:27
51

I have studied a number of Go projects and there is a fair bit of variation. You can kind of tell who is coming from C and who is coming from Java, as the former dump just about everything in the projects root directory in a main package, and the latter tend to put everything in a src directory. Neither is optimal however. Each have consequences because they affect import paths and how others can reuse them.

To get the best results I have worked out the following approach.

myproj/
  main/
    mypack.go
  mypack.go

Where mypack.go is package mypack and main/mypack.go is (obviously) package main.

If you need additional support files you have two choices. Either keep them all in the root directory, or put private support files in a lib subdirectory. E.g.

myproj/
  main/
    mypack.go
  myextras/
    someextra.go
  mypack.go
  mysupport.go

Or

myproj.org/
  lib/
    mysupport.go
    myextras/
      someextra.go
  main/
    mypack.go
  mypage.go

Only put the files in a lib directory if they are not intended to be imported by another project. In other words, if they are private support files. That's the idea behind having lib --to separate public from private interfaces.

Doing things this way will give you a nice import path, myproj.org/mypack to reuse the code in other projects. If you use lib then internal support files will have an import path that is indicative of that, myproj.org/lib/mysupport.

When building the project, use main/mypack, e.g. go build main/mypack. If you have more than one executable you can also separate those under main without having to create separate projects. e.g. main/myfoo/myfoo.go and main/mybar/mybar.go.

AndreKR
  • 32,613
  • 18
  • 106
  • 168
trans
  • 1,411
  • 1
  • 13
  • 13
  • 15
    Idomatic is to use a `cmd/nameOfMyExecutable` sub-directory for the main package (only need `cmd/…` if you have multiple commands; see `golang.org/x/tools/cmd`; otherwise it's common to swap it around and have `main.go` at the top level). The way you have it `go install` will create a "main" (or "main.exe") executable. Also, idiomatic is to use an `internal` sub-directory for a sub-package internal to the package/program that's not meant to be used elsewhere (it is expected future versions of Go will enforce no one else importing `internal` packages done this way). – Dave C Jun 06 '15 at 18:54
21

I find very useful to understand how to organize code in Golang this chapter http://www.golang-book.com/11 of the book written by Caleb Doxsey

edap
  • 1,084
  • 1
  • 10
  • 16
14

There doesn't seem to be a standard way of organizing Go projects but https://golang.org/doc/code.html specifies a best practice for most projects. jdi's answer is good but if you use github or bitbucket and you have additional libraries as well, you should create the following structure:

~/projects/
bin/
pkg/
src/
  github.com/
    username/
        mypack/
            foo.go
            bar.go
            mypack_test.go
        mylib/
            utillib.go
            utillib_test.go

By doing it this way, you can have a separate repository for mylib that can be used for other projects and can be retrieved by "go get". Your mypack project can import your library using "github.com/username/mylib". For more information:

http://www.alexvictorchan.com/2014/11/06/go-project-structure/

alexdotc
  • 268
  • 2
  • 7
7

Keep the files in the same directory and use package main in all files.

myproj/
   your-program/
      main.go
      lib.go

Then run:

~/myproj/your-program$ go build && ./your-program
Gustav
  • 2,902
  • 1
  • 25
  • 31
  • 1
    How can this work? Your main.go needs to be package main; presumably lib.go is in a different package, then the go tool complains that you can't have two packages in a single folder. – I82Much Jan 18 '14 at 23:45
  • 1
    @I82Much OP asks for how to divide one package, the main program, to many files. lib.go is in the same package in this case. – Gustav Jan 19 '14 at 17:47
  • @Gustav, I have the same question. It seems if I put package main in lib.go, in main.go, I cannot call functions defined in lib.go. –  Jan 24 '14 at 10:47
  • @ElgsQianChen The methods need to be public, it has to start with a capital letter. E.g. MyMethod() or MyStruct{...}. – Gustav Jan 24 '14 at 11:20
  • @Gustav yes, the method name is capitalized. It seems it works in any packages but main. –  Jan 24 '14 at 11:43
7

Let's explorer how the go get repository_remote_url command manages the project structure under $GOPATH. If we do a go get github.com/gohugoio/hugo It will clone the repository under

$GOPATH/src/repository_remote/user_name/project_name

$GOPATH/src/github.com/gohugoio/hugo

This is a nice way to create your initial project path. Now let's explorer what are the project types out there and how their inner structures are organized. All golang projects in the community can be categorized under

  • Libraries (no executable binaries)
  • Single Project (contains only 1 executable binary)
  • Tooling Projects (contains multiple executable binaries)

Generally golang project files can be packaged under any design principles such as DDD, POD

Most of the available go projects follows this Package Oriented Design

Package Oriented Design encourage the developer to keeps the implementation only inside it's own packages, other than the /internal package those packages can't can communicate with each other

Libraries

  • Projects such as database drivers, qt can put under this category.
  • Some libraries such as color, now follows a flat structure without any other packages.
  • Most of these library projects manages a package called internal.
  • /internal package is mainly used to hide the implementation from other projects.
  • Don't have any executable binaries, so no files that contains the main func.
 ~/$GOPATH/
    bin/
    pkg/
    src/
      repository_remote/
        user_name/
            project_name/
              internal/
              other_pkg/

Single Project

  • Projects such as hugo, etcd has a single main func in root level and.
  • Target is to generate one single binary

Tooling Projects

  • Projects such as kubernetes, go-ethereum has multiple main func organized under a package called cmd
  • cmd/ package manages the number of binaries (tools) that we want to build
 ~/$GOPATH/
    bin/
    pkg/
    src/
      repository_remote/
        user_name/
            project_name/
              cmd/
                binary_one/
                   main.go
                binary_two/
                   main.go
                binary_three/
                   main.go
              other_pkg/
noelyahan
  • 4,195
  • 1
  • 32
  • 27