Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

cmake-language (7)

Name

cmake-language - CMake Language Reference

Synopsis

Please see following description for synopsis

Description

CMAKE-LANGUAGE(7)                    CMake                   CMAKE-LANGUAGE(7)



NAME
       cmake-language - CMake Language Reference

ORGANIZATION
       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).

   Directories
       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-
       tory.

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

   Modules
       CMake Language code in  either  Directories  or  Scripts  may  use  the
       include()  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.

SYNTAX
   Encoding
       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
       encoded  as  UTF-8 on platforms with system APIs supporting this encod-
       ing.  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

       NOTE:
          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:

          message([=[
          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.
          ]=])

       NOTE:
          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
       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:

          message("\
          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.\
          ")

       NOTE:
          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-
       slash:

       unquoted_argument ::=  unquoted_element+ | unquoted_legacy
       unquoted_element  ::=  <any character except whitespace or one of '()#"\'> |
                              escape_sequence
       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:

          foreach(arg
              NoSpace
              Escaped\ Space
              This;Divides;Into;Five;Arguments
              Escaped\;Semicolon
              )
            message("${arg}")
          endforeach()

       NOTE:
          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  )
          arguments).

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

   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-
       tions.)

   Variable References
       A variable reference has the form ${<variable>} and is evaluated inside
       a Quoted Argument or an Unquoted Argument.   A  variable  reference  is
       replaced  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>}.

   Comments
       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
       Comment.

   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")

       NOTE:
          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.

CONTROL STRUCTURES
   Conditional Blocks
       The  if()/elseif()/else()/endif()  commands  delimit  code blocks to be
       executed conditionally.

   Loops
       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
       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
              directory,  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
              entries", 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
       lookups.

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

       NOTE:
          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
       Environment  Variables  are like ordinary Variables, with the following
       differences:

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

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

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

LISTS
       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
       elements 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 result-
       ing element.

       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"

COPYRIGHT
       2000-2021 Kitware, Inc. and Contributors



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+-----------------------+
       |ATTRIBUTE TYPE |   ATTRIBUTE VALUE     |
       +---------------+-----------------------+
       |Availability   | developer/build/cmake |
       +---------------+-----------------------+
       |Stability      | Uncommitted           |
       +---------------+-----------------------+

NOTES
       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source                was                downloaded                from
       http://www.cmake.org/files/v3.21/cmake-3.21.0.tar.gz.

       Further information about this software can be found on the open source
       community website at http://www.cmake.org/.



3.21.0                           Dec 22, 2021                CMAKE-LANGUAGE(7)