Documentation,cmd/dlv: clean up command line usage help

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 go-delve#2361
aarzilli · May 28, 2023 · d793796 · d793796
1 parent 4798924
commit d793796
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
@@ -29,18 +29,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"
@@ -268,6 +269,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)
 
@@ -441,6 +443,8 @@ File redirects can also be changed using the 'restart' command.
 
 	rootCommand.DisableAutoGenTag = true
 
+	configUsageFunc(rootCommand)
+
 	return rootCommand
 }
 
@@ -1077,3 +1081,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)
+	})
+}