Go Wiki：Gomote

gomote 指令是 Go 建構器基礎架構的客戶端。它是遠端 Go 建構器機器設備的遙控器。

安裝

$ go install golang.org/x/build/cmd/gomote@latest  # Go 1.16 and later

用法

gomote 工具最基本的用法只涉及幾個步驟

建立一個執行個體。
將程式碼推送到執行個體。
在執行個體上執行指令。

執行 create 指令會列出可用的執行個體類型。

$ gomote create
(list tons of buildlet types)

然後，可以透過指定執行個體類型來建立執行個體。執行個體的名稱會印到 stdout，因此結果可以儲存在環境變數中。（可能還有其他記錄訊息，但它們會在 stderr 上，且每行都會有一個「#」前置詞。）

$ gomote create linux-amd64
# still creating linux-amd64 (1) after 5s; 0 requests ahead of you
user-linux-amd64-0

有了執行個體的名稱，您現在可以將本機 Go 儲存庫推送到執行個體（更具體地說，同步其內容），並安裝引導工具鏈。您同步的儲存庫會出現在 $WORKDIR（所有 gomote 作業的預設目錄）的 go 子目錄中。引導工具鏈會永遠進入 go1.4 子目錄（即使引導工具鏈不是來自版本 1.4）。

$ GOROOT=/path/to/local/go/repo gomote push user-linux-amd64-0
$ gomote ls user-linux-amd64-0
go
go1.4

請注意，push 實際上是一個「同步」作業，因此下次您推送時，gomote 工具只會推送已變更的內容（新增、修改或移除的檔案）。

安裝了工具鏈後，您現在可以在執行個體上執行指令來建置它。run 指令讓您可以指定要執行的可執行檔。可執行檔必須相對於 $WORKDIR（例如 go/bin/go）或透過絕對路徑（例如 /bin/bash）指定。然後，該可執行檔會在目前的作業目錄設定為包含可執行檔的目錄時執行。

$ gomote run user-linux-amd64-0 go/src/make.bash

然後，要執行建置的 Go 工具鏈，請使用 go/bin/go。

$ gomote run user-linux-amd64-0 go/bin/go test -run="TestSomething" -v runtime

您還可以為 run 指定作業目錄和環境變數，這些變數會在執行指令前套用。

請注意，gomote 執行個體在閒置 30 分鐘後會自動消失。使用 list 指令來檢查它們還剩多少時間。

$ gomote list
user-linux-amd64-0  linux-amd64 host-linux-amd64-bullseye   expires in 10m27.339494527s

如果沒有其他命令針對執行個體執行，則可以使用 ping 命令來保持執行個體運作。

如需瞭解每個命令的詳細資訊，請執行 gomote help <command>。如需更多命令，請執行 gomote help。

直接偵錯建置個體

create 命令會連絡建置協調器 (farmer.golang.org) 並要求它代表您建立建置個體。所有後續命令 (例如 gomote run 或 gomote ls) 然後會透過協調器代理您的要求。如需直接存取建置個體 (例如，在處理建置個體程式碼時)，您可以略過 gomote create 步驟，並使用特殊建置器名稱 <build-config-name>@ip[:port>，例如 windows-amd64-2008@10.1.5.3。

群組

執行個體可以在命名群組中管理，而且命令會廣播給群組中的所有執行個體。

群組是由 -group 全域旗標或透過 GOMOTE_GROUP 環境變數指定的。-group 旗標必須總是指定有效的群組，而 GOMOTE_GROUP 可能包含無效的群組。執行個體可以屬於多個群組。

群組可以使用「group」子命令明確管理，但在大多數情況下，有幾個捷徑可以讓這變成不必要。

create 命令可以使用 -new-group 旗標為執行個體建立新的群組。
如果 GOMOTE_GROUP 不存在而且沒有明確指定其他群組，則 create 命令會自動在 GOMOTE_GROUP 中建立群組。
destroy 命令可以使用 -destroy-group 旗標，除了執行個體之外，還可以摧毀群組。

因此，使用群組最簡單的方法就是設定 GOMOTE_GROUP 環境變數

$ export GOMOTE_GROUP=debug
$ gomote create linux-amd64
$ GOROOT=/path/to/goroot gomote push
$ gomote run go/src/make.bash

正如此範例所示，即使群組只包含一個執行個體，群組仍然很有用：它可以大幅縮短大多數 gomote 命令。

提示和技巧

一般

create 指令接受 -setup 旗標，該旗標也會推送 GOROOT 並執行該執行個體適當的 make.bash 等效項。

範例

$ GOROOT=/path/to/my/goroot gomote create -setup linux-amd64
# Creating user-linux-amd64-0...
# Pushing /path/to/my/goroot to user-linux-amd64-0
# Running make.bash on user-linux-amd64-0...

create 指令接受 -count 旗標，用於一次建立多個執行個體。

範例

$ gomote create -count=3 linux-amd64
# Creating user-linux-amd64-0...
# Creating user-linux-amd64-1...
# Creating user-linux-amd64-2...

run 指令接受 -collect 旗標，用於將指令的輸出自動寫入目前工作目錄中的檔案，以及執行個體的完整檔案樹副本。此指令對於以設定後就忘記的方式擷取長期執行的指令輸出很有用。

範例

$ gomote run -collect user-linux-amd64-0 /bin/bash -c 'echo hi'
# Writing output to user-linux-amd64-0.stdout...
$ cat user-linux-amd64-0.stdout
hi
$ ls user-linux-amd64-0.tar.gz
user-linux-amd64-0.tar.gz

run 指令接受 -until 旗標，用於持續執行指令，直到指令的輸出符合某種模式。這對於重現罕見問題很有用，特別是在與 -collect 搭配使用時。

範例

$ gomote run -collect -until 'FAIL' user-linux-amd64-0 go/bin/go test -run 'TestFlaky' -count=1000 runtime
# Writing output to user-linux-amd64-0.stdout...
$ cat user-linux-amd64-0.stdout
...
--- FAIL: TestFlaky ---
...
$ ls user-linux-amd64-0.tar.gz
user-linux-amd64-0.tar.gz

請注意，run 指令總是將輸出串流到暫存檔，不論任何其他旗標為何，以避免因終端機捲動而遺失輸出。它總是會列印檔案的位置。

重現罕見失敗

將上述一些技巧組合在一起並使用群組，就可以更輕鬆地對某些測試進行壓力測試，以嘗試重現罕見失敗。例如

$ 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="TestFlaky" -count=100 runtime

Darwin

託管在 LUCI 上的 Darwin gomotes 沒有預先安裝 Xcode。沒有 Xcode，它們就無法執行 cgo 建置。您可以停用 cgo 進行建置

$ gomote run -e 'CGO_ENABLED=0' $MOTE go/src/make.bash

或像這樣安裝 Xcode

$ gomote run $MOTE /bin/mkdir /tmp/xcode
$ gomote run $MOTE /Users/swarming/.swarming/w/ir/tools/bin/mac_toolchain install -xcode-version 15a240d -output-dir /tmp/xcode/Xcode.app
$ gomote run $MOTE /usr/bin/sudo xcode-select --switch /tmp/xcode/Xcode.app

注意：根據您取得的機器，所引用的 mac_toolchain 二進位檔案可能另位在 /Volumes/Work/s/w/ir/tools/bin/mac_toolchain。

Windows

$ gomote run -path '$PATH,$WORKDIR/go/bin' $MOTE go/src/make.bat
$ gomote run -path '$PATH,$WORKDIR/go/bin' $MOTE go/bin/go.exe test cmd/go -short

注意：wiki 的先前版本建議為 gomote「執行」指令設定 GOROOT（例如「-e GOROOT=c:\workdir\go」）；不再建議這樣做（會導致 Go 指令快取問題）。

Windows 上的子儲存庫

$ tar --exclude .git -C ~/go/src/ -zc golang.org/x/tools | gomote puttar -dir=gopath/src $MOTE -
$ gomote run -e 'GOPATH=c:/workdir/gopath' $MOTE go/bin/go test -run=TestFixImportsVendorPackage golang.org/x/tools/imports

如果已透過 ssh 登入機器，這些環境變數可能會派上用場

$ set GOPATH=c:\workdir\gopath
$ set PATH=%PATH%;c:\workdir\gopath\bin;c:\workdir\go\bin
$ set CGO_ENABLED=0

Unix 上的子儲存庫

在 $MOTE 上測試 golang.org/x/sys/unix

$ tar -C $GOPATH/src/ -zc golang.org/x/sys/unix | gomote puttar -dir=gopath/src $MOTE
$ gomote run -e 'GOPATH=/tmp/workdir/gopath' -dir 'gopath/src/golang.org/x/sys/unix' $MOTE go/bin/go test -v golang.org/x/sys/unix

（GOPATH 部分適用於 GOPATH 相容性模式；-dir 適用於模組模式，會在工作目錄中尋找 go.mod）

Android

export MOTE=`gomote create android-arm64-wikofever`
gomote push $MOTE
gomote run $MOTE go/src/make.bash

PATH 必須包含由 make.bash 建置的執行程式包裝程式 go_android_*_exec。

gomote run -path '$PATH,$WORKDIR/go/bin' $MOTE go/bin/go test math/big

關於建置工具

https://farmer.golang.org/builders 列出每個建置工具的部署和組態資訊。這些資訊來自 golang.org/x/build/dashboard 和 golang.org/x/build/env。

存取

2022 年 8 月，部署了一個新的基礎架構，需要移除先前已核准使用者所有的 gomote 存取權。如果您仍需要存取權，請重新提出請求。

若要取得 gomote 服務的存取權，請提交標題為 access: gomote 的問題，並 cc @golang/release。此問題應包含 Google 帳戶的電子郵件地址。提供的帳戶只會用於驗證目的。

驗證會在第一次呼叫指令時觸發

$ gomote create linux-amd64
Please visit https://www.google.com/device in your browser and enter verification code:
 ABCD-4567
...

在使用提供的連結開啟瀏覽器後，使用者必須使用 Google 帳戶驗證身分，並將驗證碼貼到瀏覽器中。稍候，客戶端將會通過驗證。

gomote ssh

gomote ssh 指令使用專門為 gomote 建立的 SSH 金鑰。在第一次使用 gomote ssh 時，會建立一組金鑰並儲存在本機使用者組態目錄中。系統可能會要求您為金鑰設定密碼（不需要密碼）。SSH 功能使用 OpenSSH 憑證驗證運作，不需要任何其他組態。並非所有建置工具類型都支援 gomote ssh。

此內容是 Go Wiki 的一部分。