Skip to content

Commit 2265a5b

Browse files
fredbiclaude
andcommitted
doc(cliopts): say what -loader does when nothing is passed
The help defined "auto" as picking "own" where there is no exec, and left the reader to chain that with the default to work out what a plain run gets. It reads as though "own" were the default, which it is on no native build. It now leads with the answer, and stays true of the WebAssembly build that prints the same string: "auto" runs go list wherever a subprocess can be started, which is every native build, and uses "own" only where one cannot. The same two-hop wording sat in three documented flag tables. The WASI one now says the thing that is peculiar to it -- there, "auto" and "own" are the same choice, and "go" is refused up front rather than failing inside the go command. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 4004501 commit 2265a5b

4 files changed

Lines changed: 14 additions & 6 deletions

File tree

‎cmd/genspec-wasi/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ go run ./cmd/genspec-wasi -workdir ./testdata ./goparsing/petstore/...
4444
| *(one flag per boolean option)* | | every boolean knob on `codescan.Options` has a flag, named after the field in kebab-case — `-prune-unused-models`, `-ref-aliases`, `-clean-go-doc` … Run `genspec-wasi -h` for the list. The one exception is `ToolchainFreeLoader`, which `-loader` states more fully. |
4545
| `-build-tags` | | comma-separated build tags to apply while loading |
4646
| `-goos` / `-goarch` | this machine's | the platform the **scanned code** is built for |
47-
| `-loader` | `auto` | `go` runs `go list`; `own` needs no toolchain; `auto` picks `own` wherever the build cannot exec |
47+
| `-loader` | `auto` | here `auto` and `own` are the same thing: a WebAssembly guest can start no subprocess, so `go list` can never run. `go` is refused up front for that reason, rather than failing deep inside the go command |
4848
| `-export-data` | | directory or `.zip` of precomputed dependency types (see below) |
4949
| `-stub-stdlib` | `false` | synthesize standard-library types instead of reading GOROOT |
5050
| `-compiled-dependencies` | `false` | take dependency types from the compiler's export data rather than reading every dependency from source. The spec is the same either way; this is much faster on a warm build cache and much slower on a cold one, since export data has to be compiled before it exists. **Native builds only** — it needs `-loader=go`, which WebAssembly cannot run |

‎cmd/internal/cliopts/loader.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,14 @@ const (
1818
loaderOwn = "own" // codescan's own loader: no toolchain, no subprocess
1919
loaderAuto = "auto" // own where there is no exec, go otherwise
2020

21-
loaderHelp = `package loader: "go" runs go list, "own" needs no toolchain, "auto" picks own where there is no exec`
21+
// Spelled out rather than left as "auto picks own where there is no exec", which takes two hops to
22+
// answer the question a reader actually has -- what do I get if I pass nothing? The string is
23+
// printed by the WebAssembly build as well, so it has to be true of both without naming either as
24+
// the normal case.
25+
loaderHelp = `package loader: "auto" (the default) runs go list wherever a subprocess can be` + "\n" +
26+
`started, which is every native build, and uses "own" only where one cannot -- a` + "\n" +
27+
`WebAssembly build. "go" always runs go list; "own" always uses codescan's own loader,` + "\n" +
28+
`which needs neither a toolchain nor a subprocess`
2229
)
2330

2431
// resolveLoader reports whether to use codescan's own loader.

‎docs/doc-site/getting-started/usage-as-a-tui.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ A second group settles what gets built, and how it is loaded — the environment
7878
| `-goflags` | — | default go command flags, as `GOFLAGS` — `-build-tags` wins over a `-tags` given here |
7979
| `-gowork` | search upwards | workspace selection, as `GOWORK`: `off` to ignore a `go.work`, or the path to one |
8080
| `-goexperiment` | — | toolchain experiments, as `GOEXPERIMENT` |
81-
| `-loader` | `auto` | `go` runs `go list`; `own` uses codescan's own loader and needs no toolchain; `auto` picks `own` wherever the build cannot exec (experimental) |
81+
| `-loader` | `auto` | `auto` runs `go list`, which is what every native build does, and picks `own` only where no subprocess can be started; `go` always runs `go list`; `own` always uses codescan's own loader, which needs no toolchain (experimental) |
8282
| `-stub-stdlib` | `false` | synthesize the standard library instead of reading GOROOT (needs `-loader=own`) |
8383
| `-compiled-dependencies` | `false` | take dependency types from the compiler's export data instead of reading every dependency from source (needs `-loader=go`). Worth having here more than anywhere: a session rescans on every save, so the build cache is warm after the first one |
8484

‎docs/doc-site/usage/setting-options.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,10 @@ Two shapes do not follow from a field name:
5151
Naming none scans `./...`;
5252
- **`-loader`** takes `go`, `own` or `auto` where the field
5353
(`ToolchainFreeLoader`) is a boolean: the useful default is the third answer,
54-
"pick `own` wherever the build cannot exec". `auto` is what lets the same
55-
source build for a WASI guest, which has no process model and so can never run
56-
`go list`.
54+
"whichever one can run here". On a native build that is `go list`, so a stock
55+
run loads exactly as it always did; `auto` picks `own` only where no subprocess
56+
can be started. That is what lets the same source build for a WASI guest, which
57+
has no process model and so can never run `go list`.
5758

5859
**Commands may add some extra flags that do not affect the scanning itself**.
5960

0 commit comments

Comments
 (0)
⌂ 换网址