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

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
       entirety.

       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
	  include 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
	  result 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).

       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/error.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 progess.

       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.

       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:

	  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)

       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.
       Unknown	attributes  are	 going	to  be	ignored.  Read-only attributes
       reported	by "globalSettings" are	all capabilities, buildDirectory, gen-
       erator,	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
       related 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.

       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",
	      "OBJECT_LIBRARY",	  "EXECUTABLE",	   "UTILITY"	and    "INTER-
	      FACE_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.

       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
	      encoded 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
	      encoded 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
	      encoded 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	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
       installation.

       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 can be used once a	project	is configured and 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-2017 Kitware, Inc. and Contributors

3.8.2				 Jul 02, 2017		       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+11.1-RELEASE+and+Ports>

home | help