12 | {{ content }}
13 |
14 |
9 |
24 |
25 |
10 |
18 |
23 |
11 |
13 | Debug Adapter Protocol
12 |14 | The Debug Adapter Protocol (DAP) defines the abstract protocol used between a development tool (e.g. IDE or editor) and a debugger. 15 |
16 | 17 |18 |
19 | Star
21 |
22 |
26 |
76 | 77 |
105 |
--------------------------------------------------------------------------------
/js/page.js:
--------------------------------------------------------------------------------
1 | $('#small-nav-dropdown').change(function() {
2 | window.location = $(this)
3 | .find('option:selected')
4 | .val()
5 | })
6 |
7 | const site_tag = 'UA-62780441-30';
8 | function loadAnalytics(gtag) {
9 | // set cookie to expire in 12 x 28 days
10 | gtag('config', site_tag, { 'anonymize_ip': true, 'cookie_expires': 29030400 })
11 | }
12 |
13 | function onConsentChanged() {
14 | function gtag() {
15 | window.dataLayer.push(arguments)
16 | }
17 |
18 | if (!consentRequired() || WcpConsent.siteConsent.getConsentFor(WcpConsent.consentCategories.Analytics)) {
19 | // Load GA
20 | loadAnalytics(gtag)
21 | }
22 | }
23 |
24 | function consentRequired() {
25 | return WcpConsent.siteConsent.isConsentRequired;
26 | }
27 |
28 | $(function() {
29 | // Load GA upfront because we classify it as essential cookie
30 | window.dataLayer = window.dataLayer || []
31 | function gtag() {
32 | dataLayer.push(arguments)
33 | }
34 | gtag('js', new Date())
35 |
36 | window.WcpConsent && WcpConsent.init("en-US", "cookie-banner", function (err, _siteConsent) {
37 | }, onConsentChanged, WcpConsent.themes.light);
38 |
39 | const cookieManager = document.querySelector('#footer-cookie-link');
40 | if (consentRequired() && cookieManager && cookieManager.parentElement) {
41 | cookieManager.parentElement.style.visibility = 'visible';
42 | }
43 |
44 | // initialize consent
45 | onConsentChanged();
46 | })
--------------------------------------------------------------------------------
/overview.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Overview
3 | layout: singlePage
4 | sectionid: overview
5 | ---
6 |
7 | ## What is the Debug Adapter Protocol?
8 |
9 | It takes a significant effort to implement the UI for a new debugger for features like:
10 | - source-, function-, conditional-, and inline breakpoints,
11 | - variable values shown in hovers or inlined in the source,
12 | - multi-process and multi-thread support,
13 | - navigating through complex data structures,
14 | - watch expressions,
15 | - debug console for interactive evaluation with autocomplete (aka REPL),
16 | - log points.
17 |
18 | Typically this work must be repeated for each development tool, as each tool uses different APIs for implementing its user interface.
19 | This results in lots of duplicated functionality (and implementation) as visualized by the blue boxes in the following picture:
20 |
21 | 
22 |
23 | The idea behind the _Debug Adapter Protocol_ is to standardize an abstract protocol for how a development tool communicates with concrete debuggers.
24 |
25 | A similar approach was already [introduced in 2016](https://code.visualstudio.com/blogs/2016/06/27/common-language-protocol) with the [_Language Server Protocol_](https://microsoft.github.io/language-server-protocol/) which standardized an abstract protocol between an editor or IDE and a server providing "language smartness."
26 |
27 | Since it is unrealistic to assume that existing debuggers or runtimes adopt this protocol any time soon,
28 | we rather assume that an _intermediary_ component takes over the role of adapting an existing debugger or runtime API to the Debug Adapter Protocol.
29 | This intermediary becomes the _Debug Adapter_ which explains the name of the protocol: _Debug Adapter Protocol_.
30 | The following picture shows the resulting architecture:
31 |
32 | 
33 |
34 | The diagram shows that the Debug Adapter Protocol makes it possible to implement a single generic debugger UI per development tool
35 | and that Debug Adapters can be re-used across these tools. This reduces the effort to support a new debugger considerably.
36 |
37 | Standardizing on a wire-protocol instead of an API and a client library has the advantage that a debug adapter can be implemented in the language most suitable for the given debugger or runtime.
38 |
39 | Since the _Debug Adapter Protocol_ was designed for supporting the debugging UI in a language agnostic way,
40 | it is fairly high-level and does not have to surface all the fine details of the underlying language and low-level debugger API.
41 | The most important data type used in the protocol are strings, because that's what the end user will see in the UI.
42 | So Debug Adapters typically aggregate information received via debugger APIs into high-level, string-based data-structures that are directly consumed in the UI of the development tool.
43 | Since this mapping is mostly straightforward and has little complexity, Debug adapters can be developed with minimal effort.
44 |
45 | The _Debug Adapter Protocol_ is a win for both debugger/runtime providers and tooling vendors!
46 |
47 | ## How it works
48 |
49 | The following sections explain the interaction between a development tool (e.g. IDE or editor) and a debug adapter.
50 | This should not only help when implementing the Debug Adapter Protocol in a debug adapter, but also when _hosting_ the protocol in a development tool (sometimes also called "host" or "client").
51 |
52 | ### Debug Session Start
53 |
54 | When a debug session starts, the development tool needs a way to communicate with the debug adapter that implements the Debug Adapter Protocol.
55 | How the debug adapter comes to life is not part of the protocol specification, but it is still an important detail if debug adapters should work across different development tools.
56 |
57 | A development tool has basically two ways of interacting with a debug adapter:
58 | - **single session mode**: in this mode, the development tool starts a debug adapter as a standalone process and communicates with it through *stdin* and *stdout*. At the end of the debug session the debug adapter is terminated. For concurrent debug sessions, the development tool starts multiple debug adapters.
59 | - **multi session mode**: in this mode, the development tool does not start the debug adapter but assumes that it is already running and that it listens on a specific port for connections attempts. For every debug session, the development tool initiates a new communication session on a specific port and disconnects at the end of the session.
60 |
61 | After establishing a connection to the debug adapter, the development tool starts communicating with the adapter via the _base protocol_.
62 |
63 | ### Base protocol
64 |
65 | The base protocol exchanges messages that consist of a header and a content part (comparable to HTTP).
66 | The header and content part are separated by a `\r\n` (carriage return, line feed).
67 |
68 | #### Header Part
69 |
70 | The header part consists of header fields. Each header field is comprised of a key and a value, separated by ': ' (a colon and a space).
71 | Each header field is terminated by `\r\n`.
72 |
73 | Since both the last header field and the overall header itself are each terminated with `\r\n`,
74 | and since the header is mandatory, the content part of a message is always preceded (and uniquely identified) by two `\r\n` sequences.
75 |
76 | Currently only a single header field is supported and required:
77 |
78 | | Header Field Name | Value Type | Description |
79 | |:------------------|:------------|:------------|
80 | | Content-Length | number | The length of the content part in bytes. This header is required. |
81 | {: .table .table-bordered .table-responsive}
82 |
83 | The header part is encoded using the 'ASCII' encoding. This includes the `\r\n` separating the header and content part.
84 |
85 | #### Content Part
86 |
87 | The content part contains the actual content of the message. The content part of a message uses JSON to describe [requests](./specification#Base_Protocol_Request), [responses](./specification#Base_Protocol_Response), and [events](./specification#Base_Protocol_Event).
88 |
89 | The content part is encoded using `utf-8`.
90 |
91 | `integer`s defined in the protocol (JSON schema type `integer`) may be represented as 32 bit signed integers, although some properties disallow negative values. `number`s in the protocol (JSON schema type `number`) may be represented as 64 bit floating point numbers.
92 |
93 | #### Example:
94 |
95 | This example shows the JSON for the DAP [next](./specification#Requests_Next) request:
96 |
97 | ```
98 | Content-Length: 119\r\n
99 | \r\n
100 | {
101 | "seq": 153,
102 | "type": "request",
103 | "command": "next",
104 | "arguments": {
105 | "threadId": 3
106 | }
107 | }
108 | ```
109 |
110 | ### Initialization
111 |
112 | The Debug Adapter Protocol defines many features and this number is still growing, albeit slowly.
113 | However, the protocol is still at its first version because it was an explicit design goal to support new feature in a completely backward compatible way.
114 | Making this possible without version numbers requires that every new feature gets a corresponding flag that lets a development tool know whether a debug adapter supports the feature or not. The absence of the flag always means that the feature is not supported.
115 |
116 | A single feature and its corresponding flag is called a "capability" in the Debug Adapter Protocol. The open-ended set of all features flags is called DAP's "capabilities."
117 |
118 | When starting a debug session, the development tool sends an [**initialize**](./specification#Requests_Initialize) request to the adapter in order to exchange capabilities between the development tool and the debug adapter.
119 |
120 | The development tool capabilities are provided in the [**InitializeRequestArguments**](./specification#Types_InitializeRequestArguments) structure of the [**initialize**](./specification#Requests_Initialize) request and typically start with the prefix `supports`.
121 | Other pieces of information passed from the tool to the debug adapter are:
122 | - the name of the development tool,
123 | - the format of file paths, `native` or `uri`,
124 | - whether line and column values are 0 or 1 based,
125 | - the locale used by the development tool. A debug adapter is expected to return error messages that honor this locale.
126 |
127 | The debug adapter returns the supported capabilities in the [**InitializeResponse**](./specification#Types_InitializeResponse) via the [**Capabilities**](./specification#Types_Capabilities) type.
128 | It is not necessary to return an explicit `false` for unsupported capabilities.
129 |
130 | ### Launching and attaching
131 |
132 | After the debug adapter has been initialized, it is ready to accept requests for starting debugging.
133 | Two requests exist for this:
134 | - [**launch**](./specification#Requests_Launch) request: the debug adapter launches the program ("debuggee") in debug mode and then starts to communicate with it.
135 | Since the debug adapter is responsible for launching the debuggee, it should provide a mechanism for the end user to configure the debuggee. For example, passing arguments or specifying a working directory.
136 | - Debug adapters are free to launch the debuggee however they choose. Typically the debuggee is launched as a child process and its output channels are connected to a client's debug console via [**output**](./specification.md#Events_Output) events. However, this has certain limitations, such as not being able to write to the terminal device directly and not being able to accept standard input. For those cases, launching the debuggee in a terminal is preferable. A debug adapter can use the [**runInTerminal**](./specification#Reverse_Requests_RunInTerminal) request to ask the client to launch the debuggee in a terminal that is integrated into the client or in a terminal that runs outside of the client (but still configured and managed from the client).
137 | - [**attach**](./specification#Requests_Attach) request: the debug adapter connects to an already running program. Here the end user is responsible for launching and terminating the program.
138 |
139 | Since arguments for both requests are highly dependent on a specific debugger and debug adapter implementation, the Debug Adapter Protocol does not specify any arguments for these requests.
140 | Instead, the development tool is expected to get information about debugger specific arguments from elsewhere (e.g. contributed by some plugin or extension mechanism)
141 | and to build a UI and validation mechanism on top of that.
142 |
143 | ### Configuring breakpoint and exception behavior
144 |
145 | Since the development tool implements a generic debugger UI, it is responsible for managing breakpoints and other configurable options like exceptions.
146 | This configuration information must be passed to the debug adapter before program execution starts.
147 | Some debuggers are able to deal with this information very early, even before the debuggee is known; other debuggers accept this information only when the debuggee is about to start running.
148 |
149 | Since the development tool does not know when is the correct moment for passing the configuration information to the adapter,
150 | the debug adapter is expected to send an [**initialized**](./specification#Events_Initialized) event to the development tool
151 | to announce that it is ready to accept configuration requests.
152 | With this approach a debug adapter does not have to implement a buffering strategy for configuration information.
153 |
154 | In response to the *initialized* event, the development tool sends the configuration information using these requests:
155 | * [**setBreakpoints**](./specification#Requests_SetBreakpoints) one request for all breakpoints in a single source,
156 | * [**setFunctionBreakpoints**](./specification#Requests_SetFunctionBreakpoints) if the debug adapter supports function breakpoints,
157 | * [**setExceptionBreakpoints**](./specification#Requests_SetExceptionBreakpoints) if the debug adapter supports any exception options,
158 | * [**configurationDoneRequest**](./specification#Requests_ConfigurationDone) to indicate the end of the configuration sequence.
159 |
160 | The *setBreakpoints* request registers all breakpoints that exist for a single source (so it is not incremental).
161 | A simple implementation of these semantics in the debug adapter is to clear all previous breakpoints for the source and then set the breakpoints specified in the request.
162 | *setBreakpoints* and *setFunctionBreakpoints* are expected to return the 'actual' breakpoints and the generic debugger updates the UI dynamically if a breakpoint could not be set at the requested position or was moved by the debugger.
163 |
164 | If a debug adapter is unable to apply a breakpoint at the time when it's first sent, it should mark the breakpoint as unverified using `verified: false` in the `SetBreakpointsResponse`. If the breakpoint changes its state at a later point in time, the debug adapter should use the [**breakpoint**](./specification#Events_Breakpoint) event to notify the client.
165 |
166 | ### Launch Sequencing
167 |
168 | There are three main building blocks we've discussed to create a debugging session:
169 |
170 | - Initialization, via the `initialize` request,
171 | - Configuration of breakpoints and exceptions during the configuration stage, and
172 | - Starting the debugger, via a launch or attach request.
173 |
174 | Initialization happens first, and the debug adapter must respond to the `initialize` request with any capabilities before any further communication can take place. At any point after the client receives the capabilities, it sends a `launch` or `attach` request.
175 |
176 | Once the debug adapter is ready to receive configuration from the client, it sends an `initialized` event to the client. As described above, the client sends zero or more configuration-related requests before sending a `configurationDone` request.
177 |
178 | After the response to `configurationDone` is sent, the debug adapter may respond to the `launch` or `attach` request, and then the debug session has started.
179 |
180 | The following sequence diagram summarizes the sequence of requests and events for a hypothetical _gdb_ debug adapter:
181 |
182 |
27 |
43 |
74 |
75 |
44 |
73 |
45 |
72 |
46 |
71 |
47 |
54 |
48 |
53 |
49 | 
50 |
52 |
50 | VS Code showing inline values powered by the Python Debug Adapter
51 |
55 |
62 |
56 |
61 |
57 | 
58 |
60 |
58 | VS Code's multi-thread debugging powered by the Java Debug Adapter
59 |
63 |
70 |
64 |
69 |
65 | 
66 |
68 |
66 | REPL console in VS Code powered by the Node.js Debug Adapter
67 |76 | 77 |
78 |
104 |
79 |
85 | 80 |
Overview
81 |82 | The protocol defines the format of the messages sent using JSON between the development tool and the debug adapter. 83 |
84 |
86 |
95 | 87 |
Specification
88 |89 | The latest version of the protocol specification is version 1.70.0. 90 |
91 |92 | Change History 93 |
94 |
96 |
103 | 97 | {% assign sorted = site.implementors | sort: 'index' %} 98 |
Implementations
99 |100 | The DAP has been implemented for many debuggers or runtimes and some development tools are hosting these debug adapters. 101 |
102 |
183 |
184 | ### Stopping and accessing debuggee state
185 |
186 | Whenever the program stops (on program entry, because a breakpoint was hit, an exception occurred, or the user requested execution to be paused),
187 | the debug adapter sends a [**stopped**](./specification#Events_Stopped) event with the appropriate reason and thread id.
188 |
189 | Upon receipt, the development tool first requests the [`threads`](./specification#Types_Thread) (see below) and then the *stacktrace* (a list of [`stack frames`](./specification#Types_StackFrame)) for the thread mentioned in the stopped event.
190 | If the user then drills into the stack frame, the development tool first requests the [`scopes`](./specification#Types_Scope) for a stack frame, and then the [`variables`](./specification#Types_Variable) for a scope.
191 | If a variable is itself structured, the development tool requests its properties through additional *variables* requests.
192 | This leads to the following request waterfall:
193 |
194 | ```
195 | Threads
196 | StackTrace
197 | Scopes
198 | Variables
199 | ...
200 | Variables
201 | ```
202 |
203 | The value of variables can be modified through the [**setVariable**](./specification#Requests_SetVariable) request.
204 |
205 | #### Lifetime of Objects References
206 |
207 | Some complex structural objects such as [`scopes`](./specification#Types_Scope) or [`variables`](./specification#Types_Variable) are not returned directly with their containers ([`stack frames`](./specification#Types_StackFrame), [`scopes`](./specification#Types_Scope), [`variables`](./specification#Types_Variable)), but must be retrieved with separate [**scopes**](./specification#Requests_Scopes) and [**variables**](./specification#Requests_Variables) requests based on *object references*. An object reference is an integer in the open interval (0, 231) assigned to objects by the debug adapter.
208 |
209 | To simplify the management of object references in debug adapters, their lifetime is limited to the current suspended state. Once execution resumes, object references become invalid and DAP clients must not use them. When execution is paused again, object references no longer refer to the same objects. This means that a debug adapter can easily use sequentially assigned integers for different objects and reset the counter to 1 when execution resumes.
210 |
211 | Variable references not related to the current suspended state, such as those from `evaluate` requests or in `output` events, should be preserved as long as feasible for the debug adapter so that the client may later inspect them.
212 |
213 | Please note that other object references like `threadId` do not have limited lifetime because that would prevent something like the `pause` request from working in the running state.
214 |
215 | ### Supporting threads
216 |
217 | Whenever the generic debugger receives a [**stopped**](./specification#Events_Stopped) or a [**thread**](./specification#Events_Thread) event, the development tool requests all [`threads`](./specification#Types_Thread) that exist at that point in time. [**Thread**](./specification#Events_Thread) events are optional, but a debug adapter can send them to force the development tool to update the threads UI dynamically even when not in a stopped state. If a debug adapter decides not to emit [**Thread**](./specification#Events_Thread) events, the thread UI in the development tool will only update if a [**stopped**](./specification#Events_Stopped) event is received.
218 |
219 | After a successful *launch* or *attach*, the development tool requests the baseline of currently existing threads with the [**threads**](./specification#Requests_Threads) request and then starts to listen for [**thread**](./specification#Events_Thread) events to detect new or terminated threads. Even if a debug adapter does not support multiple threads, it must implement the [**threads**](./specification#Requests_Threads) request and return a single (dummy) thread. The thread id must be used in all requests which refer to a thread, e.g. [**stacktrace**](./specification#Requests_Stacktrace), [**pause**](./specification#Requests_Pause), [**continue**](./specification#Requests_Continue), [**next**](./specification#Requests_Next), [**stepIn**](./specification#Requests_StepIn), and [**stepOut**](./specification#Requests_StepOut).
220 |
221 | ### Debug session end
222 |
223 | When the development tool ends a debug session, the sequence of events is slightly different based on whether the session has been initially "launched" or "attached":
224 |
225 | - Debuggee **_launched_**:
226 | if a debug adapter supports the [**terminate**](./specification#Requests_Terminate) request, the development tool uses it to terminate the debuggee gracefully, i.e. it gives the debuggee a chance to cleanup everything before terminating. If the debuggee does not terminate but continues to run (or hits a breakpoint), the debug session will continue, but if the development tool tries again to terminate the debuggee, it will then use the [**disconnect**](./specification#Requests_Disconnect) request to end the debug session unconditionally. The *disconnect* request is expected to terminate the debuggee (and any child processes) forcefully.
227 | - Debuggee **_attached_**:
228 | If the debuggee has been "attached" initially, the development tool issues a [**disconnect**](./specification#Requests_Disconnect) request. This should detach the debugger from the debuggee but will allow it to continue.
229 |
230 | In all situations where a debug adapter wants to end the debug session, a [**terminated**](./specification#Events_Terminated) event must be fired.
231 |
232 | If the debuggee has ended (and the debug adapter is able to detect this), an optional [**exited**](./specification#Events_Exited) event can be issued to return the exit code to the development tool.
233 |
234 | This diagram summarizes the sequence of request and events for a hypothetical debug adapter for _gdb_:
235 |
236 | 
237 |
238 | ## Libraries (SDKs) for DAP providers and consumers
239 |
240 | To simplify the implementation of debug adapters, there are libraries or SDKs:
241 |
242 | - *Debug Adapter SDKs* for the different implementation languages there is an SDK to implement a debug adapter in a particular language. For example, to implement a debug adapter using Node.js there is the [debug adapter npm module](https://www.npmjs.com/package/@vscode/debugadapter).
243 |
--------------------------------------------------------------------------------
/spec-generator/generator.ts:
--------------------------------------------------------------------------------
1 | /*---------------------------------------------------------
2 | * Copyright (C) Microsoft Corporation. All rights reserved.
3 | *--------------------------------------------------------*/
4 |
5 | 'use strict';
6 |
7 | import * as fs from 'fs';
8 | import {IProtocol, Protocol as P} from './json_schema';
9 |
10 | const MAX_LINE_LENGTH = 80;
11 |
12 | class OutlineNode {
13 |
14 | private children: OutlineNode[] = [];
15 | public readonly anchor: string;
16 |
17 | constructor(
18 | parent: OutlineNode,
19 | private title: string
20 | ) {
21 | if (parent) {
22 | parent.children.push(this);
23 | let a = title;
24 | if (parent.anchor) {
25 | a = `${parent.anchor}_${title}`;
26 | }
27 | this.anchor = a.replace(/ /g, '_');
28 | }
29 | }
30 |
31 | dump(level = 0): string {
32 | let outline = '';
33 | const indent = ' '.repeat(level);
34 | outline += `${indent}- title: ${this.title}\n`;
35 | if (this.anchor) {
36 | outline += `${indent} anchor: ${this.anchor}\n`;
37 | }
38 | if (this.children.length > 0) {
39 | this.children = this.children.sort((a, b) => a.title.localeCompare(b.title));
40 | outline += `${indent} children:\n`;
41 | for (let c of this.children) {
42 | outline += c.dump(level+1);
43 | }
44 | }
45 | return outline;
46 | }
47 | }
48 |
49 | //---- Markdown ------------------------------------------------------------------------------------
50 |
51 | function MarkDown(schema: IProtocol): string {
52 |
53 | let s = '';
54 |
55 | s += '---\n';
56 | s += 'title: Specification\n';
57 | s += 'layout: specification\n';
58 | s += 'sectionid: specification\n';
59 | s += 'toc: true\n';
60 | s += `schemaTitle: ${schema.title}\n`;
61 | s += '---\n\n';
62 |
63 | s += '\n\n';
64 | s += Header(1, schema.title);
65 | s += description(schema);
66 |
67 | s += 'A machine-readable JSON schema can be found [here](./debugAdapterProtocol.json).\n\n';
68 |
69 | s += 'The change history of the specification lives [here](./changelog).\n';
70 |
71 | for (let typeName in schema.definitions) {
72 |
73 | const d2 = schema.definitions[typeName];
74 |
75 | let supertype: string = null;
76 | if (((.*)<\/code>/g, "'$1'");
270 | const ind = indent();
271 | return `${ind}/**` + breakLines('\n' + description, ' ', ` * `) + `\n${ind} */\n`;
272 | }
273 | }
274 | return '';
275 | }
276 |
277 | function breakLines(s: string, breakPat: string, lineStart: string): string {
278 | s = s.replace(/\n/g, `${breakPat}@@@${breakPat}`); // preserve newlines as a special word
279 | let ind = `${indent()}${lineStart}`;
280 | const result: string[] = [];
281 | const words= s.split(breakPat);
282 | let line = '';
283 | for (let w of words) {
284 |
285 | if (w === '@@@') {
286 | // force a new line
287 | result.push(line);
288 | line = '';
289 | continue;
290 | }
291 |
292 | if (ind.length + line.length + w.length + 1 > MAX_LINE_LENGTH) {
293 | // word doesn't fit into line: start a new line
294 | result.push(line);
295 | line = '';
296 | }
297 |
298 | if (line.length > 0) {
299 | line += breakPat;
300 | }
301 | line += w;
302 | }
303 | if (line.length > 0) {
304 | result.push(line);
305 | }
306 | return result.map(l => l.trimEnd()).join(`\n${ind}`);
307 | }
308 |
309 | function openBlock(str: string, openChar?: string, indent?: boolean): string {
310 | indent = typeof indent === 'boolean' ? indent : true;
311 | openChar = openChar || ' {';
312 | let s = line(`${str}${openChar}`, true, indent);
313 | numIndents++;
314 | return s;
315 | }
316 |
317 | function closeBlock(closeChar?: string, newline?: boolean): string {
318 | newline = typeof newline === 'boolean' ? newline : true;
319 | closeChar = closeChar || '}';
320 | numIndents--;
321 | return line(closeChar, newline);
322 | }
323 |
324 | function propertyType(prop: any): string {
325 | if (prop.$ref) {
326 | return getRef(prop.$ref);
327 | }
328 | if (Array.isArray(prop.oneOf)) {
329 | return (prop.oneOf as any[]).map(t => propertyType(t)).join(' | ')
330 | }
331 | switch (prop.type) {
332 | case 'array':
333 | const s = propertyType(prop.items);
334 | if (s.indexOf(' ') >= 0) {
335 | return `(${s})[]`;
336 | }
337 | return `${s}[]`;
338 | case 'object':
339 | return objectType(prop);
340 | case 'string':
341 | if (prop.enum) {
342 | return breakLines(enumAsOrType(prop.enum), ' | ', ` | `);
343 | } else if (prop._enum) {
344 | return breakLines(enumAsOrType(prop._enum, true), ' | ', ` | `);
345 | }
346 | return `string`;
347 | case 'integer':
348 | return 'number';
349 | }
350 | if (Array.isArray(prop.type)) {
351 | if (prop.type.length === 7 && prop.type.sort().join() === 'array,boolean,integer,null,number,object,string') { // silly way to detect all possible json schema types
352 | return 'any';
353 | } else {
354 | return prop.type.map(v => v === 'integer' ? 'number' : v).join(' | ');
355 | }
356 | }
357 | return prop.type;
358 | }
359 |
360 | function objectType(prop: any): string {
361 | if (prop.properties) {
362 | let s = openBlock('', '{', false);
363 |
364 | let i = 0;
365 | for (let propName in prop.properties) {
366 | if (i++ > 0) {
367 | s += '\n';
368 | }
369 | const required = prop.required ? prop.required.indexOf(propName) >= 0 : false;
370 | s += property(propName, !required, prop.properties[propName]);
371 | }
372 |
373 | s += closeBlock('}', false);
374 | return s;
375 | }
376 |
377 | if (typeof prop.additionalProperties === 'boolean') {
378 | return `{ [key: string]: any; }`;
379 | }
380 |
381 | if (prop.additionalProperties) {
382 | return `{ [key: string]: ${orType(prop.additionalProperties.type)}; }`;
383 | }
384 | return '{}';
385 | }
386 |
387 | function orType(enm: string | string[]): string {
388 | if (typeof enm === 'string') {
389 | return enm;
390 | }
391 | return enm.join(' | ');
392 | }
393 |
394 | function property(name: string, optional: boolean, prop: P.PropertyType): string {
395 | let s = '';
396 | s += comment(prop);
397 | const type = propertyType(prop);
398 | const propertyDef = `${name}${optional ? '?' : ''}: ${type}`;
399 | if (type[0] === '\'' && type[type.length-1] === '\'' && type.indexOf('|') < 0) {
400 | s += line(`${propertyDef};`);
401 | } else {
402 | s += line(`${propertyDef};`);
403 | }
404 | return s;
405 | }
406 |
407 | function getRef(ref: string): string {
408 | const REXP = /#\/(.+)\/(.+)/;
409 | const matches = REXP.exec(ref);
410 | if (matches && matches.length === 3) {
411 | return matches[2];
412 | }
413 | console.log('error: ref');
414 | return ref;
415 | }
416 |
417 | function indent(): string {
418 | return ' '.repeat(numIndents);
419 | }
420 |
421 | function line(str?: string, newline?: boolean, indnt?: boolean): string {
422 | newline = typeof newline === 'boolean' ? newline : true;
423 | indnt = typeof indnt === 'boolean' ? indnt : true;
424 | let s = '';
425 | if (str) {
426 | if (indnt) {
427 | s += indent();
428 | }
429 | s += str;
430 | }
431 | if (newline) {
432 | s += '\n';
433 | }
434 | return s;
435 | }
436 |
437 | /// Main
438 |
439 | const debugProtocolSchema = JSON.parse(fs.readFileSync('./debugAdapterProtocol.json').toString());
440 |
441 | fs.writeFileSync(`specification.md`, MarkDown(debugProtocolSchema), { encoding: 'utf-8'});
442 |
443 | fs.writeFileSync(`_data/specification-toc.yml`, outline.dump(), { encoding: 'utf-8'});
444 |
--------------------------------------------------------------------------------
/spec-generator/json_schema.d.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * TypeScript definitions for a subset of the json schema.
3 | */
4 |
5 | export interface IProtocol {
6 |
7 | $schema: string,
8 | title: string,
9 | description: string,
10 | type: "object",
11 |
12 | definitions: { [key: string]: Protocol.Definition2 }
13 | }
14 |
15 | export module Protocol {
16 |
17 | export interface Definition extends ObjectType {
18 | }
19 |
20 | export interface AllOf {
21 | allOf: (Definition | RefType ) []
22 | }
23 |
24 | export type Definition2 = Definition | AllOf | StringType;
25 | type PropertyType = PrimitiveType | StringType | ObjectType | ArrayType;
26 |
27 | export interface PrimitiveType extends BaseType {
28 | type: "number" | "integer" | "boolean"
29 | }
30 |
31 | export interface Commentable {
32 | /** Description of the type */
33 | description?: string
34 | /** Possible values of a string. */
35 | enum?: string[]
36 | /** Possible descriptions for the values of a string. */
37 | enumDescriptions?: string[]
38 | /** Possible values of a string. */
39 | _enum?: string[]
40 | }
41 |
42 | export interface StringType extends BaseType, Commentable {
43 | type: "string"
44 | /** Possible values of a string. */
45 | enum?: string[]
46 | /** Possible descriptions for the values of a string. */
47 | enumDescriptions?: string[]
48 | /** Possible values of a string. */
49 | _enum?: string[]
50 | }
51 |
52 | export interface ObjectType extends BaseType {
53 | type: "object"
54 | /** Properties of the type. Maps to a typed object */
55 | properties?: { [key: string]: PropertyType; }
56 | /** Names of required properties */
57 | required?: string[],
58 | /** Are additional properties allowed? */
59 | additionalProperties?: boolean
60 | }
61 |
62 | export interface ArrayType extends BaseType {
63 | type: "array"
64 | /** Maps to a typed array e.g string[] */
65 | items: RefType | PrimitiveType | StringType | ObjectType
66 | /** Cardinality of length of array type */
67 | //minItems?: number
68 | //maxItems?: number
69 | }
70 |
71 | export interface RefType {
72 | /** Reference to a domain defined type */
73 | $ref: string
74 | }
75 |
76 | export interface BaseType {
77 | /** Description of the type */
78 | description?: string
79 | }
80 | }
--------------------------------------------------------------------------------
/spec-generator/package-lock.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "spec-generator",
3 | "version": "0.0.1",
4 | "lockfileVersion": 2,
5 | "requires": true,
6 | "packages": {
7 | "": {
8 | "name": "spec-generator",
9 | "version": "0.0.1",
10 | "devDependencies": {
11 | "@types/node": "^16.0.0",
12 | "typescript": "^4.5.5"
13 | }
14 | },
15 | "node_modules/@types/node": {
16 | "version": "16.11.22",
17 | "resolved": "https://registry.npmjs.org/@types/node/-/node-16.11.22.tgz",
18 | "integrity": "sha512-DYNtJWauMQ9RNpesl4aVothr97/tIJM8HbyOXJ0AYT1Z2bEjLHyfjOBPAQQVMLf8h3kSShYfNk8Wnto8B2zHUA==",
19 | "dev": true
20 | },
21 | "node_modules/typescript": {
22 | "version": "4.5.5",
23 | "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.5.5.tgz",
24 | "integrity": "sha512-TCTIul70LyWe6IJWT8QSYeA54WQe8EjQFU4wY52Fasj5UKx88LNYKCgBEHcOMOrFF1rKGbD8v/xcNWVUq9SymA==",
25 | "dev": true,
26 | "bin": {
27 | "tsc": "bin/tsc",
28 | "tsserver": "bin/tsserver"
29 | },
30 | "engines": {
31 | "node": ">=4.2.0"
32 | }
33 | }
34 | },
35 | "dependencies": {
36 | "@types/node": {
37 | "version": "16.11.22",
38 | "resolved": "https://registry.npmjs.org/@types/node/-/node-16.11.22.tgz",
39 | "integrity": "sha512-DYNtJWauMQ9RNpesl4aVothr97/tIJM8HbyOXJ0AYT1Z2bEjLHyfjOBPAQQVMLf8h3kSShYfNk8Wnto8B2zHUA==",
40 | "dev": true
41 | },
42 | "typescript": {
43 | "version": "4.5.5",
44 | "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.5.5.tgz",
45 | "integrity": "sha512-TCTIul70LyWe6IJWT8QSYeA54WQe8EjQFU4wY52Fasj5UKx88LNYKCgBEHcOMOrFF1rKGbD8v/xcNWVUq9SymA==",
46 | "dev": true
47 | }
48 | }
49 | }
50 |
--------------------------------------------------------------------------------
/spec-generator/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "spec-generator",
3 | "version": "0.0.1",
4 | "description": "Generator",
5 | "author": {
6 | "name": "Microsoft Corporation",
7 | "email": "aweinand@microsoft.com"
8 | },
9 | "main": "out/generator.js",
10 | "private": true,
11 | "repository": {
12 | "type": "git",
13 | "url": "https://github.com/Microsoft/debug-adapter-protocol.git"
14 | },
15 | "bugs": {
16 | "url": "https://github.com/Microsoft/debug-adapter-protocol/issues"
17 | },
18 | "devDependencies": {
19 | "@types/node": "^16.0.0",
20 | "typescript": "^4.5.5"
21 | },
22 | "scripts": {
23 | "compile": "tsc -p .",
24 | "watch": "tsc -w -p ."
25 | }
26 | }
27 |
--------------------------------------------------------------------------------
/spec-generator/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "module": "commonjs",
4 | "moduleResolution": "node",
5 | "noImplicitAny": false,
6 | "removeComments": false,
7 | "preserveConstEnums": true,
8 | "target": "ES6",
9 | "sourceMap": true,
10 | "inlineSourceMap": false,
11 | "outDir": "./out",
12 | "typeRoots": [ "./node_modules/@types/" ],
13 | "strictNullChecks": false
14 | },
15 | "exclude": [
16 | "node_modules"
17 | ]
18 | }
19 |
--------------------------------------------------------------------------------
/webfonts/fa-brands-400.eot:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-brands-400.eot
--------------------------------------------------------------------------------
/webfonts/fa-brands-400.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-brands-400.ttf
--------------------------------------------------------------------------------
/webfonts/fa-brands-400.woff:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-brands-400.woff
--------------------------------------------------------------------------------
/webfonts/fa-brands-400.woff2:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-brands-400.woff2
--------------------------------------------------------------------------------
/webfonts/fa-regular-400.eot:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-regular-400.eot
--------------------------------------------------------------------------------
/webfonts/fa-regular-400.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-regular-400.ttf
--------------------------------------------------------------------------------
/webfonts/fa-regular-400.woff:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-regular-400.woff
--------------------------------------------------------------------------------
/webfonts/fa-regular-400.woff2:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-regular-400.woff2
--------------------------------------------------------------------------------
/webfonts/fa-solid-900.eot:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-solid-900.eot
--------------------------------------------------------------------------------
/webfonts/fa-solid-900.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-solid-900.ttf
--------------------------------------------------------------------------------
/webfonts/fa-solid-900.woff:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-solid-900.woff
--------------------------------------------------------------------------------
/webfonts/fa-solid-900.woff2:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/microsoft/debug-adapter-protocol/d863f0108ab0a5e374b727ef162cc926046fda78/webfonts/fa-solid-900.woff2
--------------------------------------------------------------------------------