Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CMAKE-SERVER(7)			     CMake		       CMAKE-SERVER(7)

NAME
       cmake-server - CMake Server

       Deprecated  since version 3.15: This will be removed from a future ver-
       sion of CMake.  Clients should use the cmake-file-api(7)	instead.

INTRODUCTION
       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  en-
       tirety.

       A  single  cmake-buildsystem(7)	may  describe buildsystem contents and
       build properties	which differ based on generation-time context  includ-
       ing:

       o The Platform (eg, Windows, APPLE, Linux).

       o The build configuration (eg, Debug, Release, Coverage).

       o The Compiler (eg, MSVC, GCC, Clang) and compiler version.

       o The language of the source files compiled.

       o Available compile features (eg	CXX variadic templates).

       o CMake policies.

       The  protocol aims to provide information to tooling to satisfy several
       needs:

       1. Provide a complete and easily	parsed source of all information rele-
	  vant	to the tooling as it relates to	the source code.  There	should
	  be no	need for tooling to parse generated buildsystems to access in-
	  clude	directories or compile definitions for example.

       2. Semantic information about the CMake buildsystem itself.

       3. Provide  a stable interface for reading the information in the CMake
	  cache.

       4. Information for determining when cmake needs to be re-run as	a  re-
	  sult of file changes.

OPERATION
       Start  cmake(1)	in  the	server command mode, supplying the path	to the
       build directory to process:

	  cmake	-E server (--debug|--pipe=<NAMED_PIPE>)

       The server will communicate using stdin/stdout (with the	--debug	param-
       eter)  or  using	a named	pipe (with the --pipe=<NAMED_PIPE> parameter).
       Note that "named	pipe" refers to	a local	domain socket on Unix and to a
       named pipe on Windows.

       When  connecting	 to  the  server  (via named pipe or by	starting it in
       --debug mode), the server will reply with a hello message:

	  [== "CMake Server" ==[
	  {"supportedProtocolVersions":[{"major":1,"minor":0}],"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 the  named  pipe
       or stdin.

DEBUGGING
       CMake  server  mode  can	 be  asked  to provide statistics on execution
       times, etc.  or to dump a copy of the response into  a  file.  This  is
       done passing a "debug" JSON object as a child of	the request.

       The  debug  object  supports the	"showStats" key, which takes a boolean
       and makes the server mode return	a "zzzDebug" object with stats as part
       of  its response.  "dumpToFile" takes a string value and	will cause the
       cmake server to copy the	response into the given	filename.

       This is a response from the cmake server	with "showStats" set to	true:

	  [== "CMake Server" ==[
	  {
	    "cookie":"",
	    "errorMessage":"Waiting for	type \"handshake\".",
	    "inReplyTo":"unknown",
	   "type":"error",
	    "zzzDebug":	{
	      "dumpFile":"/tmp/error.txt",
	      "jsonSerialization":0.011016,
	      "size":111,
	      "totalTime":0.025995
	    }
	  }
	  ]== "CMake Server" ==]

       The server has made a copy of this  response  into  the	file  /tmp/er-
       ror.txt and took	0.011 seconds to turn the JSON response	into a string,
       and it took 0.025 seconds to process the	request	in  total.  The	 reply
       has a size of 111 bytes.

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 "pro-
       gressMessage" with a string  describing	the  action  currently	taking
       place as	well as	"progressMinimum", "progressMaximum" and "progressCur-
       rent" with integer values describing the	range of progress.

       Messages	of type	"progress" will	be followed by	more  "progress"  mes-
       sages  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.

   Type	message
       A message is triggered when the server processes	a request and produces
       some form of output that	should be displayed to the user. A Message has
       a "message" with	the actual text	to display as well as a	"title"	with a
       suggested dialog	box title.

       Example:

	  [== "CMake Server" ==[
	  {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
	  ]== "CMake Server" ==]

   Type	signal
       The server can send signals when	 it  detects  changes  in  the	system
       state.  Signals are of type "signal", have an empty "cookie" and	"inRe-
       plyTo" field and	always have a "name" set  to  show  which  signal  was
       sent.

   Specific Signals
       The cmake server	may sent signals with the following names:

   dirty Signal
       The "dirty" signal is sent whenever the server determines that the con-
       figuration of the project is no longer up-to-date.  This	 happens  when
       any of the files	that have an influence on the build system is changed.

       The "dirty" signal may look like	this:

	  [== "CMake Server" ==[
	  {
	    "cookie":"",
	    "inReplyTo":"",
	    "name":"dirty",
	    "type":"signal"}
	  ]== "CMake Server" ==]

   fileChange Signal
       The  "fileChange" signal	is sent	whenever a watched file	is changed. It
       contains	the "path" that	has changed and	a list	of  "properties"  with
       the kind	of change that was detected. Possible changes are "change" and
       "rename".

       The "fileChange"	signal looks like this:

	  [== "CMake Server" ==[
	  {
	    "cookie":"",
	    "inReplyTo":"",
	    "name":"fileChange",
	    "path":"/absolute/CMakeLists.txt",
	    "properties":["change"],
	    "type":"signal"}
	  ]== "CMake Server" ==]

   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.
       Some  versions  may  be	marked 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 com-
       patible.	 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" ==[
	  {"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.	 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.

       Protocol	version	1.0 requires the following attributes to be set:

	  o "sourceDirectory" with a path to the sources

	  o "buildDirectory" with a path to the	build directory

	  o "generator"	with the generator name

	  o "extraGenerator" (optional!) with the extra	generator to be	used

	  o "platform" with the	generator platform (if supported by the	gener-
	    ator)

	  o "toolset" with the generator toolset (if supported by the  genera-
	    tor)

       Protocol	 version  1.2 makes all	but the	build directory	optional, pro-
       vided there is a	valid cache in the build directory that	 contains  all
       the other information already.

       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.

   Type	globalSettings
       This  request can be sent after the initial handshake. It will return a
       JSON structure with information on cmake	state.

       Example:

	  [== "CMake Server" ==[
	  {"type":"globalSettings"}
	  ]== "CMake Server" ==]

       which will result in a response type "reply":

	  [== "CMake Server" ==[
	  {
	    "buildDirectory": "/tmp/test-build",
	    "capabilities": {
	      "generators": [
		{
		  "extraGenerators": [],
		  "name": "Watcom WMake",
		  "platformSupport": false,
		  "toolsetSupport": false
		},
		<...>
	      ],
	      "serverMode": false,
	      "version": {
		"isDirty": false,
		"major": 3,
		"minor": 6,
		"patch": 20160830,
		"string": "3.6.20160830-gd6abad",
		"suffix": "gd6abad"
	      }
	    },
	    "checkSystemVars": false,
	    "cookie": "",
	    "extraGenerator": "",
	    "generator": "Ninja",
	    "debugOutput": false,
	    "inReplyTo": "globalSettings",
	    "sourceDirectory": "/home/code/cmake",
	    "trace": false,
	    "traceExpand": false,
	    "type": "reply",
	    "warnUninitialized": false,
	    "warnUnused": false,
	    "warnUnusedCli": true
	  }
	  ]== "CMake Server" ==]

   Type	setGlobalSettings
       This request can	be sent	to change the global settings attributes.  Un-
       known attributes	are going to be	ignored. Read-only attributes reported
       by "globalSettings" are all  capabilities,  buildDirectory,  generator,
       extraGenerator  and  sourceDirectory.  Any attempt to set these will be
       ignored,	too.

       All other settings will be changed.

       The server will respond with an empty reply message or an error.

       Example:

	  [== "CMake Server" ==[
	  {"type":"setGlobalSettings","debugOutput":true}
	  ]== "CMake Server" ==]

       CMake will reply	to this	with:

	  [== "CMake Server" ==[
	  {"inReplyTo":"setGlobalSettings","type":"reply"}
	  ]== "CMake Server" ==]

   Type	configure
       This request will configure a project for build.

       To configure a build directory already containing cmake	files,	it  is
       enough  to  set	"buildDirectory"  via "setGlobalSettings". To create a
       fresh build directory you  also	need  to  set  "currentGenerator"  and
       "sourceDirectory"  via  "setGlobalSettings" in addition to "buildDirec-
       tory".

       You may a list of strings to "configure"	via the	"cacheArguments"  key.
       These strings will be interpreted similar to command line arguments re-
       lated to	cache handling that are	 passed	 to  the  cmake	 command  line
       client.

       Example:

	  [== "CMake Server" ==[
	  {"type":"configure", "cacheArguments":["-Dsomething=else"]}
	  ]== "CMake Server" ==]

       CMake will reply	like this (after reporting progress for	some time):

	  [== "CMake Server" ==[
	  {"cookie":"","inReplyTo":"configure","type":"reply"}
	  ]== "CMake Server" ==]

   Type	compute
       This  request  will  generate build system files	in the build directory
       and is only available after a project was successfully "configure"d.

       Example:

	  [== "CMake Server" ==[
	  {"type":"compute"}
	  ]== "CMake Server" ==]

       CMake will reply	(after reporting progress information):

	  [== "CMake Server" ==[
	  {"cookie":"","inReplyTo":"compute","type":"reply"}
	  ]== "CMake Server" ==]

   Type	codemodel
       The "codemodel" request can be used after a project was "compute"d suc-
       cessfully.

       It will list the	complete project 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  des-
       tinquish	 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.

       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
	      contains the current build directory.

       targets
	      contains a list of build system target objects.

       Target objects define individual	build targets for a certain configura-
       tion.

       Each target object can have the following keys:

       name   contains the name	of the target.

       type   defines the type of build	of the	target.	 Possible  values  are
	      "STATIC_LIBRARY",	  "MODULE_LIBRARY",   "SHARED_LIBRARY",	  "OB-
	      JECT_LIBRARY", "EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY".

       fullName
	      contains the full	name of	the build  result  (incl.  extensions,
	      etc.).

       sourceDirectory
	      contains the current source directory.

       buildDirectory
	      contains the current build directory.

       isGeneratorProvided
	      true  if the target is auto-created by a generator, false	other-
	      wise

       hasInstallRule
	      true if the target contains any install rules, false otherwise.

       installPaths
	      full path	to the destination directories defined by  target  in-
	      stall 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

       linkerLanguage
	      contains the language of the linker used to  produce  the	 arti-
	      fact.

       linkLibraries
	      with  a  list  of	libraries to link to. This value is encoded in
	      the system's native shell	format.

       linkFlags
	      with a list of flags to pass to the linker. This	value  is  en-
	      coded in the system's native shell format.

       linkLanguageFlags
	      with  the	 flags	for  a compiler	using the linkerLanguage. This
	      value is encoded in the system's native shell format.

       frameworkPath
	      with the framework path (on Apple	computers). This value is  en-
	      coded in the system's native shell format.

       linkPath
	      with the link path. This value is	encoded	in the system's	native
	      shell format.

       sysroot
	      with the sysroot path.

       fileGroups
	      contains the source files	making up the target.

       FileGroups are used to group sources using similar settings together.

       Each fileGroup object may contain the following keys:

       language
	      contains the programming language	 used  by  all	files  in  the
	      group.

       compileFlags
	      with  a  string  containing all the flags	passed to the compiler
	      when building any	of the files in	this group. This value is  en-
	      coded in the system's native shell format.

       includePath
	      with  a  list  of	 include paths.	Each include path is an	object
	      containing a "path" with the actual include path and  "isSystem"
	      with  a bool value informing whether this	is a normal include or
	      a	system include.	This value is encoded in the  system's	native
	      shell format.

       defines
	      with   a	 list	of   defines   in   the	 form  "SOMEVALUE"  or
	      "SOMEVALUE=42". This value is encoded  in	 the  system's	native
	      shell format.

       sources
	      with a list of source files.

       All  file paths in the fileGroup	are either absolute or relative	to the
       sourceDirectory of the target.

       Example:

	  [== "CMake Server" ==[
	  {"type":"codemodel"}
	  ]== "CMake Server" ==]

       CMake will reply:

	  [== "CMake Server" ==[
	  {
	    "configurations": [
	      {
		"name":	"",
		"projects": [
		  {
		    "buildDirectory": "/tmp/build/Source/CursesDialog/form",
		    "name": "CMAKE_FORM",
		    "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
		    "targets": [
		      {
			"artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
			"buildDirectory": "/tmp/build/Source/CursesDialog/form",
			"fileGroups": [
			  {
			    "compileFlags": "  -std=gnu11",
			    "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
			    "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
			    "isGenerated": false,
			    "language":	"C",
			    "sources": [ "fld_arg.c", <...> ]
			  }
			],
			"fullName": "libcmForm.a",
			"linkerLanguage": "C",
			"name":	"cmForm",
			"sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
			"type":	"STATIC_LIBRARY"
		      }
		    ]
		  },
		  <...>
		]
	      }
	    ],
	    "cookie": "",
	    "inReplyTo": "codemodel",
	    "type": "reply"
	  }
	  ]== "CMake Server" ==]

   Type	ctestInfo
       The "ctestInfo" request can be used after a project was "compute"d suc-
       cessfully.

       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 des-
       tinquish	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.

       Each test property object can have the following	keys:

       key    contains the test	property key.

       value  contains the test	property value.

   Type	cmakeInputs
       The  "cmakeInputs"  requests will report	files used by CMake as part of
       the build system	itself.

       This request is only available after a project was  successfully	 "con-
       figure"d.

       Example:

	  [== "CMake Server" ==[
	  {"type":"cmakeInputs"}
	  ]== "CMake Server" ==]

       CMake will reply	with the following information:

	  [== "CMake Server" ==[
	  {"buildFiles":
	    [
	      {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
	      {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt",	...]},
	      {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
	    ],
	    "cmakeRootDirectory":"/usr/lib/cmake",
	    "sourceDirectory":"/home/code/src/cmake",
	    "cookie":"",
	    "inReplyTo":"cmakeInputs",
	    "type":"reply"
	  }
	  ]== "CMake Server" ==]

       All file	names are either relative to the top level source directory or
       absolute.

       The list	of files which "isCMake" set to	true are part of the cmake in-
       stallation.

       The list	of files witch "isTemporary" set to true are part of the build
       directory and will not survive the build	directory getting cleaned out.

   Type	cache
       The "cache" request will	list the cached	configuration values.

       Example:

	  [== "CMake Server" ==[
	  {"type":"cache"}
	  ]== "CMake Server" ==]

       CMake will respond with the following output:

	  [== "CMake Server" ==[
	  {
	    "cookie":"","inReplyTo":"cache","type":"reply",
	    "cache":
	    [
	      {
		"key":"SOMEVALUE",
		"properties":
		{
		  "ADVANCED":"1",
		  "HELPSTRING":"This is	not helpful"
		}
		"type":"STRING",
		"value":"TEST"}
	    ]
	  }
	  ]== "CMake Server" ==]

       The output can be limited to a list of keys by passing an array of  key
       names to	the "keys" optional field of the "cache" request.

   Type	fileSystemWatchers
       The  server can watch the filesystem for	changes. The "fileSystemWatch-
       ers" command will report	on the files and directories watched.

       Example:

	  [== "CMake Server" ==[
	  {"type":"fileSystemWatchers"}
	  ]== "CMake Server" ==]

       CMake will respond with the following output:

	  [== "CMake Server" ==[
	  {
	    "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
	    "watchedFiles": [ "/absolute/path" ],
	    "watchedDirectories": [ "/absolute"	]
	  }
	  ]== "CMake Server" ==]

COPYRIGHT
       2000-2020 Kitware, Inc. and Contributors

3.18.2				 Aug 27, 2020		       CMAKE-SERVER(7)

NAME | INTRODUCTION | OPERATION | DEBUGGING | PROTOCOL API | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cmake-server&sektion=7&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help