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

FreeBSD Manual Pages


home | help

       cmake-language -	CMake Language Reference

       CMake  input  files are written in the "CMake Language" in source files
       named CMakeLists.txt or ending in a .cmake file name extension.

       CMake Language source files in a	project	are organized into:

       o Directories (CMakeLists.txt),

       o Scripts (<script>.cmake), and

       o Modules (<module>.cmake).

       When CMake processes a project source tree, the entry point is a	source
       file  called  CMakeLists.txt  in	 the top-level source directory.  This
       file may	contain	the entire build specification or use  the  add_subdi-
       rectory()  command  to add subdirectories to the	build.	Each subdirec-
       tory added by the command must also contain a  CMakeLists.txt  file  as
       the  entry  point  to  that directory.  For each	source directory whose
       CMakeLists.txt file is processed	CMake generates	a corresponding	direc-
       tory  in	the build tree to act as the default working and output	direc-

       An individual <script>.cmake source file	may  be	 processed  in	script
       mode  by	 using	the  cmake(1)  command-line  tool  with	the -P option.
       Script mode simply runs the commands in the given CMake Language	source
       file  and  does	not  generate a	build system.  It does not allow CMake
       commands	that define build targets or actions.

       CMake Language code in either Directories or Scripts may	 use  the  in-
       clude()	command	 to  load a <module>.cmake source file in the scope of
       the including context.  See the cmake-modules(7)	manual page for	 docu-
       mentation  of  modules  included	 with the CMake	distribution.  Project
       source trees may	also provide their own modules and specify their loca-
       tion(s) in the CMAKE_MODULE_PATH	variable.

       A  CMake	 Language  source  file	may be written in 7-bit	ASCII text for
       maximum portability across all supported	platforms.   Newlines  may  be
       encoded as either \n or \r\n but	will be	converted to \n	as input files
       are read.

       Note that the implementation is 8-bit clean so source files may be  en-
       coded  as UTF-8 on platforms with system	APIs supporting	this encoding.
       In addition, CMake 3.2 and above	support	source files encoded in	 UTF-8
       on  Windows (using UTF-16 to call system	APIs).	Furthermore, CMake 3.0
       and above allow a leading UTF-8 Byte-Order Mark in source files.

   Source Files
       A CMake Language	source file consists of	zero or	more  Command  Invoca-
       tions separated by newlines and optionally spaces and Comments:

       file	    ::=	 file_element*
       file_element ::=	 command_invocation line_ending	|
			 (bracket_comment|space)* line_ending
       line_ending  ::=	 line_comment? newline
       space	    ::=	 <match	'[ \t]+'>
       newline	    ::=	 <match	'\n'>

       Note  that  any	source	file  line  not	 inside	Command	Arguments or a
       Bracket Comment can end in a Line Comment.

   Command Invocations
       A command invocation is a name  followed	 by  paren-enclosed  arguments
       separated by whitespace:

       command_invocation  ::=	space* identifier space* '(' arguments ')'
       identifier	   ::=	<match '[A-Za-z_][A-Za-z0-9_]*'>
       arguments	   ::=	argument? separated_arguments*
       separated_arguments ::=	separation+ argument? |
				separation* '('	arguments ')'
       separation	   ::=	space |	line_ending

       For example:

	  add_executable(hello world.c)

       Command names are case-insensitive.  Nested unquoted parentheses	in the
       arguments must balance.	Each ( or ) is given to	the command invocation
       as  a literal Unquoted Argument.	 This may be used in calls to the if()
       command to enclose conditions.  For example:

	  if(FALSE AND (FALSE OR TRUE))	# evaluates to FALSE

	  CMake	versions prior to 3.0 require command name identifiers	to  be
	  at least 2 characters.

	  CMake	 versions prior	to 2.8.12 silently accept an Unquoted Argument
	  or a Quoted Argument immediately following a Quoted Argument and not
	  separated  by	 any  whitespace.  For compatibility, CMake 2.8.12 and
	  higher accept	such code but produce a	warning.

   Command Arguments
       There are three types of	arguments within Command Invocations:

       argument	::=  bracket_argument |	quoted_argument	| unquoted_argument

   Bracket Argument
       A bracket argument, inspired by Lua long	bracket	syntax,	encloses  con-
       tent between opening and	closing	"brackets" of the same length:

       bracket_argument	::=  bracket_open bracket_content bracket_close
       bracket_open	::=  '[' '='* '['
       bracket_content	::=  <any text not containing a	bracket_close with
			      the same number of '=' as	the bracket_open>
       bracket_close	::=  ']' '='* ']'

       An  opening bracket is written [	followed by zero or more = followed by
       [.  The corresponding closing bracket is	written	] followed by the same
       number  of = followed by	].  Brackets do	not nest.  A unique length may
       always be chosen	for the	opening	and closing brackets to	contain	 clos-
       ing brackets of other lengths.

       Bracket	argument  content consists of all text between the opening and
       closing brackets, except	that one  newline  immediately	following  the
       opening	bracket,  if  any,  is ignored.	 No evaluation of the enclosed
       content,	such as	Escape Sequences or Variable References, is performed.
       A bracket argument is always given to the command invocation as exactly
       one argument.

       For example:

	  This is the first line in a bracket argument with bracket length 1.
	  No \-escape sequences	or ${variable} references are evaluated.
	  This is always one argument even though it contains a	; character.
	  The text does	not end	on a closing bracket of	length 0 like ]].
	  It does end in a closing bracket of length 1.

	  CMake	versions prior to 3.0 do not support bracket arguments.	  They
	  interpret the	opening	bracket	as the start of	an Unquoted Argument.

   Quoted Argument
       A  quoted  argument  encloses  content between opening and closing dou-
       ble-quote characters:

       quoted_argument	   ::=	'"' quoted_element* '"'
       quoted_element	   ::=	<any character except '\' or '"'> |
				escape_sequence	|
       quoted_continuation ::=	'\' newline

       Quoted argument content consists	of all text between opening and	 clos-
       ing  quotes.   Both Escape Sequences and	Variable References are	evalu-
       ated.  A	quoted argument	is always given	to the command	invocation  as
       exactly one argument.

       For example:

	  message("This	is a quoted argument containing	multiple lines.
	  This is always one argument even though it contains a	; character.
	  Both \\-escape sequences and ${variable} references are evaluated.
	  The text does	not end	on an escaped double-quote like	\".
	  It does end in an unescaped double quote.

       The  final  \  on  any  line  ending in an odd number of	backslashes is
       treated as a line continuation and ignored along	with  the  immediately
       following newline character.  For example:

	  This is the first line of a quoted argument. \
	  In fact it is	the only line but since	it is long \
	  the source code uses line continuation.\

	  CMake	 versions  prior  to  3.0  do not support continuation with \.
	  They report errors in	quoted arguments containing lines ending in an
	  odd number of	\ characters.

   Unquoted Argument
       An unquoted argument is not enclosed by any quoting syntax.  It may not
       contain any whitespace, (, ), #,	", or \	except when escaped by a back-

       unquoted_argument ::=  unquoted_element+	| unquoted_legacy
       unquoted_element	 ::=  <any character except whitespace or one of '()#"\'> |
       unquoted_legacy	 ::=  <see note	in text>

       Unquoted	argument content consists of all text in a contiguous block of
       allowed or escaped characters.  Both Escape Sequences and Variable Ref-
       erences	are evaluated.	The resulting value is divided in the same way
       Lists divide into elements.  Each non-empty element  is	given  to  the
       command	invocation as an argument.  Therefore an unquoted argument may
       be given	to a command invocation	as zero	or more	arguments.

       For example:

	      Escaped\ Space

	  To support legacy CMake code,	unquoted arguments  may	 also  contain
	  double-quoted	 strings  ("...", possibly enclosing horizontal	white-
	  space), and make-style variable references ($(MAKEVAR)).

	  Unescaped double-quotes must balance,	may not	appear at  the	begin-
	  ning	of  an	unquoted argument, and are treated as part of the con-
	  tent.	 For example, the unquoted arguments -Da="b c",	-Da=$(v),  and
	  a" "b"c"d are	each interpreted literally.  They may instead be writ-
	  ten  as  quoted  arguments  "-Da=\"b	c\"",  "-Da=$(v)",  and	  "a\"
	  \"b\"c\"d", respectively.

	  Make-style  references  are treated literally	as part	of the content
	  and do not undergo variable expansion.  They are treated as part  of
	  a  single argument (rather than as separate $, (, MAKEVAR, and ) ar-

	  The above "unquoted_legacy" production  represents  such  arguments.
	  We  do  not  recommend  using	legacy unquoted	arguments in new code.
	  Instead use a	Quoted Argument	or a Bracket Argument to represent the

   Escape Sequences
       An escape sequence is a \ followed by one character:

       escape_sequence	::=  escape_identity | escape_encoded |	escape_semicolon
       escape_identity	::=  '\' <match	'[^A-Za-z0-9;]'>
       escape_encoded	::=  '\t' | '\r' | '\n'
       escape_semicolon	::=  '\;'

       A \ followed by a non-alphanumeric character simply encodes the literal
       character without interpreting it as syntax.  A \t, \r, or \n encodes a
       tab,  carriage return, or newline character, respectively. A \; outside
       of any Variable References  encodes  itself  but	 may  be  used	in  an
       Unquoted	 Argument  to encode the ; without dividing the	argument value
       on it.  A \; inside Variable References encodes the literal  ;  charac-
       ter.   (See also	policy CMP0053 documentation for historical considera-

   Variable References
       A variable reference has	the form ${<variable>} and is evaluated	inside
       a Quoted	Argument or an Unquoted	Argument.  A variable reference	is re-
       placed by the value of the variable, or by  the	empty  string  if  the
       variable	 is  not  set.	Variable references can	nest and are evaluated
       from the	inside out, e.g. ${outer_${inner_variable}_variable}.

       Literal variable	references may consist of alphanumeric characters, the
       characters  /_.+-, and Escape Sequences.	 Nested	references may be used
       to evaluate variables of	any name.  See also policy CMP0053  documenta-
       tion  for historical considerations and reasons why the $ is also tech-
       nically permitted but is	discouraged.

       The Variables section documents the scope of  variable  names  and  how
       their values are	set.

       An  environment	variable reference has the form	$ENV{<variable>}.  See
       the Environment Variables section for more information.

       A cache variable	reference has the form $CACHE{<variable>}.  See	 CACHE
       for more	information.

       The  if()  command has a	special	condition syntax that allows for vari-
       able references in the short form <variable> instead of	${<variable>}.
       However,	 environment  and cache	variables always need to be referenced
       as $ENV{<variable>} or $CACHE{<variable>}.

       A comment starts	with a # character that	is not inside a	Bracket	 Argu-
       ment,  Quoted  Argument,	or escaped with	\ as part of an	Unquoted Argu-
       ment.  There are	two types of comments: a Bracket Comment  and  a  Line

   Bracket Comment
       A # immediately followed	by a bracket_open forms	a bracket comment con-
       sisting of the entire bracket enclosure:

       bracket_comment ::=  '#'	bracket_argument

       For example:

	  #[[This is a bracket comment.
	  It runs until	the close bracket.]]
	  message("First Argument\n" #[[Bracket	Comment]] "Second Argument")

	  CMake	versions prior to 3.0 do not support bracket  comments.	  They
	  interpret the	opening	# as the start of a Line Comment.

   Line	Comment
       A  #  not  immediately  followed	by a bracket_open forms	a line comment
       that runs until the end of the line:

       line_comment ::=	 '#' <any text not starting in a bracket_open
			      and not containing a newline>

       For example:

	  # This is a line comment.
	  message("First Argument\n" # This is a line comment :)
		  "Second Argument") # This is a line comment.

   Conditional Blocks
       The if()/elseif()/else()/endif()	commands delimit code blocks to	be ex-
       ecuted conditionally.

       The foreach()/endforeach() and while()/endwhile() commands delimit code
       blocks to be executed in	a loop.	 Inside	such blocks the	 break()  com-
       mand  may  be  used  to terminate the loop early	whereas	the continue()
       command may be used to start with the next iteration immediately.

   Command Definitions
       The macro()/endmacro(), and function()/endfunction()  commands  delimit
       code blocks to be recorded for later invocation as commands.

       Variables  are  the basic unit of storage in the	CMake Language.	 Their
       values are always of string type, though	some  commands	may  interpret
       the  strings  as	values of other	types.	The set() and unset() commands
       explicitly set or unset a variable, but other commands  have  semantics
       that  modify  variables as well.	 Variable names	are case-sensitive and
       may consist of almost any text, but we recommend	sticking to names con-
       sisting only of alphanumeric characters plus _ and -.

       Variables have dynamic scope.  Each variable "set" or "unset" creates a
       binding in the current scope:

       Function	Scope
	      Command Definitions created by  the  function()  command	create
	      commands	that, when invoked, process the	recorded commands in a
	      new variable binding scope.  A variable "set" or	"unset"	 binds
	      in  this	scope  and is visible for the current function and any
	      nested calls within it, but not after the	function returns.

       Directory Scope
	      Each of the Directories in a source tree has  its	 own  variable
	      bindings.	  Before  processing the CMakeLists.txt	file for a di-
	      rectory, CMake copies all	variable bindings currently defined in
	      the  parent  directory,  if any, to initialize the new directory
	      scope.  CMake Scripts, when processed with cmake -P, bind	 vari-
	      ables in one "directory" scope.

	      A	 variable "set"	or "unset" not inside a	function call binds to
	      the current directory scope.

       Persistent Cache
	      CMake stores a separate set of "cache" variables,	or "cache  en-
	      tries",  whose  values  persist  across  multiple	 runs within a
	      project build tree.  Cache  entries  have	 an  isolated  binding
	      scope  modified  only  by	explicit request, such as by the CACHE
	      option of	the set() and unset() commands.

       When evaluating Variable	References, CMake first	searches the  function
       call stack, if any, for a binding and then falls	back to	the binding in
       the current directory scope, if any.  If	a "set"	binding	is found,  its
       value is	used.  If an "unset" binding is	found, or no binding is	found,
       CMake then searches for a cache entry.  If a cache entry	is found,  its
       value is	used.  Otherwise, the variable reference evaluates to an empty
       string.	The $CACHE{VAR}	syntax can be used to do  direct  cache	 entry

       The  cmake-variables(7)	manual	documents  the many variables that are
       provided	by CMake or have meaning to CMake when set by project code.

	  CMake	reserves identifiers that:

	  o begin with CMAKE_ (upper-, lower-, or mixed-case), or

	  o begin with _CMAKE_ (upper-,	lower-,	or mixed-case),	or

	  o begin with _ followed by the name of any CMake Command.

       Environment Variables are like ordinary Variables, with	the  following

       Scope  Environment  variables  have  global  scope  in a	CMake process.
	      They are never cached.

	      Variable References have the form	$ENV{<variable>}.

	      Initial values of	the CMake environment variables	are  those  of
	      the  calling process.  Values can	be changed using the set() and
	      unset() commands.	 These commands	only affect the	running	 CMake
	      process,	not  the  system environment at	large.	Changed	values
	      are not written back to the calling process, and	they  are  not
	      seen by subsequent build or test processes.

       The  cmake-env-variables(7) manual documents environment	variables that
       have special meaning to CMake.

       Although	all values in CMake are	stored as strings,  a  string  may  be
       treated	as a list in certain contexts, such as during evaluation of an
       Unquoted	Argument.  In such contexts, a string is divided into list el-
       ements  by splitting on ; characters not	following an unequal number of
       [ and ] characters and not immediately preceded by a \.	 The  sequence
       \;  does	 not divide a value but	is replaced by ; in the	resulting ele-

       A list of elements is represented as a string by	concatenating the ele-
       ments  separated	 by ;.	For example, the set() command stores multiple
       values into the destination variable as a list:

	  set(srcs a.c b.c c.c)	# sets "srcs" to "a.c;b.c;c.c"

       Lists are meant for simple use cases such as a list of source files and
       should  not  be	used for complex data processing tasks.	 Most commands
       that construct lists do not escape ; characters in list elements,  thus
       flattening nested lists:

	  set(x	a "b;c") # sets	"x" to "a;b;c",	not "a;b\;c"

       2000-2021 Kitware, Inc. and Contributors

3.21.3				 Nov 04, 2021		     CMAKE-LANGUAGE(7)


Want to link to this manual page? Use this URL:

home | help