Skip to content

Commit 1dc481e

Browse files
creachadaircreachadair
committed
cmd/go-cache-plugin: reorganize and expand the help text
1 parent 1432264 commit 1dc481e

File tree

2 files changed

+107
-30
lines changed

2 files changed

+107
-30
lines changed

‎cmd/go-cache-plugin/go-cache-plugin.go

Lines changed: 1 addition & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -62,36 +62,7 @@ listening on a socket.`,
6262

6363
Run: command.Adapt(runConnect),
6464
},
65-
command.HelpCommand([]command.HelpTopic{{
66-
Name: "environment",
67-
Help: `Environment variables understood by this program.
68-
69-
To make it easier to configure this tool for multiple workflows, most of the
70-
settings can be set via environment variables as well as flags.
71-
72-
--------------------------------------------------------------------
73-
Flag (global) Variable Format Default
74-
--------------------------------------------------------------------
75-
--cache-dir GOCACHE_DIR path (required)
76-
--bucket GOCACHE_S3_BUCKET string (required)
77-
--region GOCACHE_S3_REGION string based on bucket
78-
--prefix GOCACHE_KEY_PREFIX string ""
79-
--min-upload-size GOCACHE_MIN_SIZE int64 0
80-
--metrics GOCACHE_METRICS bool false
81-
--expiry GOCACHE_EXPIRY duration 0
82-
-c GOCACHE_CONCURRENCY int runtime.NumCPU
83-
-u GOCACHE_S3_CONCURRENCY duration runtime.NumCPU
84-
-v GOCACHE_VERBOSE bool false
85-
--debug GOCACHE_DEBUG bool false
86-
87-
--------------------------------------------------------------------
88-
Flag (serve) Variable Format Default
89-
--------------------------------------------------------------------
90-
--socket GOCACHE_SOCKET path (required)
91-
--modproxy GOCACHE_MODPROXY [host]:port ""
92-
--sumdb GOCACHE_SUMDB host,... ""
93-
`,
94-
}}),
65+
command.HelpCommand(helpTopics),
9566
command.VersionCommand(),
9667
},
9768
}

‎cmd/go-cache-plugin/help.go

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
package main
2+
3+
import "github.com/creachadair/command"
4+
5+
var helpTopics = []command.HelpTopic{
6+
{
7+
Name: "configure",
8+
Help: `How to configure the plugin.
9+
10+
To run the plugin, install the program somewhere on your system and set the
11+
GOCACHEPROG environment variable to the command line of the plugin. You can
12+
either specify the full path to the program, or install it in your $PATH.
13+
14+
Parameters can be passed either as flags or via environment variables.
15+
See also "help environment".
16+
17+
The plugin requires credentials to access S3. If you are running in AWS, it can
18+
get credentials from the instnce metadata service; otherwise you will need to
19+
plumb AWS environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or
20+
set up a configuration file.
21+
22+
------------------------------------------------------------------------
23+
## To run the plugin directly as a subprocess of the toolchain
24+
25+
export GOCACHEPROG="go-cache-plugin --cache-dir=/tmp/gocache --bucket ..."
26+
go build ...
27+
28+
Alternatively:
29+
30+
export GOCACHE_DIR=/tmp/gocache
31+
export GOCACHE_S3_BUCKET=cache-bucket-name
32+
export GOCACHEPROG=go-cache-plugin
33+
go build ...
34+
35+
In this mode, you must specify the --cache-dir and --bucket settings.
36+
37+
------------------------------------------------------------------------
38+
## To run the plugin as a standalone service
39+
40+
Use the "serve" subcommand:
41+
42+
go-cache-plugin serve \
43+
--cache-dir=/tmp/gocache --bucket=$B \
44+
--socket /var/run/cache.sock
45+
46+
You can then use the "connect" subcommand to wire up the toolchain:
47+
48+
export GOCACHEPROG="go-cache-plugin connect /var/run/cache.sock"
49+
50+
In this mode, the server must have credentials to access to S3, but the
51+
toolchain process does not need AWS credentials.
52+
53+
------------------------------------------------------------------------
54+
## Running a Go module and sum database proxy
55+
56+
With the --modproxy flag, the server will also export an HTTP proxy for the
57+
public Go module proxy (proxy.golang.org) and sum DB (sum.golang.org) at the
58+
given address:
59+
60+
go-cache-plugin serve ... --modproxy=localhost:5970
61+
62+
To use the module proxy, set the standard GOPROXY environment variable:
63+
64+
export GOPROXY=localhost:5970
65+
export GOCACHEPROG="go-cache-plugin connect /var/run/cache.sock"
66+
go build ...
67+
68+
To use the sum DB proxy, set the GOSUMDB environment variable:
69+
70+
export GOSUMDB="sum.golang.org http://localhost:5970/sumdb/sum.golang.org"
71+
72+
See also: https://proxy.golang.org/
73+
`,
74+
},
75+
{
76+
Name: "environment",
77+
Help: `Environment variables understood by this program.
78+
79+
To make it easier to configure this tool for multiple workflows, most of the
80+
settings can be set via environment variables as well as flags.
81+
82+
--------------------------------------------------------------------
83+
Flag (global) Variable Format Default
84+
--------------------------------------------------------------------
85+
--cache-dir GOCACHE_DIR path (required)
86+
--bucket GOCACHE_S3_BUCKET string (required)
87+
--region GOCACHE_S3_REGION string based on bucket
88+
--prefix GOCACHE_KEY_PREFIX string ""
89+
--min-upload-size GOCACHE_MIN_SIZE int64 0
90+
--metrics GOCACHE_METRICS bool false
91+
--expiry GOCACHE_EXPIRY duration 0
92+
-c GOCACHE_CONCURRENCY int runtime.NumCPU
93+
-u GOCACHE_S3_CONCURRENCY duration runtime.NumCPU
94+
-v GOCACHE_VERBOSE bool false
95+
--debug GOCACHE_DEBUG bool false
96+
97+
--------------------------------------------------------------------
98+
Flag (serve) Variable Format Default
99+
--------------------------------------------------------------------
100+
--socket GOCACHE_SOCKET path (required)
101+
--modproxy GOCACHE_MODPROXY [host]:port ""
102+
--sumdb GOCACHE_SUMDB host,... ""
103+
104+
See also "help configure".`,
105+
},
106+
}

0 commit comments

Comments
 (0)