Projects

gb commands operate on a project. A gb project is a workspace which contains all the source needed to build and test your library or application.

A gb project is a folder on disk that contains a sub directory named src/. That’s it, no environment variables to set. For the rest of this document we’ll refer to your gb project as $PROJECT.

Your Stuff, Their Stuff

gb projects differentiate between your stuff—the code you’ve written—and their stuff—the code that your code depends on. We call their stuff “vendored code”. gb makes a distinction between your code and vendored code.

Inside a gb project, your stuff—the source code of your project—goes in:

$PROJECT/src/

The source code that others have written—their stuff—goes in:

$PROJECT/vendor/src/

Projects Do Not Live In $GOPATH

gb projects do not live inside your $GOPATH, nor does gb require you to set or update $GOPATH to use it.

gb does not use go get to manage a project’s dependencies; the owner of the project should copy any code on which project depends on into the $PROJECT/vendor/src/ directory.

gb projects can be retrieved using go get, but cannot be built by the go tool as they do not follow the convention required by go get.

Creating a Project

Creating a gb project is as simple as creating a directory:

% mkdir -p $HOME/code/demo-project

Obviously if you like to arrange your source code in another way, you’ll choose different name for your project’s directory. From now on we’ll refer to $HOME/code/demo-project as $PROJECT. We call this directory the project root.

Now you have created a project, you will need to create a folder inside your project root directory to hold your source code:

% mkdir -p $PROJECT/src
% tree $PROJECT
/home/dfc/code/demo-project
└── src

Creating a Package

Note: gb requires you to place all your code in packages inside $PROJECT/src/. Code placed at the root of your projects src/ directory will not be built; see issue #46.

Inside your source directory, let’s create a package:

% mkdir -p $PROJECT/src/hello
% tree $PROJECT
/home/dfc/code/demo-project
└── src
    └── hello

Next, let’s add a source code file to the package:

% cat <<EOF > $PROJECT/src/hello/hello.go
package main
import "fmt"
func main() {
    fmt.Println("Hello gb")
}
EOF
% tree $PROJECT
/home/dfc/code/demo-project
└── src
    └── hello
        └── hello.go

Compiling

Now that your project has some code in it, we can compile and run it:

% gb build all
hello
% bin/hello
Hello gb
% tree $PROJECT
/home/dfc/code/demo-project
├── bin
│   └── hello
└── src
    └── hello
        └── hello.go

Source Control Repository

Now that you’ve created a gb project, you should share that project with others by checking the entire contents of $PROJECT into the source control repository of your choosing. This includes any source you have copied from other projects into your $PROJECT/vendor/src/ directory. You don’t need to track $PROJECT/pkg nor $PROJECT/bin.

Next Up

Read through examples of using gb.