| // 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 skylark_debugging; |
| |
| option java_package = "com.google.devtools.build.lib.skylarkdebugging"; |
| option java_outer_classname = "SkylarkDebuggingProtos"; |
| |
| // 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 { |
| ListThreadsRequest list_threads = 100; |
| SetBreakpointsRequest set_breakpoints = 101; |
| ContinueExecutionRequest continue_execution = 102; |
| EvaluateRequest evaluate = 103; |
| ListFramesRequest list_frames = 104; |
| StartDebuggingRequest start_debugging = 105; |
| PauseThreadRequest pause_thread = 106; |
| } |
| } |
| |
| // A request to list the threads that are currently active running Skylark code. |
| message ListThreadsRequest { |
| } |
| |
| // 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 thread. |
| message ContinueExecutionRequest { |
| // The identifier of the thread to continue. |
| // |
| // If this field is not set (i.e., zero), then execution of all threads will |
| // be continued. This is typically used when the debugger disconnects from the |
| // server. In this case, the stepping field is ignored. |
| int64 thread_id = 1; |
| |
| // Describes the stepping behavior to use when continuing execution. |
| Stepping stepping = 2; |
| } |
| |
| // A request to evaluate a Skylark expression 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 Skylark expression to evaluate. |
| string expression = 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. Skylark 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 and future Skylark threads will be |
| // paused until resumed via a ContinueExecutionRequest. |
| int64 thread_id = 1; |
| } |
| |
| // 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 Skylark 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; |
| |
| ListThreadsResponse list_threads = 100; |
| SetBreakpointsResponse set_breakpoints = 101; |
| ContinueExecutionResponse continue_execution = 102; |
| EvaluateResponse evaluate = 103; |
| ListFramesResponse list_frames = 104; |
| StartDebuggingResponse start_debugging = 105; |
| PauseThreadResponse pause_thread = 106; |
| |
| ThreadStartedEvent thread_started = 1000; |
| ThreadEndedEvent thread_ended = 1001; |
| ThreadPausedEvent thread_paused = 1002; |
| ThreadContinuedEvent thread_continued = 1003; |
| } |
| } |
| |
| // 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 ListThreadsRequest. |
| message ListThreadsResponse { |
| // The threads that are currently active running Skylark code. |
| repeated Thread thread = 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 an expression. |
| 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 { |
| } |
| |
| // An event indicating that a thread has begun executing Skylark code. |
| message ThreadStartedEvent { |
| // The thread that began. |
| Thread thread = 1; |
| } |
| |
| // An event indicating that a thread that was executed Skylark code has ended. |
| message ThreadEndedEvent { |
| // The thread that ended. |
| Thread thread = 1; |
| } |
| |
| // An event indicating that a thread was paused during execution. |
| message ThreadPausedEvent { |
| // The thread that was paused. |
| Thread thread = 1; |
| } |
| |
| // An event indicating that a thread has continued execution after being paused. |
| message ThreadContinuedEvent { |
| // The thread that continued executing. |
| Thread thread = 1; |
| } |
| |
| // A location or condition where the debug server will pause execution. |
| message Breakpoint { |
| oneof condition { |
| // A breakpoint that is triggered when a particular line is reached. |
| 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. |
| 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. |
| Location location = 3; |
| } |
| |
| // A location in Skylark source code. |
| message Location { |
| // The path of the Skylark source file. |
| string path = 1; |
| |
| // A 0-based line index in the file denoted by path. |
| uint32 line_index = 2; |
| |
| // A 0-based column index in the file denoted by path. |
| uint32 column_index = 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 thread that is running Skylark code. |
| message Thread { |
| // The identifier of the thread. |
| int64 id = 1; |
| |
| // Indicates whether the thread is paused (if true) or running (if false). |
| bool is_paused = 2; |
| |
| // If the thread is paused, this field contains the location in Skylark code |
| // of the next statement or expression that will be executed. |
| Location location = 3; |
| |
| // A descriptive name for the thread that can be displayed in the debugger's |
| // UI. |
| string name = 4; |
| } |
| |
| // The debugger representation of a Skylark 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; |
| |
| // Any child values associated with this value, such as its elements (for a |
| // list or dictionary), its fields (for a struct), and so forth. |
| repeated Value child = 4; |
| } |