| // Copyright 2017 The Bazel Authors. All rights reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| syntax = "proto3"; |
| |
| package starlark_debugging; |
| |
| option java_package = "com.google.devtools.build.lib.starlarkdebugging"; |
| option java_outer_classname = "StarlarkDebuggingProtos"; |
| |
| // A request sent by the debug client to the debug server. |
| message DebugRequest { |
| // A number (intended to be sequentially generated by the client) that |
| // identifies the request. The response sent by the server will contain the |
| // same sequence number so that the client can synchronize its activity if |
| // desired. |
| int64 sequence_number = 1; |
| |
| // The payload describes the type of the request and its arguments, if any. |
| oneof payload { |
| SetBreakpointsRequest set_breakpoints = 101; |
| ContinueExecutionRequest continue_execution = 102; |
| EvaluateRequest evaluate = 103; |
| ListFramesRequest list_frames = 104; |
| StartDebuggingRequest start_debugging = 105; |
| PauseThreadRequest pause_thread = 106; |
| GetChildrenRequest get_children = 107; |
| } |
| } |
| |
| // A request to update the breakpoints used by the debug server. |
| message SetBreakpointsRequest { |
| // The breakpoints that describe where the debug server should pause |
| // evaluation. |
| repeated Breakpoint breakpoint = 1; |
| } |
| |
| // A request to continue execution on a paused or stepping thread. (A stepping |
| // thread is a thread that is running as the result of a previous |
| // ContinueExecutionRequest with non-NONE stepping.) |
| // |
| // A paused thread will be resumed with the given stepping, unless thread_id is |
| // 0. A stepping thread will continue to run with its stepping condition |
| // removed, as if it were already paused. |
| message ContinueExecutionRequest { |
| // The identifier of the thread to continue. The thread must be paused or |
| // stepping. |
| // |
| // If this field is not set (i.e., zero), then all threads will be continued |
| // without stepping; the stepping field in this message will be ignored. This |
| // is typically used when the debugger disconnects from the server. |
| |
| int64 thread_id = 1; |
| |
| // Describes the stepping behavior to use when continuing execution. |
| Stepping stepping = 2; |
| } |
| |
| // A request to evaluate a Starlark statement in a thread's current environment. |
| message EvaluateRequest { |
| // The identifier of the thread in whose execution context the expression |
| // should be evaluated. |
| int64 thread_id = 1; |
| |
| // The Starlark statement to evaluate. |
| string statement = 2; |
| } |
| |
| // A request to list the stack frames of a thread. |
| message ListFramesRequest { |
| // The identifier of the thread whose stack frames should be listed. |
| int64 thread_id = 1; |
| } |
| |
| // A request to begin the debugging session. Starlark execution will block until |
| // this request is made, to allow initial setup after the connection is |
| // established (e.g. setting breakpoints). |
| message StartDebuggingRequest {} |
| |
| // A request to pause execution of a thread, or all threads. |
| message PauseThreadRequest { |
| // The identifier of the thread to be paused. |
| // |
| // If not set (i.e. zero), all current Starlark threads will be paused, and |
| // until a ContinueExecutionRequest is sent, any future Starlark threads will |
| // also start off paused. |
| int64 thread_id = 1; |
| } |
| |
| // A request to list the children of a previously-communicated Value, such as |
| // its elements (for a list or dictionary), its fields (for a struct), and so |
| // forth. |
| message GetChildrenRequest { |
| // The identifier of the relevant thread. |
| int64 thread_id = 1; |
| |
| // The identifier of the value for which children are being requested. If the |
| // value has no children, an empty list will be returned in |
| // GetChildrenResponse. |
| int64 value_id = 2; |
| } |
| |
| // There are two kinds of events: "responses", which correspond to a |
| // DebugRequest sent by the client, and other asynchronous events that may be |
| // sent by the server to notify the client of activity in the Starlark code |
| // being debugged. |
| message DebugEvent { |
| // If non-zero, this event is a response to a DebugRequest with the same |
| // sequence number. |
| int64 sequence_number = 1; |
| |
| // The payload describes the type of event and any additional information |
| // about the event. |
| oneof payload { |
| Error error = 99; |
| |
| SetBreakpointsResponse set_breakpoints = 101; |
| ContinueExecutionResponse continue_execution = 102; |
| EvaluateResponse evaluate = 103; |
| ListFramesResponse list_frames = 104; |
| StartDebuggingResponse start_debugging = 105; |
| PauseThreadResponse pause_thread = 106; |
| GetChildrenResponse get_children = 107; |
| |
| ThreadPausedEvent thread_paused = 1001; |
| ThreadContinuedEvent thread_continued = 1002; |
| } |
| } |
| |
| // A response that indicates that an error occurred while handling a debugging |
| // request. |
| message Error { |
| // A message describing the error that occurred. |
| string message = 1; |
| } |
| |
| // The response to a SetBreakpointsRequest. |
| message SetBreakpointsResponse {} |
| |
| // The response to a ContinueExecutionRequest. |
| message ContinueExecutionResponse {} |
| |
| // The response to an EvaluateRequest. |
| message EvaluateResponse { |
| // The result of evaluating a statement. |
| Value result = 1; |
| } |
| |
| // The response to a ListFramesRequest. |
| message ListFramesResponse { |
| // The list of stack frames. The first element in the list represents the |
| // topmost frame (that is, the current innermost function). |
| repeated Frame frame = 1; |
| } |
| |
| // The response to a StartDebuggingRequest. |
| message StartDebuggingResponse {} |
| |
| // The response to a PauseThreadRequest. This is an acknowledgement that the |
| // request was received. Actual pausing of individual threads happens |
| // asynchronously, and will be communicated via ThreadPausedEvent(s). |
| message PauseThreadResponse {} |
| |
| // The response to a GetChildrenRequest. |
| message GetChildrenResponse { |
| repeated Value children = 1; |
| } |
| |
| // An event indicating that a thread was paused during execution. |
| message ThreadPausedEvent { |
| // The thread that was paused. |
| PausedThread thread = 1; |
| } |
| |
| // An event indicating that a thread has continued execution after being paused. |
| message ThreadContinuedEvent { |
| // The identifier of the thread that continued executing. |
| int64 thread_id = 1; |
| } |
| |
| // A location where the debug server will pause execution. |
| message Breakpoint { |
| oneof condition { |
| // A breakpoint that is triggered when a particular line is reached. |
| // Column index will be ignored for breakpoints. The debugger only supports |
| // one breakpoint per line. If multiple breakpoints are supplied for a |
| // single line, only the last such breakpoint is accepted. |
| Location location = 1; |
| } |
| // An optional condition for the breakpoint. When present, the breakpoint will |
| // be triggered iff both the primary condition holds and this expression |
| // evaluates to True. It is unspecified how many times this expression will be |
| // evaluated, so it should be free of side-effects. |
| string expression = 2; |
| } |
| |
| // A single frame in a thread's stack trace. |
| message Frame { |
| // The name of the function that this frame represents. |
| string function_name = 1; |
| |
| // The scopes that contain value bindings accessible in this frame. |
| repeated Scope scope = 2; |
| |
| // The source location where the frame is currently paused. May not be set in |
| // some situations. |
| Location location = 3; |
| } |
| |
| // A location in Starlark source code. |
| message Location { |
| // The path of the Starlark source file. |
| string path = 1; |
| |
| // A 1-indexed line number in the file denoted by path. |
| uint32 line_number = 2; |
| |
| // A 1-indexed column number in the file denoted by path. 0 (/unset) indicates |
| // column number is unknown or irrelevant. |
| uint32 column_number = 3; |
| } |
| |
| // A scope that contains value bindings accessible in a frame. |
| message Scope { |
| // A human-readable name of the scope, such as "global" or "local". |
| string name = 1; |
| |
| // The variable bindings that are defined in this scope. |
| repeated Value binding = 2; |
| } |
| |
| // Describes the stepping behavior that should occur when execution of a thread |
| // is continued. |
| enum Stepping { |
| // Do not step; continue execution until it completes or is paused for some |
| // other reason (such as hitting another breakpoint). |
| NONE = 0; |
| |
| // If the thread is paused on a statement that contains a function call, |
| // step into that function. Otherwise, this is the same as OVER. |
| INTO = 1; |
| |
| // Step over the next statement and any functions that it may call. |
| OVER = 2; |
| |
| // Continue execution until the current function has been exited and then |
| // pause. |
| OUT = 3; |
| } |
| |
| // Information about a paused Starlark thread. |
| message PausedThread { |
| // The identifier of the thread. |
| int64 id = 1; |
| |
| // A descriptive name for the thread that can be displayed in the debugger's |
| // UI. |
| string name = 2; |
| |
| PauseReason pause_reason = 3; |
| |
| // The location in Starlark code of the next statement or expression that will |
| // be executed. |
| Location location = 4; |
| |
| // An error that occurred while evaluating a breakpoint condition. Present if |
| // and only if pause_reason is CONDITIONAL_BREAKPOINT_ERROR. |
| Error conditional_breakpoint_error = 5; |
| } |
| |
| // The reason why a thread was paused. |
| enum PauseReason { |
| // The debug server hasn't set any reason. |
| UNSET = 0; |
| |
| // The stepping condition in a ContinueExecutionRequest was hit. |
| STEPPING = 1; |
| |
| // A PauseThreadRequest was sent with thread_id=0. |
| ALL_THREADS_PAUSED = 2; |
| |
| // A PauseThreadRequest was sent with thread_id matching this thread. |
| PAUSE_THREAD_REQUEST = 3; |
| |
| // A breakpoint was hit. |
| HIT_BREAKPOINT = 4; |
| |
| // An error occurred while evaluating a breakpoint condition. |
| CONDITIONAL_BREAKPOINT_ERROR = 5; |
| |
| // Debugging just started, and a StartDebuggingRequest has not yet been |
| // received and processed. |
| INITIALIZING = 6; |
| } |
| |
| // The debugger representation of a Starlark value. |
| message Value { |
| // A label that describes this value's location or source in a value |
| // hierarchy. |
| // |
| // For example, in a stack frame, the label would be the name of the variable |
| // to which the value is bound. For a value that is an element of a list, its |
| // its label would be its subscript, such as "[4]". A value that is a field in |
| // a struct would use the field's name as its label, and so forth. |
| string label = 1; |
| |
| // A string description of the value. |
| string description = 2; |
| |
| // A string describing the type of the value. |
| // |
| // This field may be omitted if the value does not correspond to a "real" type |
| // as far as the debugging view is concerned; for example, dictionaries will |
| // be rendered as sequences of key/value pairs ("entries") but the entries |
| // themselves do not have a meaningful type with respect to our rendering. |
| string type = 3; |
| |
| // Will be false if the value is known to have no children. May sometimes be |
| // true if this isn't yet known, in which case GetChildrenResponse#children |
| // will be empty. |
| bool has_children = 4; |
| |
| // An identifier for this value, used to request its children. The same value |
| // may be known by multiple ids. Not set for values without children. |
| int64 id = 5; |
| } |