Latest commit bbaa751
Mar 28, 2012
|Failed to load latest commit information.|
(up-to-date documentation at http://code.google.com/p/go-gb) To install, go-gb/gb> make install or > goinstall github.com/skelterjohn/go-gb/gb or > goinstall code.google.com/p/go-gb/gb or (if you like arch linux packages) visit https://aur.archlinux.org/packages.php?ID=54051 gb is nearly configuration-free project builder for the go language. Jumpstart For a single target which produces a command "X", make a directory called X and put all your source files in it. Have no subdirectories with other source. From within this directory you can run gb and it will build a binary named X. For a multiple target project, first create a workspace directory W (call it whatever you want, but it will be referred to as W here). In the directory W/x/y/z you can put the source files for a package that will be imported with the path "x/y/z" by any other target built within W. In the directory W/anything/c you can put the source files for a command that will be named c. To build everything, cd into W and run gb. Overview With gb, one only has to run the simple command line, gb, in order to bring all binaries up to date. To clean, gb -c. To install, gb -i. There are a few other options to do other tasks, but never should one have to write scripts that, for instance, specify lists of which source files should be used. gb figures that out by analyzing the directory structure and source. It works on a "one target per directory" rule to discover which source files are to be compiled with one another. The idea is to obviate the need for any sort of build script. gb will compile a set of "relevant targets" that exist within directories listed on the command line, and any other targets that these have an import depedence on. Note that a target in directory a/b/c will be included in this set if the directory a/b is listed in the command line. The most effective way to use gb is to have a top-level workspace directory for all your code, similar to the concept of a workspace with eclipse. Within the root directory, each target (whether it be a cmd or pkg) must reside entirely within its own subdirectory. Nested targets are allowed; source in a directory a/b will not be compiled with source in a directory a. When gb is run, it first recursively scans all subdirectories from its working directory to identify targets. Any directory that contains .go files or .c files will be identified as a target. Each target's name is then determined by first looking at its relative path, but can be overridden by either a gb.cfg file containing a new name, or a //target:<name> comment in one of the source files, before the package statement. This renaming of targets is primarily useful for projects that are intended to be installed with goinstall, which requires that the target name match a URL. If gb is run within a directory that has a valid target, the target's name will be taken from the containing directory, rather than the relative path, ".". gb will match target names with import statements found in the source to determine the workspace dependency structure. It will use this structure to do incremental building correctly. Packages are all built to the _obj directory in the root, and commands are built to the bin directory in the root. If -i is on, they will be copied to $GOROOT/pkg/$GOOS_$GOOARCH and $GOROOT/bin. gb.cfg If a directory has a file named "gb.cfg", gb will examine it for special settings. They are entered each on their own line, in the form "key=val". Currently valid keys are as follows. workspace=<relative path> Running gb in the current directory will pretend the working directory is the one specified by the relative path. target=<string> Set the package's import path or the binaries name. makefile=true Always build this target with a local makefile. ignore=true Never try to build a package in this directory. ignoreall=true Never try to build a package in this directory or any of its subdirectories. gcflags=<flag1> <flag2>... Include these flags on the compile line. proto=<plugin> Set the plugin for protobuf source generation. Protobufs After installing the libaries and plugins available from http://code.google.com/p/goprotobuf, gb can convert .proto files into useable Go files and build them into your target. A file x.proto will generate a source file x.pb.go. Note that a package cannot have *only* .proto files - gb requires at least one .go file to work. It is allowed for that go file to consist only of a package declaration. The plugin used for compilation can be set using the "proto" key in gb.cfg. Goyacc gb will recognize foo.y files and run "goyacc -o foo.y.go -p foo foo.y", generating a new source file foo.y.go to include in the build step. There must be at least one valid .go file already for gb to recognize the target, though this source file is allowed to have only the package declaration. Tips If your root contains a few packages and a few commands, but you only want to install the packages, run gb -Pi. You can encode some information in file names. If a common value for $GOOS or $GOARCH appears in the file name in the form of *_VALUE*.go, that file will only be included if it matches $GOOS or $GOARCH. The flag *_unix*.go will match any of the unix-based $GOOS options. Quickly check the build status of any target with gb -s. It will print out a list of targets, and will tell you if they are up to date or installed (if a target is installed, it is also up to date). Tell gb to use goinstall to download packages with gb -g. To build a simple one-target package or command, you can run gb from within its directory if you use either target.gb or a //target:<name> comment. If you are working on something in $GOROOT/src and something outside at the same time, you can run gb -R to build dependencies in $GOROOT. gb passes any command line arguments that begin with "-test." to testing binaries, when you run gb -t. Options: -i Install build pkgs and cmds to $GOROOT/pkg/$GOOS_$GOARCH and $GOROOT/bin, respectively. -c Remove all intermediate binaries. -N Remove all installed binaries. -b Definitely try to build. Useful when used as "-cb", to tell gb to first clean and then build. -g Tell gb to use goinstall to build remote packages available at one of the following websites: googlecode.com, github.com, bitbucket.org and launchpad.net. -G Same as -g, except goinstall fetches new code from the repository. -p Attempt to build a package immediately once its dependencies are met and a processor is free. -s List all targets that are relevant to the current build plan. If no directories are listed on the command line, all targets found will be listed. Otherwise, only targets that need to be up to date in order to bring the listed targets up to date will be listed. -S Same as "-s", except import dependencies are also printed. -t Run all tests contained in *_test.go source for the relevant targets. Behaves similarly to "make test". All additional command line arguments beginning with "-test." are passed to the test binary (see http://golang.org/cmd/gotest for details). -e Exclusive target list. Do not attempt to build any packages that aren't in the directories listed on the command line. -v Verbose. Print out all build instructions used. -m Use makefiles. If this flag is set, and a target contains a makefile, that makefile will be used to build. -f For use with "-M", force overwriting of makefiles. Otherwise you will be prompted when attempting to create a makefile for a target that already has one. -P Build/clean/install only packages. Useful if you have a set of helper commands to test your packages, but don't want to install them to $GOROOT. -C The same as "-P", but for commands. -R Add targets in $GOROOT/src to those that gb can build. They will not be built automatically, but if a local target has an import dependence on a target in $GOROOT/src, it will be brought up to date. This works with the "-s" option. Using "-Rs" will list any targets in $GOROOT/src that the local targets depend on. --makefiles Generate makefiles and a build script. In each relevant target, create a makefile that supports incremental building with the rest of the targets. The build script invokes each of the makefiles in a topological order, ensuring that running "./build" will always result in a correct build. --workspace Create workspace.gb files for all listed targets. Doing this allows you to run gb from within the target directories as if you were running gb from the directory you ran --workspace in. --gofmt Run gofmt on all source for relevant targets. --make-a-mess Do not clean up intermediate files, such as .6/.8, the _cgo directory and the _test directory. --testargs All command line arguments that follow --testargs will be passed on to the test binaries, and otherwise ignored.