PenaDevops/delve
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Alessandro Arzilli 2023-08-09 19:37:55 +02:00 committed by GitHub
parent dc5d8de320
commit caf6df0eb9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 153 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Documentation/usage/dlv.md
View File

@ -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.

4
Documentation/usage/dlv_attach.md
View File

@ -32,9 +32,7 @@ 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")
@ -42,8 +40,6 @@ dlv attach pid [executable] [flags]
--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

21
Documentation/usage/dlv_connect.md
View File

@ -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

5
Documentation/usage/dlv_core.md
View File

@ -28,10 +28,7 @@ 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")
@ -39,8 +36,6 @@ dlv core <executable> <core> [flags]
--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

23
Documentation/usage/dlv_dap.md
View File

@ -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

1
Documentation/usage/dlv_exec.md
View File

@ -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.

5
Documentation/usage/dlv_replay.md
View File

@ -27,10 +27,7 @@ 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")
@ -38,8 +35,6 @@ dlv replay [trace directory] [flags]
--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

25
Documentation/usage/dlv_trace.md
View File

@ -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

3
Documentation/usage/dlv_version.md
View File

@ -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

16
_scripts/gen-usage-docs.go
View File

@ -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 {

20
cmd/dlv/cmds/commands.go
View File

@ -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)
})
}

96
cmd/dlv/cmds/helphelpers/help.go Normal file
View File

@ -0,0 +1,96 @@
package helphelpers
import (
"github.com/spf13/cobra"
"github.com/spf13/pflag"
)
// Prepare prepares cmd flag set for the invocation of its usage function by
// hiding flags that we want cobra to parse but we don't want to show to the
// user.
// We do this because not all flags associated with the root command are
// valid for all subcommands but we don't want to move them out of the root
// command and into subcommands, since that would change how cobra parses
// the command line.
//
// For example:
//
// dlv --headless debug
//
// must parse successfully even though the headless flag is not applicable
// to the 'connect' subcommand.
//
// Prepare is a destructive command, cmd can not be reused after it has been
// called.
func Prepare(cmd *cobra.Command) {
switch cmd.Name() {
case "dlv", "help", "run", "version":
hideAllFlags(cmd)
case "attach":
hideFlag(cmd, "build-flags")
hideFlag(cmd, "disable-aslr")
hideFlag(cmd, "redirect")
hideFlag(cmd, "wd")
case "connect":
hideFlag(cmd, "accept-multiclient")
hideFlag(cmd, "allow-non-terminal-interactive")
hideFlag(cmd, "api-version")
hideFlag(cmd, "build-flags")
hideFlag(cmd, "check-go-version")
hideFlag(cmd, "disable-aslr")
hideFlag(cmd, "headless")
hideFlag(cmd, "listen")
hideFlag(cmd, "only-same-user")
hideFlag(cmd, "redirect")
hideFlag(cmd, "wd")
case "dap":
hideFlag(cmd, "headless")
hideFlag(cmd, "accept-multiclient")
hideFlag(cmd, "init")
hideFlag(cmd, "backend")
hideFlag(cmd, "build-flags")
hideFlag(cmd, "wd")
hideFlag(cmd, "redirect")
hideFlag(cmd, "api-version")
hideFlag(cmd, "allow-non-terminal-interactive")
case "debug", "test":
// All flags apply
case "exec":
hideFlag(cmd, "build-flags")
case "replay", "core":
hideFlag(cmd, "backend")
hideFlag(cmd, "build-flags")
hideFlag(cmd, "disable-aslr")
hideFlag(cmd, "redirect")
hideFlag(cmd, "wd")
case "trace":
hideFlag(cmd, "accept-multiclient")
hideFlag(cmd, "allow-non-terminal-interactive")
hideFlag(cmd, "api-version")
hideFlag(cmd, "headless")
hideFlag(cmd, "init")
hideFlag(cmd, "listen")
hideFlag(cmd, "only-same-user")
}
}
func hideAllFlags(cmd *cobra.Command) {
cmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
flag.Hidden = true
})
cmd.Flags().VisitAll(func(flag *pflag.Flag) {
flag.Hidden = true
})
}
func hideFlag(cmd *cobra.Command, name string) {
if cmd == nil {
return
}
flag := cmd.Flags().Lookup(name)
if flag != nil {
flag.Hidden = true
return
}
hideFlag(cmd.Parent(), name)
}

1
go.mod
View File

@ -15,6 +15,7 @@ require (
github.com/mattn/go-runewidth v0.0.13 // indirect
github.com/sirupsen/logrus v1.6.0
github.com/spf13/cobra v1.1.3
github.com/spf13/pflag v1.0.5 // indirect
github.com/stretchr/testify v1.7.0 // indirect
go.starlark.net v0.0.0-20220816155156-cfacd8902214
golang.org/x/arch v0.0.0-20190927153633-4e8777c89be4

1
vendor/modules.txt vendored
View File

@ -55,6 +55,7 @@ github.com/sirupsen/logrus
github.com/spf13/cobra
github.com/spf13/cobra/doc
# github.com/spf13/pflag v1.0.5
## explicit
github.com/spf13/pflag
# github.com/stretchr/testify v1.7.0
## explicit