Commit 5c87b92b authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'cmake-server-basic'

7263667c Help: Add notes for topic 'cmake-server-basic'
5adde4e7 cmake-server: Add documentation
b63c1f6c cmake-server: Add unit test
d341d077 cmake-server: Implement ServerProtocol 1.0
b13d3e0d cmake-server: Bare-bones server implementation
cd049f01 cmake-server: Report server mode availablitily in Capabilities
parents 419ad051 7263667c
......@@ -702,6 +702,18 @@ endif()
# setup some Testing support (a macro defined in this file)
CMAKE_SETUP_TESTING()
# Check whether to build server mode or not:
set(CMake_HAVE_SERVER_MODE 0)
if(NOT CMake_TEST_EXTERNAL_CMAKE AND NOT CMAKE_BOOTSTRAP AND CMAKE_USE_LIBUV)
list(FIND CMAKE_CXX_COMPILE_FEATURES cxx_auto_type CMake_HAVE_CXX_AUTO_TYPE)
list(FIND CMAKE_CXX_COMPILE_FEATURES cxx_range_for CMake_HAVE_CXX_RANGE_FOR)
if(CMake_HAVE_CXX_AUTO_TYPE AND CMake_HAVE_CXX_RANGE_FOR)
if(CMake_HAVE_CXX_MAKE_UNIQUE)
set(CMake_HAVE_SERVER_MODE 1)
endif()
endif()
endif()
if(NOT CMake_TEST_EXTERNAL_CMAKE)
if(NOT CMake_VERSION_IS_RELEASE)
if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND
......
......@@ -32,6 +32,7 @@ Reference Manuals
/manual/cmake-generator-expressions.7
/manual/cmake-generators.7
/manual/cmake-language.7
/manual/cmake-server.7
/manual/cmake-modules.7
/manual/cmake-packages.7
/manual/cmake-policies.7
......
.. cmake-manual-description: CMake Server
cmake-server(7)
***************
.. only:: html
.. contents::
Introduction
============
:manual:`cmake(1)` is capable of providing semantic information about
CMake code it executes to generate a buildsystem. If executed with
the ``-E server`` command line options, it starts in a long running mode
and allows a client to request the available information via a JSON protocol.
The protocol is designed to be useful to IDEs, refactoring tools, and
other tools which have a need to understand the buildsystem in entirety.
A single :manual:`cmake-buildsystem(7)` may describe buildsystem contents
and build properties which differ based on
:manual:`generation-time context <cmake-generator-expressions(7)>`
including:
* The Platform (eg, Windows, APPLE, Linux).
* The build configuration (eg, Debug, Release, Coverage).
* The Compiler (eg, MSVC, GCC, Clang) and compiler version.
* The language of the source files compiled.
* Available compile features (eg CXX variadic templates).
* CMake policies.
The protocol aims to provide information to tooling to satisfy several
needs:
#. Provide a complete and easily parsed source of all information relevant
to the tooling as it relates to the source code. There should be no need
for tooling to parse generated buildsystems to access include directories
or compile definitions for example.
#. Semantic information about the CMake buildsystem itself.
#. Provide a stable interface for reading the information in the CMake cache.
#. Information for determining when cmake needs to be re-run as a result of
file changes.
Operation
=========
Start :manual:`cmake(1)` in the server command mode, supplying the path to
the build directory to process::
cmake -E server
The server will start up and reply with an hello message on stdout::
[== CMake Server ==[
{"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
]== CMake Server ==]
Messages sent to and from the process are wrapped in magic strings::
[== CMake Server ==[
{
... some JSON message ...
}
]== CMake Server ==]
The server is now ready to accept further requests via stdin.
Protocol API
============
General Message Layout
----------------------
All messages need to have a "type" value, which identifies the type of
message that is passed back or forth. E.g. the initial message sent by the
server is of type "hello". Messages without a type will generate an response
of type "error".
All requests sent to the server may contain a "cookie" value. This value
will he handed back unchanged in all responses triggered by the request.
All responses will contain a value "inReplyTo", which may be empty in
case of parse errors, but will contain the type of the request message
in all other cases.
Type "reply"
^^^^^^^^^^^^
This type is used by the server to reply to requests.
The message may -- depending on the type of the original request --
contain values.
Example::
[== CMake Server ==[
{"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
]== CMake Server ==]
Type "error"
^^^^^^^^^^^^
This type is used to return an error condition to the client. It will
contain an "errorMessage".
Example::
[== CMake Server ==[
{"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
]== CMake Server ==]
Type "progress"
^^^^^^^^^^^^^^^
When the server is busy for a long time, it is polite to send back replies of
type "progress" to the client. These will contain a "progressMessage" with a
string describing the action currently taking place as well as
"progressMinimum", "progressMaximum" and "progressCurrent" with integer values
describing the range of progess.
Messages of type "progress" will be followed by more "progress" messages or with
a message of type "reply" or "error" that complete the request.
"progress" messages may not be emitted after the "reply" or "error" message for
the request that triggered the responses was delivered.
Specific Message Types
----------------------
Type "hello"
^^^^^^^^^^^^
The initial message send by the cmake server on startup is of type "hello".
This is the only message ever sent by the server that is not of type "reply",
"progress" or "error".
It will contain "supportedProtocolVersions" with an array of server protocol
versions supported by the cmake server. These are JSON objects with "major" and
"minor" keys containing non-negative integer values.
Example::
[== CMake Server ==[
{"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
]== CMake Server ==]
Type "handshake"
^^^^^^^^^^^^^^^^
The first request that the client may send to the server is of type "handshake".
This request needs to pass one of the "supportedProtocolVersions" of the "hello"
type response received earlier back to the server in the "protocolVersion" field.
Each protocol version may request additional attributes to be present.
Protocol version 1.0 requires the following attributes to be set:
* "sourceDirectory" with a path to the sources
* "buildDirectory" with a path to the build directory
* "generator" with the generator name
* "extraGenerator" (optional!) with the extra generator to be used.
Example::
[== CMake Server ==[
{"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
"sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
"generator":"Ninja"}
]== CMake Server ==]
which will result in a response type "reply"::
[== CMake Server ==[
{"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
]== CMake Server ==]
indicating that the server is ready for action.
......@@ -273,6 +273,9 @@ Available commands are:
``rename <oldname> <newname>``
Rename a file or directory (on one volume).
``server``
Launch :manual:`cmake-server(7)` mode.
``sleep <number>...``
Sleep for given number of seconds.
......
cmake-server-basic
------------------
* A new :manual:`cmake-server(7)` mode was added to provide semantic
information about a CMake-generated buildsystem to clients through
a JSON protocol.
......@@ -786,6 +786,17 @@ add_executable(cmake cmakemain.cxx cmcmd.cxx cmcmd.h ${MANIFEST_FILE})
list(APPEND _tools cmake)
target_link_libraries(cmake CMakeLib)
if(CMake_HAVE_SERVER_MODE)
add_library(CMakeServerLib
cmServer.cxx cmServer.h
cmServerProtocol.cxx cmServerProtocol.h
)
target_link_libraries(CMakeServerLib CMakeLib)
set_property(SOURCE cmcmd.cxx APPEND PROPERTY COMPILE_DEFINITIONS HAVE_SERVER_MODE=1)
target_link_libraries(cmake CMakeServerLib)
endif()
# Build CTest executable
add_executable(ctest ctest.cxx ${MANIFEST_FILE})
list(APPEND _tools ctest)
......
/*============================================================================
CMake - Cross Platform Makefile Generator
Copyright 2015 Stephen Kelly <steveire@gmail.com>
Copyright 2016 Tobias Hunger <tobias.hunger@qt.io>
Distributed under the OSI-approved BSD License (the "License");
see accompanying file Copyright.txt for details.
This software is distributed WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the License for more information.
============================================================================*/
#include "cmServer.h"
#include "cmServerProtocol.h"
#include "cmVersionMacros.h"
#include "cmake.h"
#if defined(CMAKE_BUILD_WITH_CMAKE)
#include "cm_jsoncpp_reader.h"
#include "cm_jsoncpp_value.h"
#endif
const char kTYPE_KEY[] = "type";
const char kCOOKIE_KEY[] = "cookie";
const char REPLY_TO_KEY[] = "inReplyTo";
const char ERROR_MESSAGE_KEY[] = "errorMessage";
const char ERROR_TYPE[] = "error";
const char REPLY_TYPE[] = "reply";
const char PROGRESS_TYPE[] = "progress";
const char START_MAGIC[] = "[== CMake Server ==[";
const char END_MAGIC[] = "]== CMake Server ==]";
typedef struct
{
uv_write_t req;
uv_buf_t buf;
} write_req_t;
void alloc_buffer(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf)
{
(void)handle;
*buf = uv_buf_init(static_cast<char*>(malloc(suggested_size)),
static_cast<unsigned int>(suggested_size));
}
void free_write_req(uv_write_t* req)
{
write_req_t* wr = reinterpret_cast<write_req_t*>(req);
free(wr->buf.base);
free(wr);
}
void on_stdout_write(uv_write_t* req, int status)
{
(void)status;
auto server = reinterpret_cast<cmServer*>(req->data);
free_write_req(req);
server->PopOne();
}
void write_data(uv_stream_t* dest, std::string content, uv_write_cb cb)
{
write_req_t* req = static_cast<write_req_t*>(malloc(sizeof(write_req_t)));
req->req.data = dest->data;
req->buf = uv_buf_init(static_cast<char*>(malloc(content.size())),
static_cast<unsigned int>(content.size()));
memcpy(req->buf.base, content.c_str(), content.size());
uv_write(reinterpret_cast<uv_write_t*>(req), static_cast<uv_stream_t*>(dest),
&req->buf, 1, cb);
}
void read_stdin(uv_stream_t* stream, ssize_t nread, const uv_buf_t* buf)
{
if (nread > 0) {
auto server = reinterpret_cast<cmServer*>(stream->data);
std::string result = std::string(buf->base, buf->base + nread);
server->handleData(result);
}
if (buf->base)
free(buf->base);
}
cmServer::cmServer()
{
// Register supported protocols:
this->RegisterProtocol(new cmServerProtocol1_0);
}
cmServer::~cmServer()
{
if (!this->Protocol) // Daemon was never fully started!
return;
uv_close(reinterpret_cast<uv_handle_t*>(this->InputStream), NULL);
uv_close(reinterpret_cast<uv_handle_t*>(this->OutputStream), NULL);
uv_loop_close(this->Loop);
for (cmServerProtocol* p : this->SupportedProtocols) {
delete p;
}
}
void cmServer::PopOne()
{
this->Writing = false;
if (this->Queue.empty()) {
return;
}
Json::Reader reader;
Json::Value value;
const std::string input = this->Queue.front();
this->Queue.erase(this->Queue.begin());
if (!reader.parse(input, value)) {
this->WriteParseError("Failed to parse JSON input.");
return;
}
const cmServerRequest request(this, value[kTYPE_KEY].asString(),
value[kCOOKIE_KEY].asString(), value);
if (request.Type == "") {
cmServerResponse response(request);
response.SetError("No type given in request.");
this->WriteResponse(response);
return;
}
this->WriteResponse(this->Protocol ? this->Protocol->Process(request)
: this->SetProtocolVersion(request));
}
void cmServer::handleData(const std::string& data)
{
this->DataBuffer += data;
for (;;) {
auto needle = this->DataBuffer.find('\n');
if (needle == std::string::npos) {
return;
}
std::string line = this->DataBuffer.substr(0, needle);
const auto ls = line.size();
if (ls > 1 && line.at(ls - 1) == '\r')
line.erase(ls - 1, 1);
this->DataBuffer.erase(this->DataBuffer.begin(),
this->DataBuffer.begin() + needle + 1);
if (line == START_MAGIC) {
this->JsonData.clear();
continue;
}
if (line == END_MAGIC) {
this->Queue.push_back(this->JsonData);
this->JsonData.clear();
if (!this->Writing) {
this->PopOne();
}
} else {
this->JsonData += line;
this->JsonData += "\n";
}
}
}
void cmServer::RegisterProtocol(cmServerProtocol* protocol)
{
auto version = protocol->ProtocolVersion();
assert(version.first >= 0);
assert(version.second >= 0);
auto it = std::find_if(this->SupportedProtocols.begin(),
this->SupportedProtocols.end(),
[version](cmServerProtocol* p) {
return p->ProtocolVersion() == version;
});
if (it == this->SupportedProtocols.end())
this->SupportedProtocols.push_back(protocol);
}
void cmServer::PrintHello() const
{
Json::Value hello = Json::objectValue;
hello[kTYPE_KEY] = "hello";
Json::Value& protocolVersions = hello["supportedProtocolVersions"] =
Json::arrayValue;
for (auto const& proto : this->SupportedProtocols) {
auto version = proto->ProtocolVersion();
Json::Value tmp = Json::objectValue;
tmp["major"] = version.first;
tmp["minor"] = version.second;
protocolVersions.append(tmp);
}
this->WriteJsonObject(hello);
}
cmServerResponse cmServer::SetProtocolVersion(const cmServerRequest& request)
{
if (request.Type != "handshake")
return request.ReportError("Waiting for type \"handshake\".");
Json::Value requestedProtocolVersion = request.Data["protocolVersion"];
if (requestedProtocolVersion.isNull())
return request.ReportError(
"\"protocolVersion\" is required for \"handshake\".");
if (!requestedProtocolVersion.isObject())
return request.ReportError("\"protocolVersion\" must be a JSON object.");
Json::Value majorValue = requestedProtocolVersion["major"];
if (!majorValue.isInt())
return request.ReportError("\"major\" must be set and an integer.");
Json::Value minorValue = requestedProtocolVersion["minor"];
if (!minorValue.isNull() && !minorValue.isInt())
return request.ReportError("\"minor\" must be unset or an integer.");
const int major = majorValue.asInt();
const int minor = minorValue.isNull() ? -1 : minorValue.asInt();
if (major < 0)
return request.ReportError("\"major\" must be >= 0.");
if (!minorValue.isNull() && minor < 0)
return request.ReportError("\"minor\" must be >= 0 when set.");
this->Protocol =
this->FindMatchingProtocol(this->SupportedProtocols, major, minor);
if (!this->Protocol) {
return request.ReportError("Protocol version not supported.");
}
std::string errorMessage;
if (!this->Protocol->Activate(request, &errorMessage)) {
this->Protocol = CM_NULLPTR;
return request.ReportError("Failed to activate protocol version: " +
errorMessage);
}
return request.Reply(Json::objectValue);
}
void cmServer::Serve()
{
assert(!this->SupportedProtocols.empty());
assert(!this->Protocol);
this->Loop = uv_default_loop();
if (uv_guess_handle(1) == UV_TTY) {
uv_tty_init(this->Loop, &this->Input.tty, 0, 1);
uv_tty_set_mode(&this->Input.tty, UV_TTY_MODE_NORMAL);
this->Input.tty.data = this;
InputStream = reinterpret_cast<uv_stream_t*>(&this->Input.tty);
uv_tty_init(this->Loop, &this->Output.tty, 1, 0);
uv_tty_set_mode(&this->Output.tty, UV_TTY_MODE_NORMAL);
this->Output.tty.data = this;
OutputStream = reinterpret_cast<uv_stream_t*>(&this->Output.tty);
} else {
uv_pipe_init(this->Loop, &this->Input.pipe, 0);
uv_pipe_open(&this->Input.pipe, 0);
this->Input.pipe.data = this;
InputStream = reinterpret_cast<uv_stream_t*>(&this->Input.pipe);
uv_pipe_init(this->Loop, &this->Output.pipe, 0);
uv_pipe_open(&this->Output.pipe, 1);
this->Output.pipe.data = this;
OutputStream = reinterpret_cast<uv_stream_t*>(&this->Output.pipe);
}
this->PrintHello();
uv_read_start(this->InputStream, alloc_buffer, read_stdin);
uv_run(this->Loop, UV_RUN_DEFAULT);
}
void cmServer::WriteJsonObject(const Json::Value& jsonValue) const
{
Json::FastWriter writer;
std::string result = std::string("\n") + std::string(START_MAGIC) +
std::string("\n") + writer.write(jsonValue) + std::string(END_MAGIC) +
std::string("\n");
this->Writing = true;
write_data(this->OutputStream, result, on_stdout_write);
}
cmServerProtocol* cmServer::FindMatchingProtocol(
const std::vector<cmServerProtocol*>& protocols, int major, int minor)
{
cmServerProtocol* bestMatch = nullptr;
for (auto protocol : protocols) {
auto version = protocol->ProtocolVersion();
if (major != version.first)
continue;
if (minor == version.second)
return protocol;
if (!bestMatch || bestMatch->ProtocolVersion().second < version.second)
bestMatch = protocol;
}
return minor < 0 ? bestMatch : nullptr;
}
void cmServer::WriteProgress(const cmServerRequest& request, int min,
int current, int max,
const std::string& message) const
{
assert(min <= current && current <= max);
assert(message.length() != 0);
Json::Value obj = Json::objectValue;
obj[kTYPE_KEY] = PROGRESS_TYPE;
obj[REPLY_TO_KEY] = request.Type;
obj[kCOOKIE_KEY] = request.Cookie;
obj["progressMessage"] = message;
obj["progressMinimum"] = min;
obj["progressMaximum"] = max;
obj["progressCurrent"] = current;
this->WriteJsonObject(obj);
}
void cmServer::WriteParseError(const std::string& message) const
{
Json::Value obj = Json::objectValue;
obj[kTYPE_KEY] = ERROR_TYPE;
obj[ERROR_MESSAGE_KEY] = message;
obj[REPLY_TO_KEY] = "";
obj[kCOOKIE_KEY] = "";
this->WriteJsonObject(obj);
}
void cmServer::WriteResponse(const cmServerResponse& response) const
{
assert(response.IsComplete());
Json::Value obj = response.Data();
obj[kCOOKIE_KEY] = response.Cookie;
obj[kTYPE_KEY] = response.IsError() ? ERROR_TYPE : REPLY_TYPE;
obj[REPLY_TO_KEY] = response.Type;
if (response.IsError()) {
obj[ERROR_MESSAGE_KEY] = response.ErrorMessage();
}
this->WriteJsonObject(obj);
}
/*============================================================================
CMake - Cross Platform Makefile Generator
Copyright 2015 Stephen Kelly <steveire@gmail.com>
Copyright 2016 Tobias Hunger <tobias.hunger@qt.io>
Distributed under the OSI-approved BSD License (the "License");