diff options
Diffstat (limited to 'Help/manual/cmake-server.7.rst')
| -rw-r--r-- | Help/manual/cmake-server.7.rst | 124 |
1 files changed, 120 insertions, 4 deletions
diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 9520cc1..c2aef99 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -254,6 +254,11 @@ versions supported by the cmake server. These are JSON objects with "major" and as experimental. These will contain the "isExperimental" key set to true. Enabling these requires a special command line argument when starting the cmake server mode. +Within a "major" version all "minor" versions are fully backwards compatible. +New "minor" versions may introduce functionality in such a way that existing +clients of the same "major" version will continue to work, provided they +ignore keys in the output that they do not know about. + Example:: [== "CMake Server" ==[ @@ -268,8 +273,13 @@ 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. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. -Each protocol version may request additional attributes to be present. +If the build directory already contains a CMake cache, it is sufficient to set +the "buildDirectory" attribute. To create a fresh build directory, additional +attributes are required depending on the protocol version. Protocol version 1.0 requires the following attributes to be set: @@ -448,6 +458,11 @@ Each project object can have the following keys: "name" contains the (sub-)projects name. +"minimumCMakeVersion" + contains the minimum cmake version allowed for this project, null if the + project doesn't specify one. +"hasInstallRule" + true if the project contains any install rules, false otherwise. "sourceDirectory" contains the current source directory "buildDirectory" @@ -471,6 +486,12 @@ Each target object can have the following keys: contains the current source directory. "buildDirectory" contains the current build directory. +"isGeneratorProvided" + true if the target is auto-created by a generator, false otherwise +"hasInstallRule" + true if the target contains any install rules, false otherwise. +"installPaths" + full path to the destination directories defined by target install rules. "artifacts" with a list of build artifacts. The list is sorted with the most important artifacts first (e.g. a .DLL file is listed before a @@ -496,6 +517,9 @@ Each target object can have the following keys: with the sysroot path. "fileGroups" contains the source files making up the target. +"crossReferences" + contains the location of the target in the corresponding CMakeLists.txt + file and the locations of the related statements like "target_link_libraries" FileGroups are used to group sources using similar settings together. @@ -521,6 +545,16 @@ Each fileGroup object may contain the following keys: All file paths in the fileGroup are either absolute or relative to the sourceDirectory of the target. +CrossReferences object is used to report the location of the target (including +the entire call stack if the target is defined in a function) and the related +"target_link_libraries", "target_include_directories", "target_compile_definitions" +and "target_compile_options" statements. + +See the example below for details on the internal format of the "crossReferences" object. +Line numbers stated in the "backtrace" entries are 1-based. The last entry of a backtrace +is a special entry with missing "line" and "name" fields that specifies the initial +CMakeLists.txt file. + Example:: [== "CMake Server" ==[ @@ -557,7 +591,34 @@ CMake will reply:: "linkerLanguage": "C", "name": "cmForm", "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", - "type": "STATIC_LIBRARY" + "type": "STATIC_LIBRARY", + "crossReferences": { + "backtrace": [ + { + "line": 7, + "name": "add_executable", + "path": "C:/full/path/CMakeLists.txt" + }, + { + "path": "c:/full/path/CMakeLists.txt" + } + ], + "relatedStatements": [ + { + "backtrace": [ + { + "line": 8, + "name": "target_link_libraries", + "path": "c:/full/path/CMakeLists.txt" + }, + { + "path": "c:/full/path/CMakeLists.txt" + } + ], + "type": "target_link_libraries" + } + ] + } } ] }, @@ -572,6 +633,62 @@ CMake will reply:: ]== "CMake Server" ==] +Type "ctestInfo" +^^^^^^^^^^^^^^^^ + +The "ctestInfo" request can be used after a project was "compute"d successfully. + +It will list the complete project test structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"ctestInfo" + contains a list of test objects. + +Each test object can have the following keys: + +"ctestName" + contains the name of the test. +"ctestCommand" + contains the test command. +"properties" + contains a list of test property objects. +"backtrace" + contains a list of backtrace objects that specify where the test was defined. + +Each backtrace object can have the following keys: + +"path" + contains the full path to the file containing the statement. +"line" + contains the line number in the file where the statement was defined. +"name" + contains the name of the statement that added the test. + +Each test property object can have the following keys: + +"key" + contains the test property key. +"value" + contains the test property value. + + Type "cmakeInputs" ^^^^^^^^^^^^^^^^^^ @@ -616,8 +733,7 @@ and will not survive the build directory getting cleaned out. Type "cache" ^^^^^^^^^^^^ -The "cache" request can be used once a project is configured and will -list the cached configuration values. +The "cache" request will list the cached configuration values. Example:: |