From 93d82ca8d2f373e1439c2b4f97bb4fa9ba5bebdc Mon Sep 17 00:00:00 2001 From: Derek Parker Date: Fri, 20 May 2016 10:51:23 -0700 Subject: [PATCH] dlv/cmds: Improve subcommand help output --- Documentation/usage/dlv.md | 6 ++-- Documentation/usage/dlv_attach.md | 9 ++++-- Documentation/usage/dlv_connect.md | 4 +-- Documentation/usage/dlv_debug.md | 12 +++++--- Documentation/usage/dlv_exec.md | 11 ++++++-- Documentation/usage/dlv_run.md | 2 +- Documentation/usage/dlv_test.md | 9 ++++-- Documentation/usage/dlv_trace.md | 9 ++++-- Documentation/usage/dlv_version.md | 2 +- cmd/dlv/cmds/commands.go | 45 +++++++++++++++++++++++------- 10 files changed, 79 insertions(+), 30 deletions(-) diff --git a/Documentation/usage/dlv.md b/Documentation/usage/dlv.md index affa3e9b..8fd4ab95 100644 --- a/Documentation/usage/dlv.md +++ b/Documentation/usage/dlv.md @@ -28,11 +28,11 @@ The goal of this tool is to provide a simple yet powerful interface for debuggin ### SEE ALSO * [dlv attach](dlv_attach.md) - Attach to running process and begin debugging. * [dlv connect](dlv_connect.md) - Connect to a headless debug server. -* [dlv debug](dlv_debug.md) - Compile and begin debugging program. -* [dlv exec](dlv_exec.md) - Runs precompiled binary, attaches and begins debug session. +* [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 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. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_attach.md b/Documentation/usage/dlv_attach.md index 5958a829..df7faae6 100644 --- a/Documentation/usage/dlv_attach.md +++ b/Documentation/usage/dlv_attach.md @@ -5,7 +5,12 @@ Attach to running process and begin debugging. ### Synopsis -Attach to running process and begin debugging. +Attach to an already running process and begin debugging it. + +This command will cause Delve to take control of an already running process, and +begin a new debug session. When exiting the debug session you will have the +option to let the process continue or kill it. + ``` dlv attach pid @@ -26,4 +31,4 @@ dlv attach pid ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_connect.md b/Documentation/usage/dlv_connect.md index 24de0543..45a688ce 100644 --- a/Documentation/usage/dlv_connect.md +++ b/Documentation/usage/dlv_connect.md @@ -5,7 +5,7 @@ Connect to a headless debug server. ### Synopsis -Connect to a headless debug server. +Connect to a running headless debug server. ``` dlv connect addr @@ -26,4 +26,4 @@ dlv connect addr ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_debug.md b/Documentation/usage/dlv_debug.md index 94f00b54..27624fa1 100644 --- a/Documentation/usage/dlv_debug.md +++ b/Documentation/usage/dlv_debug.md @@ -1,12 +1,16 @@ ## dlv debug -Compile and begin debugging program. +Compile and begin debugging main package in current directory, or the package specified ### Synopsis -Compiles your program with optimizations disabled, -starts and attaches to it, and enables you to immediately begin debugging your program. +Compiles your program with optimizations disabled, starts and attaches to it. + +By default, with no arguments, Delve will compile the 'main' package in the +current directory, and begin to debug it. Alternatively you can specify a +package name and Delve will compile that package instead, and begin a new debug +session. ``` dlv debug [package] @@ -27,4 +31,4 @@ dlv debug [package] ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_exec.md b/Documentation/usage/dlv_exec.md index 6e70c5ff..e5f33b3b 100644 --- a/Documentation/usage/dlv_exec.md +++ b/Documentation/usage/dlv_exec.md @@ -1,11 +1,16 @@ ## dlv exec -Runs precompiled binary, attaches and begins debug session. +Execute a precompiled binary, and begin a debug session. ### Synopsis -Runs precompiled binary, attaches and begins debug session. +Execute a precompiled binary and begin a debug session. + +This command will cause Delve to exec the binary and immediately attach to it to +begin a new debug session. Please note that if the binary was not compiled with +optimizations disabled, it may be difficult to properly debug it. Please +consider compiling debugging binaries with -gcflags="-N -l". ``` dlv exec [./path/to/binary] @@ -26,4 +31,4 @@ dlv exec [./path/to/binary] ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_run.md b/Documentation/usage/dlv_run.md index 305206e8..9581f9fc 100644 --- a/Documentation/usage/dlv_run.md +++ b/Documentation/usage/dlv_run.md @@ -26,4 +26,4 @@ dlv run ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_test.md b/Documentation/usage/dlv_test.md index ff0dc064..feefc742 100644 --- a/Documentation/usage/dlv_test.md +++ b/Documentation/usage/dlv_test.md @@ -5,7 +5,12 @@ Compile test binary and begin debugging program. ### Synopsis -Compiles a test binary with optimizations disabled, starts and attaches to it, and enable you to immediately begin debugging your program. +Compiles a test binary with optimizations disabled and begins a new debug session. + +The test command allows you to begin a new debug session in the context of your +unit tests. By default Delve will debug the tests in the current directory. +Alternatively you can specify a package name, and Delve will debug the tests in +that package instead. ``` dlv test [package] @@ -26,4 +31,4 @@ dlv test [package] ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_trace.md b/Documentation/usage/dlv_trace.md index d4d2e321..337d3150 100644 --- a/Documentation/usage/dlv_trace.md +++ b/Documentation/usage/dlv_trace.md @@ -5,7 +5,12 @@ Compile and begin tracing program. ### Synopsis -Trace program execution. Will set a tracepoint on every function matching the provided regular expression and output information when tracepoint is hit. +Trace program execution. + +The trace sub command will set a tracepoint on every function matching the +provided regular expression and output information when tracepoint is hit. This +is useful if you do not want to begin an entire debug session, but merely want +to know what functions your process is executing. ``` dlv trace [package] regexp @@ -33,4 +38,4 @@ dlv trace [package] regexp ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/Documentation/usage/dlv_version.md b/Documentation/usage/dlv_version.md index 2f6c7795..33637d67 100644 --- a/Documentation/usage/dlv_version.md +++ b/Documentation/usage/dlv_version.md @@ -26,4 +26,4 @@ dlv version ### SEE ALSO * [dlv](dlv.md) - Delve is a debugger for the Go programming language. -###### Auto generated by spf13/cobra on 11-Apr-2016 +###### Auto generated by spf13/cobra on 20-May-2016 diff --git a/cmd/dlv/cmds/commands.go b/cmd/dlv/cmds/commands.go index 446627d4..4217abad 100644 --- a/cmd/dlv/cmds/commands.go +++ b/cmd/dlv/cmds/commands.go @@ -89,7 +89,12 @@ func New() *cobra.Command { attachCommand := &cobra.Command{ Use: "attach pid", Short: "Attach to running process and begin debugging.", - Long: "Attach to running process and begin debugging.", + Long: `Attach to an already running process and begin debugging it. + +This command will cause Delve to take control of an already running process, and +begin a new debug session. When exiting the debug session you will have the +option to let the process continue or kill it. +`, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { if len(args) == 0 { return errors.New("you must provide a PID") @@ -104,7 +109,7 @@ func New() *cobra.Command { connectCommand := &cobra.Command{ Use: "connect addr", Short: "Connect to a headless debug server.", - Long: "Connect to a headless debug server.", + Long: "Connect to a running headless debug server.", PersistentPreRunE: func(cmd *cobra.Command, args []string) error { if len(args) == 0 { return errors.New("you must provide an address as the first argument") @@ -118,9 +123,13 @@ func New() *cobra.Command { // 'debug' subcommand. debugCommand := &cobra.Command{ Use: "debug [package]", - Short: "Compile and begin debugging program.", - Long: `Compiles your program with optimizations disabled, -starts and attaches to it, and enables you to immediately begin debugging your program.`, + Short: "Compile and begin debugging main package in current directory, or the package specified", + Long: `Compiles your program with optimizations disabled, starts and attaches to it. + +By default, with no arguments, Delve will compile the 'main' package in the +current directory, and begin to debug it. Alternatively you can specify a +package name and Delve will compile that package instead, and begin a new debug +session.`, Run: debugCmd, } RootCommand.AddCommand(debugCommand) @@ -128,7 +137,13 @@ starts and attaches to it, and enables you to immediately begin debugging your p // 'exec' subcommand. execCommand := &cobra.Command{ Use: "exec [./path/to/binary]", - Short: "Runs precompiled binary, attaches and begins debug session.", + Short: "Execute a precompiled binary, and begin a debug session.", + Long: `Execute a precompiled binary and begin a debug session. + +This command will cause Delve to exec the binary and immediately attach to it to +begin a new debug session. Please note that if the binary was not compiled with +optimizations disabled, it may be difficult to properly debug it. Please +consider compiling debugging binaries with -gcflags="-N -l".`, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { if len(args) == 0 { return errors.New("you must provide a path to a binary") @@ -156,8 +171,13 @@ starts and attaches to it, and enables you to immediately begin debugging your p testCommand := &cobra.Command{ Use: "test [package]", Short: "Compile test binary and begin debugging program.", - Long: `Compiles a test binary with optimizations disabled, starts and attaches to it, and enable you to immediately begin debugging your program.`, - Run: testCmd, + Long: `Compiles a test binary with optimizations disabled and begins a new debug session. + +The test command allows you to begin a new debug session in the context of your +unit tests. By default Delve will debug the tests in the current directory. +Alternatively you can specify a package name, and Delve will debug the tests in +that package instead.`, + Run: testCmd, } RootCommand.AddCommand(testCommand) @@ -165,8 +185,13 @@ starts and attaches to it, and enables you to immediately begin debugging your p traceCommand := &cobra.Command{ Use: "trace [package] regexp", Short: "Compile and begin tracing program.", - Long: "Trace program execution. Will set a tracepoint on every function matching the provided regular expression and output information when tracepoint is hit.", - Run: traceCmd, + Long: `Trace program execution. + +The trace sub command will set a tracepoint on every function matching the +provided regular expression and output information when tracepoint is hit. This +is useful if you do not want to begin an entire debug session, but merely want +to know what functions your process is executing.`, + Run: traceCmd, } traceCommand.Flags().IntVarP(&traceAttachPid, "pid", "p", 0, "Pid to attach to.") traceCommand.Flags().IntVarP(&traceStackDepth, "stack", "s", 0, "Show stack trace with given depth.") -- GitLab