The gomote command is a client for the Go builder infrastructure. It's a remote control for remote Go builder machines.
gomote [global-flags] cmd [cmd-flags] For example, $ gomote create openbsd-amd64-60 user-username-openbsd-amd64-60-0 $ gomote push user-username-openbsd-amd64-60-0 $ gomote run user-username-openbsd-amd64-60-0 go/src/make.bash $ gomote run user-username-openbsd-amd64-60-0 go/bin/go test -v -short os
To list the subcommands, run "gomote" without arguments:
Commands: create create a buildlet; with no args, list types of buildlets destroy destroy a buildlet gettar extract a tar.gz from a buildlet list list active buildlets ls list the contents of a directory on a buildlet ping test whether a buildlet is alive and reachable push sync your GOROOT directory to the buildlet put put files on a buildlet put14 put Go 1.4 in place puttar extract a tar.gz to a buildlet rm delete files or directories rdp RDP (Remote Desktop Protocol) to a Windows buildlet run run a command on a buildlet ssh ssh to a buildlet
To list all the builder types available, run "create" with no arguments:
$ gomote create (list tons of buildlet types)
The "gomote run" command has many of its own flags:
$ gomote run -h run usage: gomote run [run-opts] <instance> <cmd> [args...] -builderenv string Optional alternate builder to act like. Must share the same underlying buildlet host type, or it's an error. For instance, linux-amd64-race is compatible with linux-amd64, but openbsd-amd64 and openbsd-386 are different hosts. -debug write debug info about the command's execution before it begins -dir string Directory to run from. Defaults to the directory of the command, or the work directory if -system is true. -e value Environment variable KEY=value. The -e flag may be repeated multiple times to add multiple things to the environment. -path string Comma-separated list of ExecOpts.Path elements. The special string 'EMPTY' means to run without any $PATH. The empty string (default) does not modify the $PATH. Otherwise, the following expansions apply: the string '$PATH' expands to the current PATH element(s), the substring '$WORKDIR' expands to the buildlet's temp workdir. -system run inside the system, and not inside the workdir; this is implicit if cmd starts with '/'
Debugging buildlets directly ¶
Using "gomote create" contacts the build coordinator (farmer.golang.org) and requests that it create the buildlet on your behalf. All subsequent commands (such as "gomote run" or "gomote ls") then proxy your request via the coordinator. To access a buildlet directly (for example, when working on the buildlet code), you can skip the "gomote create" step and use the special builder name "<build-config-name>@ip[:port>", such as "email@example.com".
Instances may be managed in named groups, and commands are broadcast to all instances in the group.
A group is specified either by the -group global flag or through the GOMOTE_GROUP environment variable. The -group flag must always specify a valid group, whereas GOMOTE_GROUP may contain an invalid group. Instances may be part of more than one group.
Groups may be explicitly managed with the "group" subcommand, but there are several short-cuts that make this unnecessary in most cases:
- The create command can create a new group for instances with the -new-group flag.
- The create command will automatically create the group in GOMOTE_GROUP if it does not exist and no other group is explicitly specified.
- The destroy command can destroy a group in addition to its instances with the -destroy-group flag.
As a result, the easiest way to use groups is to just set the GOMOTE_GROUP environment variable:
$ export GOMOTE_GROUP=debug $ gomote create linux-amd64 $ GOROOT=/path/to/goroot gomote create linux-amd64 $ gomote run go/src/make.bash
As this example demonstrates, groups are useful even if the group contains only a single instance: it can dramatically shorten most gomote commands.
Tips and tricks ¶
- The create command accepts the -setup flag which also pushes a GOROOT and runs the appropriate equivalent of "make.bash" for the instance.
- The create command accepts the -count flag for creating several instances at once.
- The run command accepts the -collect flag for automatically writing the output from the command to a file in $PWD, as well as a copy of the full file tree from the instance. This command is useful for capturing the output of long-running commands in a set-and-forget manner.
- The run command accepts the -until flag for continuously executing a command until the output of the command matches some pattern. Useful for reproducing rare issues, and especially useful when used in tandem with -collect.
- The run command always streams output to a temporary file regardless of any additional flags to avoid losing output due to terminal scrollback. It always prints the location of the file.
Using some of these tricks, it's straightforward to hammer at some test to reproduce a rare failure, like so:
$ export GOMOTE_GROUP=debug $ GOROOT=/path/to/goroot gomote create -setup -count=10 linux-amd64 $ gomote run -until='unexpected return pc' -collect go/bin/go run -run="MyFlakyTest" -count=100 runtime