diff --git a/Documentation/api/ClientHowto.md b/Documentation/api/ClientHowto.md index 00556837..d695f280 100644 --- a/Documentation/api/ClientHowto.md +++ b/Documentation/api/ClientHowto.md @@ -65,6 +65,17 @@ Delve will respond by sending a response packet that will look like this: {"id":27, "result": {"Breakpoint": {"id":3, "name":"", "addr":4538829, "file":"/User/you/some/file.go", "line":16, "functionName":"main.main", "Cond":"", "continue":false, "goroutine":false, "stacktrace":0, "LoadArgs":null, "LoadLocals":null, "hitCount":{}, "totalHitCount":0}}, "error":null} ``` +## Selecting the API version + +Delve currently supports two version of its API, APIv1 and APIv2. By default +a headless instance of `dlv` will serve APIv1 for backward-compatibility +with older clients, however new clients should use APIv2 as new features +will only be made available through version 2. The preferred method of +switching to APIv2 is to send the `RPCServer.SetApiVersion` command right +after connecting to the backend. +Alternatively the `--api-version=2` command line option can be used when +spawning the backend. + ## Diagnostics Just like any other program, both Delve and your client have bugs. To help diff --git a/Documentation/api/json-rpc/README.md b/Documentation/api/json-rpc/README.md index cbdd7912..c690c480 100644 --- a/Documentation/api/json-rpc/README.md +++ b/Documentation/api/json-rpc/README.md @@ -8,7 +8,8 @@ Here is an (incomplete) [list of language implementations](http://json-rpc.org/w # API versions -Delve currently supports two versions of its API. By default a headless instance of `dlv` will serve APIv1, however new clients should use APIv2 as new features will only be made available through version 2. To select APIv2 use `--api-version=2` command line argument. +Delve currently supports two versions of its API. By default a headless instance of `dlv` will serve APIv1 for backward compatibility with old clients, however new clients should use APIv2 as new features will only be made available through version 2. To select APIv2 use `--api-version=2` command line argument. +Clients can also select APIv2 by sending a [SetApiVersion](https://godoc.org/github.com/go-delve/delve/service/rpccommon#RPCServer.SetApiVersion) request specifying `APIVersion = 2` after connecting to the headless instance. # API version 2 documentation diff --git a/Documentation/usage/dlv.md b/Documentation/usage/dlv.md index e10abdc3..9dd8c538 100644 --- a/Documentation/usage/dlv.md +++ b/Documentation/usage/dlv.md @@ -20,7 +20,7 @@ Pass flags to the program you are debugging using `--`, for example: ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_attach.md b/Documentation/usage/dlv_attach.md index ce6dd29a..a5828ee0 100644 --- a/Documentation/usage/dlv_attach.md +++ b/Documentation/usage/dlv_attach.md @@ -26,7 +26,7 @@ dlv attach pid [executable] ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_backend.md b/Documentation/usage/dlv_backend.md index 8fc4cb95..579817dc 100644 --- a/Documentation/usage/dlv_backend.md +++ b/Documentation/usage/dlv_backend.md @@ -19,7 +19,7 @@ are: ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_connect.md b/Documentation/usage/dlv_connect.md index 6885635b..3690ecee 100644 --- a/Documentation/usage/dlv_connect.md +++ b/Documentation/usage/dlv_connect.md @@ -15,7 +15,7 @@ dlv connect addr ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_core.md b/Documentation/usage/dlv_core.md index f7b4815f..46ce2d2d 100644 --- a/Documentation/usage/dlv_core.md +++ b/Documentation/usage/dlv_core.md @@ -21,7 +21,7 @@ dlv core ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_dap.md b/Documentation/usage/dlv_dap.md index 4cbc18ac..f538c781 100644 --- a/Documentation/usage/dlv_dap.md +++ b/Documentation/usage/dlv_dap.md @@ -22,7 +22,7 @@ dlv dap ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_debug.md b/Documentation/usage/dlv_debug.md index d00dee1b..b951a3ca 100644 --- a/Documentation/usage/dlv_debug.md +++ b/Documentation/usage/dlv_debug.md @@ -28,7 +28,7 @@ dlv debug [package] ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_exec.md b/Documentation/usage/dlv_exec.md index 2b3d123e..b275a02c 100644 --- a/Documentation/usage/dlv_exec.md +++ b/Documentation/usage/dlv_exec.md @@ -28,7 +28,7 @@ dlv exec ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_log.md b/Documentation/usage/dlv_log.md index 5f7ffa18..f5b22aba 100644 --- a/Documentation/usage/dlv_log.md +++ b/Documentation/usage/dlv_log.md @@ -34,7 +34,7 @@ and dap modes. ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_replay.md b/Documentation/usage/dlv_replay.md index f4e874cc..1ddf98eb 100644 --- a/Documentation/usage/dlv_replay.md +++ b/Documentation/usage/dlv_replay.md @@ -19,7 +19,7 @@ dlv replay [trace directory] ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_run.md b/Documentation/usage/dlv_run.md index 39744ab2..f0e7693d 100644 --- a/Documentation/usage/dlv_run.md +++ b/Documentation/usage/dlv_run.md @@ -15,7 +15,7 @@ dlv run ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_test.md b/Documentation/usage/dlv_test.md index 67c96b41..35fc3c8d 100644 --- a/Documentation/usage/dlv_test.md +++ b/Documentation/usage/dlv_test.md @@ -26,7 +26,7 @@ dlv test [package] ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_trace.md b/Documentation/usage/dlv_trace.md index a83322ee..d6b053df 100644 --- a/Documentation/usage/dlv_trace.md +++ b/Documentation/usage/dlv_trace.md @@ -33,7 +33,7 @@ dlv trace [package] regexp ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/Documentation/usage/dlv_version.md b/Documentation/usage/dlv_version.md index ab6e735e..6dbf66e7 100644 --- a/Documentation/usage/dlv_version.md +++ b/Documentation/usage/dlv_version.md @@ -15,7 +15,7 @@ dlv version ``` --accept-multiclient Allows a headless server to accept multiple client connections. - --api-version int Selects API version when headless. (default 1) + --api-version int Selects 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. --check-go-version Checks that the version of Go in use is compatible with Delve. (default true) diff --git a/cmd/dlv/cmds/commands.go b/cmd/dlv/cmds/commands.go index e26bacf9..e14e66d7 100644 --- a/cmd/dlv/cmds/commands.go +++ b/cmd/dlv/cmds/commands.go @@ -115,7 +115,7 @@ func New(docCall bool) *cobra.Command { 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.") - rootCommand.PersistentFlags().IntVar(&apiVersion, "api-version", 1, "Selects API version when headless.") + rootCommand.PersistentFlags().IntVar(&apiVersion, "api-version", 1, "Selects API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md.") 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.")