You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Gomote.md
+46-53Lines changed: 46 additions & 53 deletions
Original file line number
Diff line number
Diff line change
@@ -17,26 +17,26 @@ The most basic usage of the gomote tool involves just a few steps:
17
17
1. Push code to the instance.
18
18
1. Run commands on the instance.
19
19
20
-
Running the `create` command will list available instance types.
20
+
Running the `create` command with the `-list` flag will list available instance types.
21
21
22
22
```
23
-
$ gomote create
24
-
(list tons of buildlet types)
23
+
$ gomote create -list
24
+
(list tons of builder types)
25
25
```
26
26
27
27
Then, an instance can be created by specifying an instance type. The instance's name will be printed to stdout, so the result may be stored in an environment variable. (There may be other logging messages, but they will be on stderr and each line will have a '#' prefix.)
28
28
29
29
```
30
-
$ gomote create linux-amd64
31
-
# still creating linux-amd64 (1) after 5s; 0 requests ahead of you
32
-
user-linux-amd64-0
30
+
$ gomote create gotip-linux-amd64
31
+
# still creating gotip-linux-amd64 (1) after 5s; 0 requests ahead of you
32
+
user-gotip-linux-amd64-0
33
33
```
34
34
35
-
With that instance's name you can now push (more specifically sync the contents of) a local Go repository to the instance and install a bootstrap toolchain. The repository you sync will appear at the `go` subdirectory of `$WORKDIR` (the default directory of all gomote operations). The bootstrap toolchain will always go into the `go1.4` subdirectory (even if the bootstrap toolchain isn't from version 1.4).
35
+
With that instance's name you can now push a GOROOT to the instance and install a bootstrap toolchain. The repository you sync will appear at the `go` subdirectory of `$WORKDIR` (the default directory of all gomote operations). The bootstrap toolchain will always go into the `go1.4` subdirectory (even if the bootstrap toolchain isn't from version 1.4).
@@ -46,28 +46,36 @@ Note that `push` really is a "sync" operation, so next time you push the gomote
46
46
With a toolchain installed, you can now build it by running commands on the instance. The `run` command allows you to specify an executable to run. The executable must be specified relative to `$WORKDIR` (e.g. `go/bin/go`) or via an absolute path (e.g. `/bin/bash`). That executable will then run with its current working directory set to the directory containing the executable.
47
47
48
48
```
49
-
$ gomote run user-linux-amd64-0 go/src/make.bash
49
+
$ gomote run user-gotip-linux-amd64-0 go/src/make.bash
50
50
```
51
51
52
52
To then run the built Go toolchain, use `go/bin/go`.
53
53
54
54
```
55
-
$ gomote run user-linux-amd64-0 go/bin/go test -run="TestSomething" -v runtime
55
+
$ gomote run user-gotip-linux-amd64-0 go/bin/go test -run="TestSomething" -v runtime
56
56
```
57
57
58
-
You can additionally specify a working directory and environment variables to `run` that will be applied before the command is executed.
58
+
You can additionally specify a working directory and environment variables via flags to `run` that will be applied before the command is executed.
59
59
60
60
Note that gomote instances will automatically disappear after 30 minutes of inactivity. Use the `list` command to check how long they have left.
61
61
62
62
```
63
63
$ gomote list
64
-
user-linux-amd64-0 linux-amd64 host-linux-amd64-bullseye expires in 10m27.339494527s
64
+
user-gotip-linux-amd64-0 gotip-linux-amd64 gotip-linux-amd64 expires in 10m27.339494527s
65
65
```
66
66
67
67
The `ping` command can be used to keep an instance alive if no other commands are being run against it.
68
68
69
69
For more information on each command run `gomote help <command>`. For more commands, run `gomote help`.
70
70
71
+
### Builder types
72
+
73
+
Available builder types follow a certain structure, loosely `$GOBRANCH-($REPO-)?$GOOS-$GOARCH(_$OS)-$EXTRA`.
74
+
75
+
A few useful notes about these names.
76
+
- Different `$GOBRANCH` mainly modify the preinstalled tool versions, like the bootstrap Go toolchain.
77
+
- Builder types with `$REPO` will have the specified repository downloaded to the work root at tip-of-tree.
78
+
71
79
### Debugging buildlets directly
72
80
73
81
The `create` command 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 protected]`.
@@ -76,7 +84,7 @@ The `create` command contacts the build coordinator (farmer.golang.org) and requ
76
84
77
85
Instances may be managed in named groups, and commands are broadcast to all instances in the group.
78
86
79
-
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.
87
+
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.
80
88
81
89
Groups may be explicitly managed with the "group" subcommand, but there are several short-cuts that make this unnecessary in most cases:
82
90
@@ -88,7 +96,7 @@ As a result, the easiest way to use groups is to just set the `GOMOTE_GROUP` env
88
96
89
97
```
90
98
$ export GOMOTE_GROUP=debug
91
-
$ gomote create linux-amd64
99
+
$ gomote create gotip-linux-amd64
92
100
$ GOROOT=/path/to/goroot gomote push
93
101
$ gomote run go/src/make.bash
94
102
```
@@ -103,46 +111,46 @@ The `create` command accepts the `-setup` flag which also pushes a `GOROOT` and
# Pushing /path/to/my/goroot to user-gotip-linux-amd64-0
117
+
# Running make.bash on user-gotip-linux-amd64-0...
110
118
```
111
119
112
120
The `create` command accepts the `-count` flag for creating several instances at once.
113
121
114
122
Example:
115
123
```
116
-
$ gomote create -count=3 linux-amd64
117
-
# Creating user-linux-amd64-0...
118
-
# Creating user-linux-amd64-1...
119
-
# Creating user-linux-amd64-2...
124
+
$ gomote create -count=3 gotip-linux-amd64
125
+
# Creating user-gotip-linux-amd64-0...
126
+
# Creating user-gotip-linux-amd64-1...
127
+
# Creating user-gotip-linux-amd64-2...
120
128
```
121
129
122
130
The `run` command accepts the `-collect` flag for automatically writing the output from the command to a file in the current working directory, 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.
123
131
124
132
Example:
125
133
```
126
-
$ gomote run -collect user-linux-amd64-0 /bin/bash -c 'echo hi'
127
-
# Writing output to user-linux-amd64-0.stdout...
128
-
$ cat user-linux-amd64-0.stdout
134
+
$ gomote run -collect user-gotip-linux-amd64-0 /bin/bash -c 'echo hi'
135
+
# Writing output to user-gotip-linux-amd64-0.stdout...
136
+
$ cat user-gotip-linux-amd64-0.stdout
129
137
hi
130
-
$ ls user-linux-amd64-0.tar.gz
131
-
user-linux-amd64-0.tar.gz
138
+
$ ls user-gotip-linux-amd64-0.tar.gz
139
+
user-gotip-linux-amd64-0.tar.gz
132
140
```
133
141
134
142
The `run` command accepts the `-until` flag for continuously executing a command until the output of the command matches some pattern. This is useful for reproducing rare issues, and especially useful when used together with `-collect`.
135
143
136
144
Example:
137
145
```
138
-
$ gomote run -collect -until 'FAIL' user-linux-amd64-0 go/bin/go test -run 'TestFlaky' -count=1000 runtime
139
-
# Writing output to user-linux-amd64-0.stdout...
140
-
$ cat user-linux-amd64-0.stdout
146
+
$ gomote run -until 'FAIL' -collect user-gotip-linux-amd64-0 go/bin/go test -run 'TestFlaky' -count=1000 runtime
147
+
# Writing output to user-gotip-linux-amd64-0.stdout...
148
+
$ cat user-gotip-linux-amd64-0.stdout
141
149
...
142
150
--- FAIL: TestFlaky ---
143
151
...
144
-
$ ls user-linux-amd64-0.tar.gz
145
-
user-linux-amd64-0.tar.gz
152
+
$ ls user-gotip-linux-amd64-0.tar.gz
153
+
user-gotip-linux-amd64-0.tar.gz
146
154
```
147
155
148
156
Note that 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.
@@ -153,29 +161,14 @@ Putting together some of the tricks above and making use of groups, it's much ea
$ gomote run -until='unexpected return pc' -collect go/bin/go run -run="TestFlaky" -count=100 runtime
158
166
```
159
167
160
168
### Darwin
161
169
162
-
Darwin gomotes hosted on LUCI do not have Xcode pre-installed.
163
-
Without Xcode, they cannot do cgo builds.
164
-
You can build with cgo disabled:
165
-
166
-
```
167
-
$ gomote run -e 'CGO_ENABLED=0' $MOTE go/src/make.bash
168
-
```
169
-
170
-
Or install Xcode like so:
171
-
172
-
```
173
-
$ gomote run $MOTE /bin/mkdir /tmp/xcode
174
-
$ gomote run $MOTE /Users/swarming/.swarming/w/ir/tools/bin/mac_toolchain install -xcode-version 15a240d -output-dir /tmp/xcode/Xcode.app
175
-
$ gomote run $MOTE /usr/bin/sudo xcode-select --switch /tmp/xcode/Xcode.app
176
-
```
177
-
178
-
Note: Depending on which machine you get, the `mac_toolchain` binary referenced may alternatively be at either `/Volumes/Work/s/w/ir/tools/bin/mac_toolchain`.
170
+
Darwin gomotes are known to take a few minutes to set up, even if there are machines available.
171
+
This is due to the extra time necessary to set up Xcode.
0 commit comments