Clone wiki

gofr / Home

Welcome to gofr!

Gofr (pronounced like "gopher") is a "Go (object) file recompiler"; in other words, it does all the work of analyzing your source tree and figuring out what it has to do to take the changed files and recompile them into binaries and libraries. It has been tested on linux and on darwin, and should theoretically be general enough to work on Windows as well, with the proper setup.

Gofr was initially started as a project to do the backend build for GoClipse (which you should definitely consider if you need an IDE), and grew from that into a really robust tool. Don't hesitate to fork it, tweak it, post bug reports, etc.


The gofr utility has numerous features which (its author would argue) are unavailable in a single package elsewhere:

  • Zero configuration required
    • gofr picks up all newest changes every time you run it automatically
  • Sensible package imports
    • Unlike with most other auto-builders, all package imports are interpreted as being relative to their location, e.g. src/file.go doesn't have to import "src/sub/pkg"
  • Multiple binaries and libraries
    • Any package in the tree with a main package will generate a binary. This can be used to automatically build tools to go along with your application or library.
    • Any package in the tree will be built, and if no binary is found in the base directory, they will all be linked into libraries.
  • Automatic testing support
    • Building on the gotest concepts, tests will run immediately following the build, and you can know immediately if you break one of your tests.
  • Incremental building
    • gofr will do as much as possible to keep from recompiling code that doesn't need to be recompiled to reduce compile times.
  • CGO support
    • gofr can automatically build CGO packages, including ones with local .c files, it just needs to be told what external libraries need to be linked in.
    • As of v3.0.0, gofr supports testing CGO packages and the new, relative dynamic library search paths
  • Gofmt support
    • gofr can automatically format source files if they don't match gofmt guidelines.
  • Automatic installation
    • gofr can automatically install libraries it builds into GOROOT and all binaries it builds into GOBIN.
  • Bash completion support
    • The source distribution includes a basic bash-completion script in the extra/ directory to help complete options for you.


Installation requires Mercurial (which at this point you should already have if you have a Go source tree). Installation is as simple as executing the following in the directory in which you want to check out gofr:

hg clone gofr
cd gofr && bash && cd -

The above commands will check out the latest gofr source, build it, and install it to $GOBIN ($HOME/bin by default), and run the built-in test script. It should complete with an "All tests passed!" message. If you do not have your GOBIN in your path, the built-in test will probably fail.


From the online help:

Usage of gofr:
        Compile all go souce files in the current directory tree
  -o        --binary         Name of binary (if not specified, will be file including main)
  -v        --verbose        Show commands as they are executed
  -V        --vverbose       Show very verbose debugging information
  -p        --pretend        Don't actually execute any commands (use with -v to see what would be executed
  -c        --clean          Remove the object, test, and library directories before building
  -C        --clean-only     Same as --clean, except exits after the objects are removed
  -f        --format         Format go source files if they do not adhere to gofmt rules
  -F        --no-format      Disable auto-formatting (the default)
  -t        --test           Automatically compile *_test.go files for a package and test them
  -x regex  --ignore=regex   Specify regular expressions of file paths to ignore (eXclude) (can specify multiple times)
  -l lib    --libs=lib       CGO Libraries (can specify multiple times)
  -I pkg    --install=pkg    Enable installation of the .a files and binaries into GOROOT and GOBIN under pkg/
  -P *      --prefix=*       Specify the installation prefix for the .a files (defaults to ${GOROOT}/pkg/${GOOS}_${GOARCH}/${PKG})
  -B *      --bin-prefix=*   Specify the installation prefix for the binaries (defaults to ${GOBIN}/${PKG})
  -O _obj   --objdir=_obj    The directory to put object files into
  -T _test  --testdir=_test  The directory to put test files into
  -N        --no-binaries    Suppress the creation of binaries (run in library mode, generating .a's)
            --version        Print version information and exit
            --help           show usage message

Using gofr: Learn by Example

gofr -v
gofr --verbose

Look at every single go source file in the directory tree and compile them. Compile main packages into binaries, and if there isn't one at the root directory, also create library files for every package encountered. Print out all of the commands that are being executed (-v).

gofr -f
gofr --format

Like above, except it will automatically format all go source files if necessary before compiling them (and it won't print the commands, as --verbose isn't specified)

gofr -t
gofr --test

Automatically link and execute test binaries based on the *_test.go files in each package. Note, you cannot have a test for a main package, because the generated main() will conflict with the real one. In these cases, you can make a pkg_test package that tests externally.

gofr -cv
gofr --clean --verbose

Clean the directory of object files and recompile everything from scratch, printing out all commands. Note that this will print out rm commands even if this is not the command on your system, it is actually using Go's internal file removal functionality.

gofr -NI
gofr --no-binaries

Build every package in the source directory and install them into GOROOT such that they can be included as import "<packagename>", but without building or installing any of the binaries

gofr -IB ${GOBIN}
gofr -I -B ${GOBIN}
gofr --bin-prefix=${GOBIN}

This assumes that there is a main package in the base directory; it will compile that package and install the linked binary into GOBIN. If you happen to have any CGO packages, because of the semantics of their compilation, they will be installed to GOROOT according to the argument to --install.

gofr -x experimental
gofr --ignore=experimental

While processing the directory, completely ignore every file that matches the regular expression /experimental/.


Thanks to everyone who helped out with testing gofr with their own projects, all of the Go nuts on the mailing lists, and especially to David Roundy for making goopt and for putting up with my pull requests.