diff --git a/Documentation/usage/dlv.md b/Documentation/usage/dlv.md index bf9bd07d..7c5a56aa 100644 --- a/Documentation/usage/dlv.md +++ b/Documentation/usage/dlv.md @@ -19,30 +19,17 @@ Pass flags to the program you are debugging using `--`, for example: ### Options ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` @@ -58,3 +45,5 @@ Defaults to "debugger" when logging is enabled with --log. * [dlv trace](dlv_trace.md) - Compile and begin tracing program. * [dlv version](dlv_version.md) - Prints version. +* [dlv log](dlv_log.md) - Help about logging flags +* [dlv backend](dlv_backend.md) - Help about the `--backend` flag diff --git a/Documentation/usage/dlv_attach.md b/Documentation/usage/dlv_attach.md index 0c465825..28659ee2 100644 --- a/Documentation/usage/dlv_attach.md +++ b/Documentation/usage/dlv_attach.md @@ -19,30 +19,17 @@ dlv attach pid [executable] ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_backend.md b/Documentation/usage/dlv_backend.md new file mode 100644 index 00000000..ccdda1b6 --- /dev/null +++ b/Documentation/usage/dlv_backend.md @@ -0,0 +1,37 @@ +## dlv backend + +Help about the --backend flag. + +### Synopsis + + +The --backend flag specifies which backend should be used, possible values +are: + + default Uses lldb on macOS, native everywhere else. + native Native backend. + lldb Uses lldb-server or debugserver. + rr Uses mozilla rr (https://github.com/mozilla/rr). + + + +### Options inherited from parent commands + +``` + --accept-multiclient Allows a headless server to accept multiple client connections. + --api-version int Selects API version when headless. (default 1) + --backend string Backend selection (see 'dlv help backend'). (default "default") + --build-flags string Build flags, to be passed to the compiler. + --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) + --headless Run debug server only, in headless mode. + --init string Init file, executed by the terminal client. + -l, --listen string Debugging server listen address. (default "localhost: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') + --wd string Working directory for running the program. (default ".") +``` + +### SEE ALSO +* [dlv](dlv.md) - Delve is a debugger for the Go programming language. + diff --git a/Documentation/usage/dlv_connect.md b/Documentation/usage/dlv_connect.md index b09c027c..d2c8e20c 100644 --- a/Documentation/usage/dlv_connect.md +++ b/Documentation/usage/dlv_connect.md @@ -14,30 +14,17 @@ dlv connect addr ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_core.md b/Documentation/usage/dlv_core.md index e67ea788..0e97117a 100644 --- a/Documentation/usage/dlv_core.md +++ b/Documentation/usage/dlv_core.md @@ -20,30 +20,17 @@ dlv core ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_debug.md b/Documentation/usage/dlv_debug.md index b969017e..6d03d0be 100644 --- a/Documentation/usage/dlv_debug.md +++ b/Documentation/usage/dlv_debug.md @@ -26,30 +26,17 @@ dlv debug [package] ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_exec.md b/Documentation/usage/dlv_exec.md index d4fbe2fc..f3697a49 100644 --- a/Documentation/usage/dlv_exec.md +++ b/Documentation/usage/dlv_exec.md @@ -26,30 +26,17 @@ dlv exec ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_log.md b/Documentation/usage/dlv_log.md new file mode 100644 index 00000000..2242a428 --- /dev/null +++ b/Documentation/usage/dlv_log.md @@ -0,0 +1,51 @@ +## dlv log + +Help about logging flags. + +### Synopsis + + +Logging can be enabled by specifying the --log flag and using the +--log-output flag to select which components should produce logs. + +The argument of --log-output must be a comma separated list of component +names selected from this list: + + + debugger Log debugger commands + gdbwire Log connection to gdbserial backend + lldbout Copy output from debugserver/lldb to standard output + debuglineerr Log recoverable errors reading .debug_line + rpc Log all RPC messages + fncall Log function call protocol + minidump Log minidump loading + +Additionally --log-dest can be used to specify where the logs should be +written. +If the argument is a number it will be interpreted as a file descriptor, +otherwise as a file path. +This option will also redirect the \"API listening\" message in headless +mode. + + + +### Options inherited from parent commands + +``` + --accept-multiclient Allows a headless server to accept multiple client connections. + --api-version int Selects API version when headless. (default 1) + --backend string Backend selection (see 'dlv help backend'). (default "default") + --build-flags string Build flags, to be passed to the compiler. + --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) + --headless Run debug server only, in headless mode. + --init string Init file, executed by the terminal client. + -l, --listen string Debugging server listen address. (default "localhost: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') + --wd string Working directory for running the program. (default ".") +``` + +### SEE ALSO +* [dlv](dlv.md) - Delve is a debugger for the Go programming language. + diff --git a/Documentation/usage/dlv_replay.md b/Documentation/usage/dlv_replay.md index a869ce16..5caa7dcc 100644 --- a/Documentation/usage/dlv_replay.md +++ b/Documentation/usage/dlv_replay.md @@ -18,30 +18,17 @@ dlv replay [trace directory] ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_run.md b/Documentation/usage/dlv_run.md index dd5e8181..bdf21f59 100644 --- a/Documentation/usage/dlv_run.md +++ b/Documentation/usage/dlv_run.md @@ -14,30 +14,17 @@ dlv run ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_test.md b/Documentation/usage/dlv_test.md index 4818fc66..0b72b2a2 100644 --- a/Documentation/usage/dlv_test.md +++ b/Documentation/usage/dlv_test.md @@ -25,30 +25,17 @@ dlv test [package] ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_trace.md b/Documentation/usage/dlv_trace.md index 6179cfdb..ce608065 100644 --- a/Documentation/usage/dlv_trace.md +++ b/Documentation/usage/dlv_trace.md @@ -29,30 +29,17 @@ dlv trace [package] regexp ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/Documentation/usage/dlv_version.md b/Documentation/usage/dlv_version.md index 7e11c9bc..a0261c71 100644 --- a/Documentation/usage/dlv_version.md +++ b/Documentation/usage/dlv_version.md @@ -14,30 +14,17 @@ dlv version ### Options inherited from parent commands ``` - --accept-multiclient Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate. + --accept-multiclient Allows a headless server to accept multiple client connections. --api-version int Selects API version when headless. (default 1) - --backend string Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). - (default "default") + --backend string Backend selection (see 'dlv help backend'). (default "default") --build-flags string Build flags, to be passed to the compiler. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) --headless Run debug server only, in headless mode. --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. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the "API listening" message in headless mode. - --log-output string Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log. + --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') --wd string Working directory for running the program. (default ".") ``` diff --git a/cmd/dlv/cmds/commands.go b/cmd/dlv/cmds/commands.go index 70158a06..93c7425e 100644 --- a/cmd/dlv/cmds/commands.go +++ b/cmd/dlv/cmds/commands.go @@ -101,30 +101,17 @@ func New(docCall bool) *cobra.Command { RootCommand.PersistentFlags().StringVarP(&Addr, "listen", "l", "127.0.0.1:0", "Debugging server listen address.") RootCommand.PersistentFlags().BoolVarP(&Log, "log", "", false, "Enable debugging server logging.") - RootCommand.PersistentFlags().StringVarP(&LogOutput, "log-output", "", "", `Comma separated list of components that should produce debug output, possible values: - debugger Log debugger commands - gdbwire Log connection to gdbserial backend - lldbout Copy output from debugserver/lldb to standard output - debuglineerr Log recoverable errors reading .debug_line - rpc Log all RPC messages - fncall Log function call protocol - minidump Log minidump loading -Defaults to "debugger" when logging is enabled with --log.`) - RootCommand.PersistentFlags().StringVarP(&LogDest, "log-dest", "", "", "Writes logs to the specified file or file descriptor. If the argument is a number it will be interpreted as a file descriptor, otherwise as a file path. This option will also redirect the \"API listening\" message in headless mode.") + RootCommand.PersistentFlags().StringVarP(&LogOutput, "log-output", "", "", `Comma separated list of components that should produce debug output (see 'dlv help log')`) + RootCommand.PersistentFlags().StringVarP(&LogDest, "log-dest", "", "", "Writes logs to the specified file or file descriptor (see 'dlv help log').") RootCommand.PersistentFlags().BoolVarP(&Headless, "headless", "", false, "Run debug server only, in headless mode.") - RootCommand.PersistentFlags().BoolVarP(&AcceptMulti, "accept-multiclient", "", false, "Allows a headless server to accept multiple client connections. Note that the server API is not reentrant and clients will have to coordinate.") + RootCommand.PersistentFlags().BoolVarP(&AcceptMulti, "accept-multiclient", "", false, "Allows a headless server to accept multiple client connections.") RootCommand.PersistentFlags().IntVar(&APIVersion, "api-version", 1, "Selects API version when headless.") RootCommand.PersistentFlags().StringVar(&InitFile, "init", "", "Init file, executed by the terminal client.") RootCommand.PersistentFlags().StringVar(&BuildFlags, "build-flags", buildFlagsDefault, "Build flags, to be passed to the compiler.") RootCommand.PersistentFlags().StringVar(&WorkingDir, "wd", ".", "Working directory for running the program.") - RootCommand.PersistentFlags().StringVar(&Backend, "backend", "default", `Backend selection: - default Uses lldb on macOS, native everywhere else. - native Native backend. - lldb Uses lldb-server or debugserver. - rr Uses mozilla rr (https://github.com/mozilla/rr). -`) RootCommand.PersistentFlags().BoolVarP(&CheckGoVersion, "check-go-version", "", true, "Checks that the version of Go in use is compatible with Delve.") + RootCommand.PersistentFlags().StringVar(&Backend, "backend", "default", `Backend selection (see 'dlv help backend').`) // 'attach' subcommand. attachCommand := &cobra.Command{ @@ -299,6 +286,47 @@ https://github.com/mozilla/rr RootCommand.AddCommand(replayCommand) } + RootCommand.AddCommand(&cobra.Command{ + Use: "backend", + Short: "Help about the --backend flag.", + Long: `The --backend flag specifies which backend should be used, possible values +are: + + default Uses lldb on macOS, native everywhere else. + native Native backend. + lldb Uses lldb-server or debugserver. + rr Uses mozilla rr (https://github.com/mozilla/rr). + +`}) + + RootCommand.AddCommand(&cobra.Command{ + Use: "log", + Short: "Help about logging flags.", + Long: `Logging can be enabled by specifying the --log flag and using the +--log-output flag to select which components should produce logs. + +The argument of --log-output must be a comma separated list of component +names selected from this list: + + + debugger Log debugger commands + gdbwire Log connection to gdbserial backend + lldbout Copy output from debugserver/lldb to standard output + debuglineerr Log recoverable errors reading .debug_line + rpc Log all RPC messages + fncall Log function call protocol + minidump Log minidump loading + +Additionally --log-dest can be used to specify where the logs should be +written. +If the argument is a number it will be interpreted as a file descriptor, +otherwise as a file path. +This option will also redirect the \"API listening\" message in headless +mode. + +`, + }) + RootCommand.DisableAutoGenTag = true return RootCommand diff --git a/cmd/dlv/dlv_test.go b/cmd/dlv/dlv_test.go index 33eea1b3..d3d0b458 100644 --- a/cmd/dlv/dlv_test.go +++ b/cmd/dlv/dlv_test.go @@ -22,7 +22,6 @@ import ( protest "github.com/go-delve/delve/pkg/proc/test" "github.com/go-delve/delve/pkg/terminal" "github.com/go-delve/delve/service/rpc2" - "github.com/spf13/cobra/doc" "golang.org/x/tools/go/packages" ) @@ -240,7 +239,7 @@ func TestContinue(t *testing.T) { t.Log(scan.Text()) if scan.Text() == "hello world!" { break - } + } } // and detach from and kill the headless instance @@ -286,7 +285,7 @@ func TestGeneratedDoc(t *testing.T) { tempDir, err := ioutil.TempDir(os.TempDir(), "test-gen-doc") assertNoError(err, t, "TempDir") defer cmds.SafeRemoveAll(tempDir) - doc.GenMarkdownTree(cmds.New(true), tempDir) + exec.Command("go", "run", "scripts/gen-usage-docs.go", tempDir).Run() entries, err := ioutil.ReadDir(tempDir) assertNoError(err, t, "ReadDir") for _, doc := range entries { diff --git a/scripts/gen-cli-docs.go b/scripts/gen-cli-docs.go index 9e543a13..d85e1eda 100644 --- a/scripts/gen-cli-docs.go +++ b/scripts/gen-cli-docs.go @@ -11,7 +11,7 @@ import ( ) func main() { - fh, err := os.Create(os.ExpandEnv("$GOPATH/src/github.com/go-delve/delve/Documentation/cli/README.md")) + fh, err := os.Create(os.ExpandEnv("./Documentation/cli/README.md")) if err != nil { log.Fatalf("could not create README.md: %v", err) } diff --git a/scripts/gen-usage-docs.go b/scripts/gen-usage-docs.go index 74ed9865..244e18d5 100644 --- a/scripts/gen-usage-docs.go +++ b/scripts/gen-usage-docs.go @@ -3,10 +3,35 @@ package main import ( + "fmt" + "log" + "os" + "path/filepath" + "github.com/go-delve/delve/cmd/dlv/cmds" "github.com/spf13/cobra/doc" ) +const defaultUsageDir = "./Documentation/usage" + func main() { - doc.GenMarkdownTree(cmds.New(true), "./Documentation/usage") + usageDir := defaultUsageDir + if len(os.Args) > 1 { + usageDir = os.Args[1] + } + root := cmds.New(true) + doc.GenMarkdownTree(root, usageDir) + // 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) + } + } + fh, err := os.OpenFile(filepath.Join(usageDir, "dlv.md"), os.O_APPEND|os.O_WRONLY, 0) + if err != nil { + log.Fatalf("appending to dlv.md: %v", err) + } + defer fh.Close() + fmt.Fprintln(fh, "* [dlv log](dlv_log.md)\t - Help about logging flags") + fmt.Fprintln(fh, "* [dlv backend](dlv_backend.md)\t - Help about the `--backend` flag") }