mirror of
https://github.com/apple/swift.git
synced 2025-12-14 20:36:38 +01:00
[Gardening] De-RST DriverParseableOutput
This commit is contained in:
Robert Widmann
@@ -84,7 +84,7 @@ highly dependent on **compilation modes**. Information concerning those modes
|
||||
that's relevant to compilation performance is recounted in the following
|
||||
section; for more details on the driver, see [the driver docs](Driver.md), as
|
||||
well as docs on [driver internals](DriverInternals.md)
|
||||
and [driver parseable output](DriverParseableOutput.rst).
|
||||
and [driver parseable output](DriverParseableOutput.md).
|
||||
|
||||
After discussing compilation modes in the following section, we'll also touch on
|
||||
large-scale variation in workload that can occur _without_ obvious hotspots, in
|
||||
|
||||
@@ -1,12 +1,6 @@
|
||||
=======================
|
||||
Parseable Driver Output
|
||||
=======================
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
@@ -21,13 +15,15 @@ Message Format
|
||||
The parseable output provided by the Swift driver is provided as messages
|
||||
encoded in JSON objects. All messages are structured like this::
|
||||
|
||||
<Message Length>\n
|
||||
{
|
||||
"kind": "<Message Kind>",
|
||||
"name": "<Message Name>",
|
||||
"<key>": "<value>",
|
||||
...
|
||||
}\n
|
||||
```
|
||||
<Message Length>\n
|
||||
{
|
||||
"kind": "<Message Kind>",
|
||||
"name": "<Message Name>",
|
||||
"<key>": "<value>",
|
||||
...
|
||||
}\n
|
||||
```
|
||||
|
||||
This allows the driver to pass as much information as it wants about the ongoing
|
||||
compilation, and programs which parse this data can decide what to use and what
|
||||
@@ -65,9 +61,6 @@ If "pid" is greater than 0 it will always match the value in "process.real_pid".
|
||||
Message Kinds
|
||||
=============
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
The driver may emit four kinds of messages: "began", "finished", "signalled",
|
||||
and "skipped".
|
||||
|
||||
@@ -85,33 +78,33 @@ will specify the command which was executed under the "command_executable" and
|
||||
To get the real process identifier for the process that started, get the value
|
||||
of "process.real_pid".
|
||||
|
||||
Example::
|
||||
|
||||
{
|
||||
"kind": "began",
|
||||
"name": "compile",
|
||||
"pid": 12345,
|
||||
"process": {
|
||||
"real_pid": 12345
|
||||
```json
|
||||
{
|
||||
"kind": "began",
|
||||
"name": "compile",
|
||||
"pid": 12345,
|
||||
"process": {
|
||||
"real_pid": 12345
|
||||
},
|
||||
"inputs": ["/src/foo.swift"],
|
||||
"outputs": [
|
||||
{
|
||||
"type": "object",
|
||||
"path": "/build/foo.o"
|
||||
},
|
||||
"inputs": ["/src/foo.swift"],
|
||||
"outputs": [
|
||||
{
|
||||
"type": "object",
|
||||
"path": "/build/foo.o"
|
||||
},
|
||||
{
|
||||
"type": "swiftmodule",
|
||||
"path": "/build/foo.swiftmodule"
|
||||
},
|
||||
{
|
||||
"type": "diagnostics",
|
||||
"path": "/build/foo.dia"
|
||||
},
|
||||
],
|
||||
"command_executable": "swift",
|
||||
"command_arguments" : ["-frontend", "-c", "-primary-file", "/src/foo.swift", "/src/bar.swift", "-emit-module-path", "/build/foo.swiftmodule", "-emit-diagnostics-path", "/build/foo.dia"]
|
||||
}
|
||||
{
|
||||
"type": "swiftmodule",
|
||||
"path": "/build/foo.swiftmodule"
|
||||
},
|
||||
{
|
||||
"type": "diagnostics",
|
||||
"path": "/build/foo.dia"
|
||||
},
|
||||
],
|
||||
"command_executable": "swift",
|
||||
"command_arguments" : ["-frontend", "-c", "-primary-file", "/src/foo.swift", "/src/bar.swift", "-emit-module-path", "/build/foo.swiftmodule", "-emit-diagnostics-path", "/build/foo.dia"]
|
||||
}
|
||||
```
|
||||
|
||||
Finished Message
|
||||
----------------
|
||||
@@ -124,23 +117,23 @@ missing, no output was generated by the task.
|
||||
It will contain the process identifier of the operating system and usage under
|
||||
the "process" key. The usage is optional and could be omitted.
|
||||
|
||||
Example::
|
||||
|
||||
{
|
||||
"kind": "finished",
|
||||
"name": "compile",
|
||||
"pid": 12345,
|
||||
"exit-status": 0,
|
||||
"process": {
|
||||
"real_pid": 12345,
|
||||
"usage": {
|
||||
"utime": 22740,
|
||||
"stime": 91107,
|
||||
"maxrss": 7745536
|
||||
}
|
||||
}
|
||||
// "output" key omitted because there was no stdout/stderr.
|
||||
```json
|
||||
{
|
||||
"kind": "finished",
|
||||
"name": "compile",
|
||||
"pid": 12345,
|
||||
"exit-status": 0,
|
||||
"process": {
|
||||
"real_pid": 12345,
|
||||
"usage": {
|
||||
"utime": 22740,
|
||||
"stime": 91107,
|
||||
"maxrss": 7745536
|
||||
}
|
||||
}
|
||||
// "output" key omitted because there was no stdout/stderr.
|
||||
}
|
||||
```
|
||||
|
||||
Signalled Message
|
||||
-----------------
|
||||
@@ -157,22 +150,24 @@ the "process" key. The usage is optional and could be omitted.
|
||||
|
||||
Example::
|
||||
|
||||
{
|
||||
"kind": "signalled",
|
||||
"name": "compile",
|
||||
"pid": 12345,
|
||||
"error-message": "Segmentation fault: 11",
|
||||
"signal": 4,
|
||||
"process": {
|
||||
"real_pid": 12345,
|
||||
"usage": {
|
||||
"utime": 22740,
|
||||
"stime": 91107,
|
||||
"maxrss": 7745536
|
||||
}
|
||||
}
|
||||
// "output" key omitted because there was no stdout/stderr.
|
||||
```json
|
||||
{
|
||||
"kind": "signalled",
|
||||
"name": "compile",
|
||||
"pid": 12345,
|
||||
"error-message": "Segmentation fault: 11",
|
||||
"signal": 4,
|
||||
"process": {
|
||||
"real_pid": 12345,
|
||||
"usage": {
|
||||
"utime": 22740,
|
||||
"stime": 91107,
|
||||
"maxrss": 7745536
|
||||
}
|
||||
}
|
||||
// "output" key omitted because there was no stdout/stderr.
|
||||
}
|
||||
```
|
||||
|
||||
Skipped Message
|
||||
---------------
|
||||
@@ -181,29 +176,29 @@ A "skipped" message indicates that the driver determined a command did not need
|
||||
run during the current compilation. A "skipped" message is equivalent to a "began"
|
||||
message, with the exception that it does not include the "pid" key.
|
||||
|
||||
Example::
|
||||
|
||||
{
|
||||
"kind": "skipped",
|
||||
"name": "compile",
|
||||
"inputs": ["/src/foo.swift"],
|
||||
"outputs": [
|
||||
{
|
||||
"type": "object",
|
||||
"path": "/build/foo.o"
|
||||
},
|
||||
{
|
||||
"type": "swiftmodule",
|
||||
"path": "/build/foo.swiftmodule"
|
||||
},
|
||||
{
|
||||
"type": "diagnostics",
|
||||
"path": "/build/foo.dia"
|
||||
},
|
||||
],
|
||||
"command_executable": "swift",
|
||||
"command_arguments": ["-frontend", "-c", "-primary-file", "/src/foo.swift", "/src/bar.swift", "-emit-module-path", "/build/foo.swiftmodule", "-emit-diagnostics-path", "/build/foo.dia"]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"kind": "skipped",
|
||||
"name": "compile",
|
||||
"inputs": ["/src/foo.swift"],
|
||||
"outputs": [
|
||||
{
|
||||
"type": "object",
|
||||
"path": "/build/foo.o"
|
||||
},
|
||||
{
|
||||
"type": "swiftmodule",
|
||||
"path": "/build/foo.swiftmodule"
|
||||
},
|
||||
{
|
||||
"type": "diagnostics",
|
||||
"path": "/build/foo.dia"
|
||||
},
|
||||
],
|
||||
"command_executable": "swift",
|
||||
"command_arguments": ["-frontend", "-c", "-primary-file", "/src/foo.swift", "/src/bar.swift", "-emit-module-path", "/build/foo.swiftmodule", "-emit-diagnostics-path", "/build/foo.dia"]
|
||||
}
|
||||
```
|
||||
|
||||
Message Names
|
||||
=============
|
||||
@@ -8,7 +8,6 @@ Contents
|
||||
|
||||
IndexInvalidation
|
||||
AccessControl
|
||||
DriverParseableOutput
|
||||
ErrorHandling
|
||||
ErrorHandlingRationale
|
||||
Generics
|
||||
|
||||
Reference in New Issue
Block a user