Documentation,cmd/dlv: clean up command line usage help (#3395)

Due to some very old mistakes too many of Delve's flags are declared as persistent on cobra's root command. For example the headless flag is a global flag but does not apply to connect, dap or trace; the backend flag does not apply to replay, core and dap; etc. Almost all global flags should have been declared as local flags on individual subcommands. Unfortunately we can not change this without breaking backwards compatibility, for example: dlv --headless debug would not parse if headless was a flag of debug instead of a global flag. Instead we alter usage function and the markdown generation script to strategically hide the flags that don't apply. Fixes #2361
go-delve · Aug 9, 2023 · caf6df0 · caf6df0
1 parent dc5d8de
commit caf6df0
Show file tree

Hide file tree

Showing 14 changed files with 153 additions and 87 deletions.
diff --git a/Documentation/usage/dlv.md b/Documentation/usage/dlv.md
@@ -18,23 +18,7 @@ Pass flags to the program you are debugging using `--`, for example:
 ### Options
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-  -h, --help                             help for dlv
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
+  -h, --help   help for dlv
 ```
 
 ### SEE ALSO
@@ -46,7 +30,6 @@ Pass flags to the program you are debugging using `--`, for example:
 * [dlv debug](dlv_debug.md)	 - Compile and begin debugging main package in current directory, or the package specified.
 * [dlv exec](dlv_exec.md)	 - Execute a precompiled binary, and begin a debug session.
 * [dlv replay](dlv_replay.md)	 - Replays a rr trace.
-* [dlv run](dlv_run.md)	 - Deprecated command. Use 'debug' instead.
 * [dlv test](dlv_test.md)	 - Compile test binary and begin debugging program.
 * [dlv trace](dlv_trace.md)	 - Compile and begin tracing program.
 * [dlv version](dlv_version.md)	 - Prints version.

diff --git a/Documentation/usage/dlv_attach.md b/Documentation/usage/dlv_attach.md
@@ -32,18 +32,14 @@ dlv attach pid [executable] [flags]
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
       --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
       --init string                      Init file, executed by the terminal client.
   -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
       --log                              Enable debugging server logging.
       --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
       --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
       --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

diff --git a/Documentation/usage/dlv_connect.md b/Documentation/usage/dlv_connect.md
@@ -19,22 +19,11 @@ dlv connect addr [flags]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
+      --backend string      Backend selection (see 'dlv help backend'). (default "default")
+      --init string         Init file, executed by the terminal client.
+      --log                 Enable debugging server logging.
+      --log-dest string     Writes logs to the specified file or file descriptor (see 'dlv help log').
+      --log-output string   Comma separated list of components that should produce debug output (see 'dlv help log')
 ```
 
 ### SEE ALSO

diff --git a/Documentation/usage/dlv_core.md b/Documentation/usage/dlv_core.md
@@ -28,19 +28,14 @@ dlv core <executable> <core> [flags]
       --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
       --init string                      Init file, executed by the terminal client.
   -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
       --log                              Enable debugging server logging.
       --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
       --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
       --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

diff --git a/Documentation/usage/dlv_dap.md b/Documentation/usage/dlv_dap.md
@@ -40,22 +40,13 @@ dlv dap [flags]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
+      --check-go-version    Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
+      --disable-aslr        Disables address space randomization
+  -l, --listen string       Debugging server listen address. (default "127.0.0.1:0")
+      --log                 Enable debugging server logging.
+      --log-dest string     Writes logs to the specified file or file descriptor (see 'dlv help log').
+      --log-output string   Comma separated list of components that should produce debug output (see 'dlv help log')
+      --only-same-user      Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
 ```
 
 ### SEE ALSO

diff --git a/Documentation/usage/dlv_exec.md b/Documentation/usage/dlv_exec.md
@@ -31,7 +31,6 @@ dlv exec <path/to/binary> [flags]
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
       --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
       --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.

diff --git a/Documentation/usage/dlv_replay.md b/Documentation/usage/dlv_replay.md
@@ -27,19 +27,14 @@ dlv replay [trace directory] [flags]
       --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
       --init string                      Init file, executed by the terminal client.
   -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
       --log                              Enable debugging server logging.
       --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
       --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
       --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

diff --git a/Documentation/usage/dlv_trace.md b/Documentation/usage/dlv_trace.md
@@ -34,22 +34,15 @@ dlv trace [package] regexp [flags]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
+      --backend string         Backend selection (see 'dlv help backend'). (default "default")
+      --build-flags string     Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
+      --check-go-version       Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
+      --disable-aslr           Disables address space randomization
+      --log                    Enable debugging server logging.
+      --log-dest string        Writes logs to the specified file or file descriptor (see 'dlv help log').
+      --log-output string      Comma separated list of components that should produce debug output (see 'dlv help log')
+  -r, --redirect stringArray   Specifies redirect rules for target process (see 'dlv help redirect')
+      --wd string              Working directory for running the program.
 ```
 
 ### SEE ALSO

diff --git a/Documentation/usage/dlv_version.md b/Documentation/usage/dlv_version.md
@@ -9,8 +9,7 @@ dlv version [flags]
 ### Options
 
 ```
-  -h, --help      help for version
-  -v, --verbose   print verbose version info
+  -h, --help   help for version
 ```
 
 ### Options inherited from parent commands

diff --git a/_scripts/gen-usage-docs.go b/_scripts/gen-usage-docs.go
@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 
 	"github.com/go-delve/delve/cmd/dlv/cmds"
+	"github.com/go-delve/delve/cmd/dlv/cmds/helphelpers"
 	"github.com/spf13/cobra/doc"
 )
 
@@ -21,12 +22,19 @@ func main() {
 		usageDir = os.Args[1]
 	}
 	root := cmds.New(true)
+
+	cmdnames := []string{}
+	for _, subcmd := range root.Commands() {
+		cmdnames = append(cmdnames, subcmd.Name())
+	}
+	helphelpers.Prepare(root)
 	doc.GenMarkdownTree(root, usageDir)
+	root = nil
 	// GenMarkdownTree ignores additional help topic commands, so we have to do this manually
-	for _, cmd := range root.Commands() {
-		if cmd.Run == nil {
-			doc.GenMarkdownTree(cmd, usageDir)
-		}
+	for _, cmdname := range cmdnames {
+		cmd, _, _ := cmds.New(true).Find([]string{cmdname})
+		helphelpers.Prepare(cmd)
+		doc.GenMarkdownTree(cmd, usageDir)
 	}
 	fh, err := os.OpenFile(filepath.Join(usageDir, "dlv.md"), os.O_APPEND|os.O_WRONLY, 0)
 	if err != nil {

diff --git a/cmd/dlv/cmds/commands.go b/cmd/dlv/cmds/commands.go
@@ -16,6 +16,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/go-delve/delve/cmd/dlv/cmds/helphelpers"
 	"github.com/go-delve/delve/pkg/config"
 	"github.com/go-delve/delve/pkg/gobuild"
 	"github.com/go-delve/delve/pkg/goversion"
@@ -276,6 +277,7 @@ or later, -gcflags="-N -l" on earlier versions of Go.`,
 			fmt.Println("This command is deprecated, please use 'debug' instead.")
 			os.Exit(0)
 		},
+		Hidden: true,
 	}
 	rootCommand.AddCommand(runCommand)
 
@@ -452,6 +454,8 @@ File redirects can also be changed using the 'restart' command.
 
 	rootCommand.DisableAutoGenTag = true
 
+	configUsageFunc(rootCommand)
+
 	return rootCommand
 }
 
@@ -1099,3 +1103,19 @@ func parseRedirects(redirects []string) ([3]string, error) {
 	}
 	return r, nil
 }
+
+func configUsageFunc(cmd *cobra.Command) {
+	for _, subcmd := range cmd.Commands() {
+		configUsageFunc(subcmd)
+	}
+
+	if cmd.Run == nil && cmd.Name() != "dlv" {
+		return
+	}
+
+	usage := cmd.UsageFunc()
+	cmd.SetUsageFunc(func(cmd *cobra.Command) error {
+		helphelpers.Prepare(cmd)
+		return usage(cmd)
+	})
+}