chore: Use go 1.24's 'go tool' support for CLI tooling

maru-ava · maru-ava · commit f7901f54517e · 2025-10-02T21:42:59.000Z
This change mirrors a change already made to avalanchego and avoids
the problem of a cached version of golangci-lint being incompatible
with a new version of golang when upgrading the golang version between
minor versions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -40,13 +40,13 @@ Mocks are auto-generated using [mockgen](https://pkg.go.dev/go.uber.org/mock/moc
 * To **re-generate all mocks**, use the command below from the root of the project:
 
     ```sh
-    go generate -run "go.uber.org/mock/mockgen" ./...
+    go generate -run mockgen ./...
     ```
 
 * To **add** an interface that needs a corresponding mock generated:
   * if the file `mocks_generate_test.go` exists in the package where the interface is located, either:
-    * modify its `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface (preferred); or
-    * add another `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface according to specific mock generation settings
+    * modify its `//go:generate go tool -modfile=tools/go.mod mockgen` to generate a mock for your interface (preferred); or
+    * add another `//go:generate go tool -modfile=tools/go.mod mockgen` to generate a mock for your interface according to specific mock generation settings
   * if the file `mocks_generate_test.go` does not exist in the package where the interface is located, create it with content (adapt as needed):
 
     ```go
@@ -55,7 +55,7 @@ Mocks are auto-generated using [mockgen](https://pkg.go.dev/go.uber.org/mock/moc
 
     package mypackage
 
-    //go:generate go run go.uber.org/mock/mockgen -package=${GOPACKAGE} -destination=mocks_test.go . YourInterface
+    //go:generate go tool -modfile=tools/go.mod mockgen -package=${GOPACKAGE} -destination=mocks_test.go . YourInterface
     ```
 
     Notes:
@@ -66,3 +66,26 @@ Mocks are auto-generated using [mockgen](https://pkg.go.dev/go.uber.org/mock/moc
   1. If the `//go:generate` mockgen command line:
       * generates a mock file for multiple interfaces, remove your interface from the line
       * generates a mock file only for the interface, remove the entire line. If the file is empty, remove `mocks_generate_test.go` as well.
+
+## Tool Dependencies
+
+This project uses `go tool` to manage development tool dependencies in `tools/go.mod`. This isolates tool dependencies from the main application dependencies and provides consistent, version-locked tools across the team.
+
+### Managing Tools
+
+* To **add a new tool**:
+  ```sh
+  go get -tool -modfile=tools/go.mod example.com/tool/cmd/toolname@version
+  ```
+
+* To **upgrade a tool**:
+  ```sh
+  go get -tool -modfile=tools/go.mod example.com/tool/cmd/toolname@newversion
+  ```
+
+* To **run a tool manually**:
+  ```sh
+  go tool -modfile=tools/go.mod toolname [args...]
+  ```
+
+Note: `ginkgo` remains in the main `go.mod` as it is used directly in e2e test code.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -33,6 +33,10 @@ jobs:
       - uses: actions/setup-go@v5
         with:
           go-version-file: "go.mod"
+          cache-dependency-path: |
+            go.sum
+            tools/go.sum
+            tools/legacy-golangci-lint.sum
       - name: change avalanchego dep
         if: ${{ github.event_name == 'workflow_dispatch' }}
         run: |
@@ -67,6 +71,9 @@ jobs:
       - uses: actions/setup-go@v5
         with:
           go-version-file: "go.mod"
+          cache-dependency-path: |
+            go.sum
+            tools/go.sum
       - name: change avalanchego dep
         if: ${{ github.event_name == 'workflow_dispatch' }}
         run: |
@@ -96,9 +103,6 @@ jobs:
           ref: ${{ github.event.inputs.avalanchegoBranch }}
           path: avalanchego
           token: ${{ secrets.AVALANCHE_PAT }}
-      - uses: actions/setup-go@v5
-        with:
-          go-version-file: "go.mod"
       - name: Run e2e tests
         uses: ava-labs/avalanchego/.github/actions/run-monitored-tmpnet-cmd@23ace817fe84e8f9b20bf1155075f8d4541d4295
         with:
@@ -120,10 +124,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: "go.mod"
       - name: check out ${{ github.event.inputs.avalanchegoRepo }} ${{ github.event.inputs.avalanchegoBranch }}
         if: ${{ github.event_name == 'workflow_dispatch' }}
         uses: actions/checkout@v4
diff --git a/Taskfile.yml b/Taskfile.yml
@@ -59,10 +59,14 @@ tasks:
       - task: check-clean-branch
 
   check-go-mod-tidy:
-    desc: Checks that go.mod and go.sum are up-to-date (requires a clean git working tree)
+    desc: Checks that all go.mod and go.sum files are up-to-date (requires a clean git working tree)
     cmds:
       - cmd: go mod tidy
       - task: check-clean-branch
+      - cmd: cd tools && go mod tidy
+      - task: check-clean-branch
+      - cmd: cd tools && go mod tidy -modfile=legacy-golangci-lint.mod
+      - task: check-clean-branch
 
   coverage:
     desc: Display test coverage statistics from coverage.out file
@@ -72,19 +76,19 @@ tasks:
     desc: Generates fjl/gencodec files
     cmds:
       - cmd: grep -lr -E '^// Code generated by github\.com\/fjl\/gencodec\. DO NOT EDIT\.$' . | xargs -r rm
-      - cmd: go generate -run "github.com/fjl/gencodec" ./...
+      - cmd: go generate -run gencodec ./...
 
   generate-mocks:
     desc: Generates testing mocks
     cmds:
       - cmd: grep -lr -E '^// Code generated by MockGen\. DO NOT EDIT\.$' . | xargs -r rm
-      - cmd: go generate -run "go.uber.org/mock/mockgen" ./...
+      - cmd: go generate -run mockgen ./...
 
   generate-rlp:
     desc: Generates rlp files
     cmds:
       - cmd: grep -lr -E '^// Code generated by rlpgen\. DO NOT EDIT.\.$' . | xargs -r rm
-      - cmd: go generate -run "github.com/ava-labs/libevm/rlp/rlpgen" ./...
+      - cmd: go generate -run rlpgen ./...
 
   lint:
     desc: Run golangci-lint and check for allowed Ethereum imports in Go code
diff --git a/bin/ginkgo b/bin/ginkgo
diff --git a/bin/ginkgo b/bin/ginkgo
@@ -0,0 +1 @@
+../scripts/run_ginkgo.sh
diff --git a/core/genesis.go b/core/genesis.go
@@ -55,7 +55,7 @@ import (
 	"github.com/holiman/uint256"
 )
 
-//go:generate go run github.com/fjl/gencodec -type Genesis -field-override genesisSpecMarshaling -out gen_genesis.go
+//go:generate go tool -modfile=../tools/go.mod gencodec -type Genesis -field-override genesisSpecMarshaling -out gen_genesis.go
 
 var errGenesisNoConfig = errors.New("genesis has no chain configuration")
 
diff --git a/eth/ethconfig/config.go b/eth/ethconfig/config.go
@@ -75,7 +75,7 @@ func NewDefaultConfig() Config {
 	}
 }
 
-//go:generate go run github.com/fjl/gencodec -type Config -formats toml -out gen_config.go
+//go:generate go tool -modfile=../../tools/go.mod gencodec -type Config -formats toml -out gen_config.go
 
 // Config contains configuration options for ETH and LES protocols.
 type Config struct {
diff --git a/go.mod b/go.mod
@@ -1,5 +1,16 @@
 module github.com/ava-labs/coreth
 
+// CLI tools intended for invocation with `go tool` should be added to
+// tools/go.mod to avoid polluting the main module's dependencies. See
+// CONTRIBUTING.md for more details.
+
+// - Changes to the minimum golang version must also be replicated in:
+//   - go.mod (here)
+//   - tools/go.mod
+//   - tools/legacy-golangci-lint.mod
+//
+// - If updating between minor versions (e.g. 1.24.x -> 1.25.x):
+//   - Consider updating the version of golangci-lint (see tools/go.mod)
 go 1.24.7
 
 require (
@@ -175,3 +186,10 @@ require (
 	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
 	sigs.k8s.io/yaml v1.3.0 // indirect
 )
+
+// The following tools are managed here instead of in tools/go.mod
+// because they are already direct dependencies of the main module.
+tool (
+	github.com/ava-labs/libevm/rlp/rlpgen
+	github.com/onsi/ginkgo/v2
+)
diff --git a/internal/ethapi/mocks_generate_test.go b/internal/ethapi/mocks_generate_test.go
@@ -1,3 +1,3 @@
 package ethapi
 
-//go:generate go run go.uber.org/mock/mockgen -package=$GOPACKAGE -destination=mocks_test.go . Backend
+//go:generate go tool -modfile=../../tools/go.mod mockgen -package=$GOPACKAGE -destination=mocks_test.go . Backend
diff --git a/plugin/evm/customtypes/header_ext.go b/plugin/evm/customtypes/header_ext.go
@@ -178,8 +178,8 @@ func (h *HeaderSerializable) updateToExtras(extras *HeaderExtra) {
 // NOTE: both generators currently do not support type aliases.
 // We are using custom versions of these programs for now to support type aliases,
 // see https://github.com/ava-labs/coreth/pull/746#discussion_r1969673252
-//go:generate go run github.com/fjl/gencodec -type HeaderSerializable -field-override headerMarshaling -out gen_header_serializable_json.go
-//go:generate go run github.com/ava-labs/libevm/rlp/rlpgen -type HeaderSerializable -out gen_header_serializable_rlp.go
+//go:generate go tool -modfile=../../../tools/go.mod gencodec -type HeaderSerializable -field-override headerMarshaling -out gen_header_serializable_json.go
+//go:generate go tool rlpgen -type HeaderSerializable -out gen_header_serializable_rlp.go
 
 // HeaderSerializable defines the header of a block in the Ethereum blockchain,
 // as it is to be serialized into RLP and JSON. Note it must be exported so that
diff --git a/precompile/contract/mocks_generate_test.go b/precompile/contract/mocks_generate_test.go
@@ -3,4 +3,4 @@
 
 package contract
 
-//go:generate go run go.uber.org/mock/mockgen -package=$GOPACKAGE -source=interfaces.go -destination=mocks.go -exclude_interfaces StatefulPrecompiledContract,StateReader,ConfigurationBlockContext,Configurator
+//go:generate go tool -modfile=../../tools/go.mod mockgen -package=$GOPACKAGE -source=interfaces.go -destination=mocks.go -exclude_interfaces StatefulPrecompiledContract,StateReader,ConfigurationBlockContext,Configurator
diff --git a/precompile/precompileconfig/mocks_generate_test.go b/precompile/precompileconfig/mocks_generate_test.go
@@ -3,4 +3,4 @@
 
 package precompileconfig
 
-//go:generate go run go.uber.org/mock/mockgen -package=$GOPACKAGE -destination=mocks.go . Predicater,Config,ChainConfig,Accepter
+//go:generate go tool -modfile=../../tools/go.mod mockgen -package=$GOPACKAGE -destination=mocks.go . Predicater,Config,ChainConfig,Accepter
diff --git a/scripts/actionlint.sh b/scripts/actionlint.sh
@@ -2,7 +2,7 @@
 
 set -euo pipefail
 
-go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.1 "${@}"
+go tool -modfile=tools/go.mod actionlint "${@}"
 
 echo "Checking use of scripts/* in GitHub Actions workflows..."
 SCRIPT_USAGE=
diff --git a/scripts/lint.sh b/scripts/lint.sh
@@ -93,15 +93,19 @@ function read_dirs {
 TESTS=${TESTS:-"golangci_lint avalanche_golangci_lint license_header require_error_is_no_funcs_as_params single_import interface_compliance_nil require_no_error_inline_func import_testing_only_in_tests"}
 
 function test_golangci_lint {
-  go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.63 run --config .golangci.yml
+  # Since there are 2 versions of golangci-lint in play, and only one
+  # can be managed by a given go.mod file, we use a separate mod file
+  # for the older version.
+  # TODO(marun) Switch everything to v2 when possible
+  go tool -modfile=tools/legacy-golangci-lint.mod golangci-lint run --config .golangci.yml
 }
 
 function test_avalanche_golangci_lint {
   if [[ ! -f $AVALANCHE_LINT_FILE ]]; then
     return 0
   fi
 
-  go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run \
+  go tool -modfile=tools/go.mod golangci-lint run \
   --config "$AVALANCHE_LINT_FILE" \
   || return 1
 }
@@ -115,7 +119,7 @@ function test_license_header {
   if [[ ${#UPSTREAM_FILES[@]} -gt 0 ]]; then
     echo "Running license tool on upstream files with header for upstream..."
     # shellcheck disable=SC2086
-    go run github.com/palantir/go-license@v1.25.0 \
+    go tool -modfile=tools/go.mod go-license \
       --config=./license_header_for_upstream.yml \
       ${_addlicense_flags} \
       "${UPSTREAM_FILES[@]}" \
@@ -125,7 +129,7 @@ function test_license_header {
   if [[ ${#DEFAULT_FILES[@]} -gt 0 ]]; then
     echo "Running license tool on remaining files with default header..."
     # shellcheck disable=SC2086
-    go run github.com/palantir/go-license@v1.25.0 \
+    go tool -modfile=tools/go.mod go-license \
       --config=./license_header.yml \
       ${_addlicense_flags} \
       "${DEFAULT_FILES[@]}" \
diff --git a/scripts/run_ginkgo.sh b/scripts/run_ginkgo.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+REPO_ROOT=$(
+  cd "$(dirname "${BASH_SOURCE[0]}")"
+  cd .. && pwd
+)
+cd "${REPO_ROOT}"
+
+go tool ginkgo "${@}"
diff --git a/scripts/run_task.sh b/scripts/run_task.sh
@@ -6,5 +6,5 @@ set -euo pipefail
 if command -v task > /dev/null 2>&1; then
   exec task "${@}"
 else
-  go run github.com/go-task/task/v3/cmd/task@v3.39.2 "${@}"
+  go tool -modfile=tools/go.mod task "${@}"
 fi 
diff --git a/tests/warp/aggregator/mocks_generate_test.go b/tests/warp/aggregator/mocks_generate_test.go
@@ -3,4 +3,4 @@
 
 package aggregator
 
-//go:generate go run go.uber.org/mock/mockgen -package=$GOPACKAGE -destination=mock_signature_getter.go . SignatureGetter
+//go:generate go tool -modfile=../../../tools/go.mod mockgen -package=$GOPACKAGE -destination=mock_signature_getter.go . SignatureGetter
diff --git a/tools/go.mod b/tools/go.mod
diff --git a/tools/go.sum b/tools/go.sum
diff --git a/tools/legacy-golangci-lint.mod b/tools/legacy-golangci-lint.mod
diff --git a/tools/legacy-golangci-lint.sum b/tools/legacy-golangci-lint.sum

Original file line number	Diff line number	Diff line change
`@@ -55,7 +55,7 @@ import (`
`55`	`55`	`"github.com/holiman/uint256"`
`56`	`56`	`)`
`57`	`57`
`58`		`-//go:generate go run github.com/fjl/gencodec -type Genesis -field-override genesisSpecMarshaling -out gen_genesis.go`
	`58`	`+//go:generate go tool -modfile=../tools/go.mod gencodec -type Genesis -field-override genesisSpecMarshaling -out gen_genesis.go`
`59`	`59`
`60`	`60`	`var errGenesisNoConfig = errors.New("genesis has no chain configuration")`
`61`	`61`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ func NewDefaultConfig() Config {`
`75`	`75`	`}`
`76`	`76`	`}`
`77`	`77`
`78`		`-//go:generate go run github.com/fjl/gencodec -type Config -formats toml -out gen_config.go`
	`78`	`+//go:generate go tool -modfile=../../tools/go.mod gencodec -type Config -formats toml -out gen_config.go`
`79`	`79`
`80`	`80`	`// Config contains configuration options for ETH and LES protocols.`
`81`	`81`	`type Config struct {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`package ethapi`
`2`	`2`
`3`		`-//go:generate go run go.uber.org/mock/mockgen -package=$GOPACKAGE -destination=mocks_test.go . Backend`
	`3`	`+//go:generate go tool -modfile=../../tools/go.mod mockgen -package=$GOPACKAGE -destination=mocks_test.go . Backend`