From ea70d9c8572933ceb117367b125b7fc60ea8359a Mon Sep 17 00:00:00 2001 From: hmdsefi Date: Tue, 3 Nov 2026 00:39:30 +0400 Subject: [PATCH] docs(faq): explain the go get error for nested modules --- docs/faq.md | 36 ++++++++++++++++++++++++++++++++++++ llms.txt | 2 +- 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 108b3c9..dfdc6b6 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -189,6 +189,42 @@ Yes. Package `kernel` is a plain Go API: `kernel.New` creates a simulator, and y `Run`, `RunUntil` or `RunFor`. Without `faultline.Run` you give up the seed list, the subtests, the checks, the second run of failing seeds and the artifacts. +### Why does `go get` say the module "does not contain package"? + +`go get` of a nested module at an explicit version can fail when your `go.mod` already requires +`github.com/hmdsefi/faultline`. You see it only while the module cache does not hold the nested +module yet, as on a new machine or a clean CI runner: + +```sh +go get github.com/hmdsefi/faultline/harness/etcdraft@v0.2.0 +``` + +```text +go: module github.com/hmdsefi/faultline@v0.2.0 found, but does not contain package github.com/hmdsefi/faultline/harness/etcdraft +``` + +`harness/etcdraft`, `shims/grpcsim` and `runner/toolexec`, which holds the `faultline-toolexec` +wrapper, are nested modules with their own version tags, such as `harness/etcdraft/v0.2.0`. When the +error appears, the go command has searched only the root module. It never asked the module proxy +for the nested one. + +Leave the version off, and `go get` adds the nested module's latest release: + +```sh +go get github.com/hmdsefi/faultline/harness/etcdraft +``` + +To add a specific release, download the nested module into the module cache first. For the wrapper, +download `runner/toolexec`, then add the wrapper with `go get -tool`. The following commands add the +harness and the wrapper at v0.2.0: + +```sh +go mod download github.com/hmdsefi/faultline/harness/etcdraft@v0.2.0 +go get github.com/hmdsefi/faultline/harness/etcdraft@v0.2.0 +go mod download github.com/hmdsefi/faultline/runner/toolexec@v0.2.0 +go get -tool github.com/hmdsefi/faultline/runner/toolexec/cmd/faultline-toolexec@v0.2.0 +``` + ### Does faultline make network calls? No. `shims/netsim` implements `net.Conn` and `net.Listener` on the simulated network and never diff --git a/llms.txt b/llms.txt index 8f84527..fe75ad9 100644 --- a/llms.txt +++ b/llms.txt @@ -35,7 +35,7 @@ - [How faultline works](https://raw.githubusercontent.com/hmdsefi/faultline/main/docs/how-it-works.md): when you write code that runs inside the simulation, or need to know why a run behaves as it does. Virtual time, the seeded scheduler, named random streams, nodes, the simulated network and disk, goroutine mode, faults and fault schedules, checks, seeds and replay, and the determinism rules for code under test in each mode. - [Architecture](https://raw.githubusercontent.com/hmdsefi/faultline/main/docs/architecture.md): when you need to know what the node API is or which package does what. The node API and goroutine mode, the packages and modules, how one seed runs through them, and the design choices behind them, including the toolexec backend. -- [Limitations and FAQ](https://raw.githubusercontent.com/hmdsefi/faultline/main/docs/faq.md): before you decide whether faultline fits a system, or when a feature seems to be missing. What faultline does not do, the known issues, and how faultline relates to FoundationDB's simulation testing, TigerBeetle's VOPR, Antithesis, Jepsen and `testing/synctest`. +- [Limitations and FAQ](https://raw.githubusercontent.com/hmdsefi/faultline/main/docs/faq.md): before you decide whether faultline fits a system, when a feature seems to be missing, or when `go get` of a nested module fails with "does not contain package". What faultline does not do, the known issues, how to add a nested module at a specific version, and how faultline relates to FoundationDB's simulation testing, TigerBeetle's VOPR, Antithesis, Jepsen and `testing/synctest`. ## Optional