|
|
| Line 1: |
Line 1: |
| <pre>
| | See https://cmake.org/cmake/help/ctest2.6docs.html |
| ctest version 2.6-patch 1
| |
| ------------------------------------------------------------------------------
| |
| Name
| |
| | |
| ctest - Testing driver provided by CMake.
| |
| | |
| ------------------------------------------------------------------------------
| |
| Usage
| |
| | |
| ctest [options]
| |
| | |
| ------------------------------------------------------------------------------
| |
| Description
| |
| | |
| The "ctest" executable is the CMake test driver program. CMake-generated
| |
| build trees created for projects that use the ENABLE_TESTING and ADD_TEST
| |
| commands have testing support. This program will run the tests and report
| |
| results.
| |
| | |
| ------------------------------------------------------------------------------
| |
| Options
| |
| | |
| -C <cfg>, --build-config <cfg>
| |
| Choose configuration to test.
| |
| | |
| Some CMake-generated build trees can have multiple build
| |
| configurations in the same tree. This option can be used to specify
| |
| which one should be tested. Example configurations are "Debug" and
| |
| "Release".
| |
| | |
| -V,--verbose
| |
| Enable verbose output from tests.
| |
| | |
| Test output is normally suppressed and only summary information is
| |
| displayed. This option will show all test output.
| |
| | |
| -VV,--extra-verbose
| |
| Enable more verbose output from tests.
| |
| | |
| Test output is normally suppressed and only summary information is
| |
| displayed. This option will show even more test output.
| |
| | |
| --debug
| |
| Displaying more verbose internals of CTest.
| |
| | |
| This feature will result in large number of output that is mostly
| |
| useful for debugging dashboard problems.
| |
| | |
| -Q,--quiet
| |
| Make ctest quiet.
| |
| | |
| This option will suppress all the output. The output log file will
| |
| still be generated if the --output-log is specified. Options such as
| |
| --verbose, --extra-verbose, and --debug are ignored if --quiet is
| |
| specified.
| |
| | |
| -O <file>, --output-log <file>
| |
| Output to log file
| |
| | |
| This option tells ctest to write all its output to a log file.
| |
| | |
| -N,--show-only
| |
| Disable actual execution of tests.
| |
| | |
| This option tells ctest to list the tests that would be run but not
| |
| actually run them. Useful in conjunction with the -R and -E options.
| |
| | |
| -R <regex>, --tests-regex <regex>
| |
| Run tests matching regular expression.
| |
| | |
| This option tells ctest to run only the tests whose names match the
| |
| given regular expression.
| |
| | |
| -E <regex>, --exclude-regex <regex>
| |
| Exclude tests matching regular expression.
| |
| | |
| This option tells ctest to NOT run the tests whose names match the
| |
| given regular expression.
| |
| | |
| -D <dashboard>, --dashboard <dashboard>
| |
| Execute dashboard test
| |
| | |
| This option tells ctest to perform act as a Dart client and perform a
| |
| dashboard test. All tests are <Mode><Test>, where Mode can be
| |
| Experimental, Nightly, and Continuous, and Test can be Start, Update,
| |
| Configure, Build, Test, Coverage, and Submit.
| |
| | |
| -M <model>, --test-model <model>
| |
| Sets the model for a dashboard
| |
| | |
| This option tells ctest to act as a Dart client where the TestModel
| |
| can be Experimental, Nightly, and Continuous. Combining -M and -T is
| |
| similar to -D
| |
| | |
| -T <action>, --test-action <action>
| |
| Sets the dashboard action to perform
| |
| | |
| This option tells ctest to act as a Dart client and perform some
| |
| action such as start, build, test etc. Combining -M and -T is similar
| |
| to -D
| |
| | |
| --track <track>
| |
| Specify the track to submit dashboard to
| |
| | |
| Submit dashboard to specified track instead of default one. By
| |
| default, the dashboard is submitted to Nightly, Experimental, or
| |
| Continuous track, but by specifying this option, the track can be
| |
| arbitrary.
| |
| | |
| -S <script>, --script <script>
| |
| Execute a dashboard for a configuration
| |
| | |
| This option tells ctest to load in a configuration script which sets a
| |
| number of parameters such as the binary and source directories. Then
| |
| ctest will do what is required to create and run a dashboard. This
| |
| option basically sets up a dashboard and then runs ctest -D with the
| |
| appropriate options.
| |
| | |
| -SP <script>, --script-new-process <script>
| |
| Execute a dashboard for a configuration
| |
| | |
| This option does the same operations as -S but it will do them in a
| |
| seperate process. This is primarily useful in cases where the script
| |
| may modify the environment and you do not want the modified enviroment
| |
| to impact other -S scripts.
| |
| | |
| -A <file>, --add-notes <file>
| |
| Add a notes file with submission
| |
| | |
| This option tells ctest to include a notes file when submitting
| |
| dashboard.
| |
| | |
| -I [Start,End,Stride,test#,test#|Test file], --tests-information
| |
| Run a specific number of tests by number.
| |
| | |
| This option causes ctest to run tests starting at number Start, ending
| |
| at number End, and incrementing by Stride. Any additional numbers
| |
| after Stride are considered individual test numbers. Start, End,or
| |
| stride can be empty. Optionally a file can be given that contains the
| |
| same syntax as the command line.
| |
| | |
| -U, --union
| |
| Take the Union of -I and -R
| |
| | |
| When both -R and -I are specified by default the intersection of tests
| |
| are run. By specifying -U the union of tests is run instead.
| |
| | |
| --interactive-debug-mode [0|1]
| |
| Set the interactive mode to 0 or 1.
| |
| | |
| This option causes ctest to run tests in either an interactive mode or
| |
| a non-interactive mode. On Windows this means that in non-interactive
| |
| mode, all system debug pop up windows are blocked. In dashboard mode
| |
| (Experimental, Nightly, Continuous), the default is non-interactive.
| |
| When just running tests not for a dashboard the default is to allow
| |
| popups and interactive debugging.
| |
| | |
| --build-and-test
| |
| Configure, build and run a test.
| |
| | |
| This option tells ctest to configure (i.e. run cmake on), build, and
| |
| or execute a test. The configure and test steps are optional. The
| |
| arguments to this command line are the source and binary directories.
| |
| By default this will run CMake on the Source/Bin directories specified
| |
| unless --build-nocmake is specified. Both --build-makeprogram and
| |
| --build-generator MUST be provided to use --built-and-test. If
| |
| --test-command is specified then that will be run after the build is
| |
| complete. Other options that affect this mode are --build-target
| |
| --build-nocmake, --build-run-dir, --build-two-config, --build-exe-dir,
| |
| --build-project,--build-noclean, --build-options
| |
| | |
| --build-target
| |
| Specify a specific target to build.
| |
| | |
| This option goes with the --build-and-test option, if left out the all
| |
| target is built.
| |
| | |
| --build-nocmake
| |
| Run the build without running cmake first.
| |
| | |
| Skip the cmake step.
| |
| | |
| --build-run-dir
| |
| Specify directory to run programs from.
| |
| | |
| Directory where programs will be after it has been compiled.
| |
| | |
| --build-two-config
| |
| Run CMake twice
| |
| | |
| --build-exe-dir
| |
| Specify the directory for the executable.
| |
| | |
| --build-generator
| |
| Specify the generator to use.
| |
| | |
| --build-project
| |
| Specify the name of the project to build.
| |
| | |
| --build-makeprogram
| |
| Specify the make program to use.
| |
| | |
| --build-noclean
| |
| Skip the make clean step.
| |
| | |
| --build-config-sample
| |
| A sample executable to use to determine the configuraiton
| |
| | |
| A sample executable to use to determine the configuraiton that should
| |
| be used. e.g. Debug/Release/etc
| |
| | |
| --build-options
| |
| Add extra options to the build step.
| |
| | |
| This option must be the last option with the exception of
| |
| --test-command
| |
| | |
| --test-command
| |
| The test to run with the --build-and-test option.
| |
| | |
| --test-timeout
| |
| The time limit in seconds, internal use only.
| |
| | |
| --tomorrow-tag
| |
| Nightly or experimental starts with next day tag.
| |
| | |
| This is useful if the build will not finish in one day.
| |
| | |
| --ctest-config
| |
| The configuration file used to initialize CTest state when submitting
| |
| dashboards.
| |
| | |
| This option tells CTest to use different initialization file instead
| |
| of CTestConfiguration.tcl. This way multiple initialization files can
| |
| be used for example to submit to multiple dashboards.
| |
| | |
| --overwrite
| |
| Overwrite CTest configuration option.
| |
| | |
| By default ctest uses configuration options from configuration file.
| |
| This option will overwrite the configuration option.
| |
| | |
| --extra-submit <file>[;<file>]
| |
| Submit extra files to the dashboard.
| |
| | |
| This option will submit extra files to the dashboard.
| |
| | |
| --force-new-ctest-process
| |
| Run child CTest instances as new processes
| |
| | |
| By default CTest will run child CTest instances within the same
| |
| process. If this behavior is not desired, this argument will enforce
| |
| new processes for child CTest processes.
| |
| | |
| --submit-index
| |
| Submit individual dashboard tests with specific index
| |
| | |
| This option allows performing the same CTest action (such as test)
| |
| multiple times and submit all stages to the same dashboard (Dart2
| |
| required). Each execution requires different index.
| |
| | |
| ------------------------------------------------------------------------------
| |
| Generators
| |
| | |
| The following generators are available on this platform:
| |
| | |
| ------------------------------------------------------------------------------
| |
| Commands
| |
| | |
| break
| |
| Break from an enclosing foreach or while loop.
| |
| | |
| break()
| |
| | |
| Breaks from an enclosing foreach loop or while loop
| |
| | |
| build_name
| |
| Deprecated. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
| |
| | |
| build_name(variable)
| |
| | |
| Sets the specified variable to a string representing the platform and
| |
| compiler settings. These values are now available through the
| |
| CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
| |
| | |
| cmake_minimum_required
| |
| Set the minimum required version of cmake for a project.
| |
| | |
| cmake_minimum_required(VERSION major[.minor[.patch]]
| |
| [FATAL_ERROR])
| |
| | |
| If the current version of CMake is lower than that required it will
| |
| stop processing the project and report an error. When a version
| |
| higher than 2.4 is specified the command implicitly invokes
| |
| | |
| cmake_policy(VERSION major[.minor[.patch]])
| |
| | |
| which sets the cmake policy version level to the version specified.
| |
| When version 2.4 or lower is given the command implicitly invokes
| |
| | |
| cmake_policy(VERSION 2.4)
| |
| | |
| which enables compatibility features for CMake 2.4 and lower.
| |
| | |
| The FATAL_ERROR option is accepted but ignored. It is left from CMake
| |
| versions 2.4 and lower in which failure to meet the minimum version
| |
| was a warning by default.
| |
| | |
| cmake_policy
| |
| Manage CMake Policy settings.
| |
| | |
| As CMake evolves it is sometimes necessary to change existing behavior
| |
| in order to fix bugs or improve implementations of existing features.
| |
| The CMake Policy mechanism is designed to help keep existing projects
| |
| building as new versions of CMake introduce changes in behavior. Each
| |
| new policy (behavioral change) is given an identifier of the form
| |
| "CMP<NNNN>" where "<NNNN>" is an integer index. Documentation
| |
| associated with each policy describes the OLD and NEW behavior and the
| |
| reason the policy was introduced. Projects may set each policy to
| |
| select the desired behavior. When CMake needs to know which behavior
| |
| to use it checks for a setting specified by the project. If no
| |
| setting is available the OLD behavior is assumed and a warning is
| |
| produced requesting that the policy be set.
| |
| | |
| The cmake_policy command is used to set policies to OLD or NEW
| |
| behavior. While setting policies individually is supported, we
| |
| encourage projects to set policies based on CMake versions.
| |
| | |
| cmake_policy(VERSION major.minor[.patch])
| |
| | |
| Specify that the current CMake list file is written for the given
| |
| version of CMake. All policies introduced in the specified version or
| |
| earlier will be set to use NEW behavior. All policies introduced
| |
| after the specified version will be reset to use OLD behavior with a
| |
| warning. This effectively requests behavior preferred as of a given
| |
| CMake version and tells newer CMake versions to warn about their new
| |
| policies. The policy version specified must be at least 2.4 or the
| |
| command will report an error. In order to get compatibility features
| |
| supporting versions earlier than 2.4 see documentation of policy
| |
| CMP0001.
| |
| | |
| cmake_policy(SET CMP<NNNN> NEW)
| |
| cmake_policy(SET CMP<NNNN> OLD)
| |
| | |
| Tell CMake to use the OLD or NEW behavior for a given policy.
| |
| Projects depending on the old behavior of a given policy may silence a
| |
| policy warning by setting the policy state to OLD. Alternatively one
| |
| may fix the project to work with the new behavior and set the policy
| |
| state to NEW.
| |
| | |
| cmake_policy(PUSH)
| |
| cmake_policy(POP)
| |
| | |
| Push and pop the current policy setting state on a stack. Each PUSH
| |
| must have a matching POP. This is useful when mixing multiple
| |
| projects, subprojects, and files included from external projects that
| |
| may each have been written for a different version of CMake. Each
| |
| subdirectory entered by the project automatically pushes a new level
| |
| on the stack to isolate the subdirectories from their parents.
| |
| | |
| configure_file
| |
| Copy a file to another location and modify its contents.
| |
| | |
| configure_file(InputFile OutputFile
| |
| [COPYONLY] [ESCAPE_QUOTES] [@ONLY])
| |
| | |
| The Input and Output files have to have full paths. This command
| |
| replaces any variables in the input file referenced as ${VAR} or @VAR@
| |
| with their values as determined by CMake. If a variable is not
| |
| defined, it will be replaced with nothing. If COPYONLY is specified,
| |
| then no variable expansion will take place. If ESCAPE_QUOTES is
| |
| specified then any substituted quotes will be C-style escaped. The
| |
| file will be configured with the current values of CMake variables.
| |
| If @ONLY is specified, only variables of the form @VAR@ will be
| |
| replaces and ${VAR} will be ignored. This is useful for configuring
| |
| scripts that use ${VAR}. Any occurrences of #cmakedefine VAR will be
| |
| replaced with either #define VAR or /* #undef VAR */ depending on the
| |
| setting of VAR in CMake
| |
| | |
| ctest_build
| |
| Builds the repository.
| |
| | |
| ctest_build([BUILD build_dir] [RETURN_VALUE res])
| |
| | |
| Builds the given build directory and stores results in Build.xml.
| |
| | |
| ctest_configure
| |
| Configures the repository.
| |
| | |
| ctest_configure(BUILD build_dir RETURN_VALUE res)
| |
| | |
| Configures the given build directory and stores results in
| |
| Configure.xml. The second argument is a variable that will hold
| |
| return value.
| |
| | |
| ctest_coverage
| |
| Tests the repository.
| |
| | |
| ctest_coverage([BUILD build_dir] [RETURN_VALUE res])
| |
| | |
| Perform the coverage of the given build directory and stores results
| |
| in Coverage.xml. The second argument is a variable that will hold
| |
| value.
| |
| | |
| ctest_empty_binary_directory
| |
| empties the binary directory
| |
| | |
| ctest_empty_binary_directory( directory )
| |
| | |
| Removes a binary directory. This command will perform some checks
| |
| prior to deleting the directory in an attempt to avoid malicious or
| |
| accidental directory deletion.
| |
| | |
| ctest_memcheck
| |
| Tests the repository.
| |
| | |
| ctest_memcheck([BUILD build_dir] [RETURN_VALUE res])
| |
| | |
| Performs a memory checking of tests in the given build directory and
| |
| stores results in MemCheck.xml. The second argument is a variable
| |
| that will hold value.
| |
| | |
| ctest_read_custom_files
| |
| read CTestCustom files.
| |
| | |
| ctest_read_custom_files( directory ... )
| |
| | |
| Read all the CTestCustom.ctest or CTestCustom.cmake files from the
| |
| given directory.
| |
| | |
| ctest_run_script
| |
| runs a ctest -S script
| |
| | |
| ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
| |
| script_file_name2 ...)
| |
| | |
| Runs a script or scripts much like if it was run from ctest -S. If no
| |
| argument is provided then the current script is run using the current
| |
| settings of the variables. If NEW_PROCESS is specified then each
| |
| script will be run in a seperate process.
| |
| | |
| ctest_sleep
| |
| sleeps for some amount of time
| |
| | |
| ctest_sleep( seconds )
| |
| ctest_sleep( time1 duration time2 )
| |
| | |
| With one argument it will sleep for a given number of seconds. With
| |
| three arguments it will wait for time2 - time1 - duration seconds.
| |
| | |
| ctest_start
| |
| Starts the testing for a given model
| |
| | |
| ctest_start(Model [TRACK <track>] [source [binary]])
| |
| | |
| Starts the testing for a given model. The command should be called
| |
| after the binary directory is initialized. If the 'source' and
| |
| 'binary' directory are not specified, it reads the
| |
| CTEST_SOURCE_DIRECTORY and CTEST_BINARY_DIRECTORY. If the track is
| |
| specified, the submissions will go to the specified track.
| |
| | |
| ctest_submit
| |
| Submits the repository.
| |
| | |
| ctest_submit([RETURN_VALUE res])
| |
| | |
| Submits the test results for the project.
| |
| | |
| CTEST_TEST
| |
| Tests the repository.
| |
| | |
| CTEST_TEST([BUILD build_dir] [RETURN_VALUE res])
| |
| | |
| Tests the given build directory and stores results in Test.xml. The
| |
| second argument is a variable that will hold value.
| |
| | |
| ctest_update
| |
| Updates the repository.
| |
| | |
| ctest_update([SOURCE source] [RETURN_VALUE res])
| |
| | |
| Updates the given source directory and stores results in Update.xml.
| |
| The second argument is a variable that will hold the number of files
| |
| modified. If there is a problem, the variable will be -1.
| |
| | |
| else
| |
| Starts the else portion of an if block.
| |
| | |
| else(expression)
| |
| | |
| See the if command.
| |
| | |
| elseif
| |
| Starts the elseif portion of an if block.
| |
| | |
| elseif(expression)
| |
| | |
| See the if command.
| |
| | |
| endforeach
| |
| Ends a list of commands in a FOREACH block.
| |
| | |
| endforeach(expression)
| |
| | |
| See the FOREACH command.
| |
| | |
| endfunction
| |
| Ends a list of commands in a function block.
| |
| | |
| endfunction(expression)
| |
| | |
| See the function command.
| |
| | |
| endif
| |
| Ends a list of commands in an if block.
| |
| | |
| endif(expression)
| |
| | |
| See the if command.
| |
| | |
| endmacro
| |
| Ends a list of commands in a macro block.
| |
| | |
| endmacro(expression)
| |
| | |
| See the macro command.
| |
| | |
| endwhile
| |
| Ends a list of commands in a while block.
| |
| | |
| endwhile(expression)
| |
| | |
| See the while command.
| |
| | |
| exec_program
| |
| Deprecated. Use the execute_process() command instead.
| |
| | |
| Run an executable program during the processing of the CMakeList.txt
| |
| file.
| |
| | |
| exec_program(Executable [directory in which to run]
| |
| [ARGS <arguments to executable>]
| |
| [OUTPUT_VARIABLE <var>]
| |
| [RETURN_VALUE <var>])
| |
| | |
| The executable is run in the optionally specified directory. The
| |
| executable can include arguments if it is double quoted, but it is
| |
| better to use the optional ARGS argument to specify arguments to the
| |
| program. This is because cmake will then be able to escape spaces in
| |
| the executable path. An optional argument OUTPUT_VARIABLE specifies a
| |
| variable in which to store the output. To capture the return value of
| |
| the execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is
| |
| specified, then no output will go to the stdout/stderr of the console
| |
| running cmake.
| |
| | |
| | |
| execute_process
| |
| Execute one or more child processes.
| |
| | |
| execute_process(COMMAND <cmd1> [args1...]]
| |
| [COMMAND <cmd2> [args2...] [...]]
| |
| [WORKING_DIRECTORY <directory>]
| |
| [TIMEOUT <seconds>]
| |
| [RESULT_VARIABLE <variable>]
| |
| [OUTPUT_VARIABLE <variable>]
| |
| [ERROR_VARIABLE <variable>]
| |
| [INPUT_FILE <file>]
| |
| [OUTPUT_FILE <file>]
| |
| [ERROR_FILE <file>]
| |
| [OUTPUT_QUIET]
| |
| [ERROR_QUIET]
| |
| [OUTPUT_STRIP_TRAILING_WHITESPACE]
| |
| [ERROR_STRIP_TRAILING_WHITESPACE])
| |
| | |
| Runs the given sequence of one or more commands with the standard
| |
| output of each process piped to the standard input of the next. A
| |
| single standard error pipe is used for all processes. If
| |
| WORKING_DIRECTORY is given the named directory will be set as the
| |
| current working directory of the child processes. If TIMEOUT is given
| |
| the child processes will be terminated if they do not finish in the
| |
| specified number of seconds (fractions are allowed). If
| |
| RESULT_VARIABLE is given the variable will be set to contain the
| |
| result of running the processes. This will be an integer return code
| |
| from the last child or a string describing an error condition. If
| |
| OUTPUT_VARIABLE or ERROR_VARIABLE are given the variable named will be
| |
| set with the contents of the standard output and standard error pipes
| |
| respectively. If the same variable is named for both pipes their
| |
| output will be merged in the order produced. If INPUT_FILE,
| |
| OUTPUT_FILE, or ERROR_FILE is given the file named will be attached to
| |
| the standard input of the first process, standard output of the last
| |
| process, or standard error of all processes respectively. If
| |
| OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
| |
| standard error results will be quietly ignored. If more than one
| |
| OUTPUT_* or ERROR_* option is given for the same pipe the precedence
| |
| is not specified. If no OUTPUT_* or ERROR_* options are given the
| |
| output will be shared with the corresponding pipes of the CMake
| |
| process itself.
| |
| | |
| The execute_process command is a newer more powerful version of
| |
| exec_program, but the old command has been kept for compatibility.
| |
| | |
| file
| |
| File manipulation command.
| |
| | |
| file(WRITE filename "message to write"... )
| |
| file(APPEND filename "message to write"... )
| |
| file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
| |
| file(STRINGS filename variable [LIMIT_COUNT num]
| |
| [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
| |
| [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
| |
| [NEWLINE_CONSUME] [REGEX regex]
| |
| [NO_HEX_CONVERSION])
| |
| file(GLOB variable [RELATIVE path] [globbing expressions]...)
| |
| file(GLOB_RECURSE variable [RELATIVE path]
| |
| [globbing expressions]...)
| |
| file(REMOVE [file1 ...])
| |
| file(REMOVE_RECURSE [file1 ...])
| |
| file(MAKE_DIRECTORY [directory1 directory2 ...])
| |
| file(RELATIVE_PATH variable directory file)
| |
| file(TO_CMAKE_PATH path result)
| |
| file(TO_NATIVE_PATH path result)
| |
| file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log])
| |
| | |
| WRITE will write a message into a file called 'filename'. It
| |
| overwrites the file if it already exists, and creates the file if it
| |
| does not exist.
| |
| | |
| APPEND will write a message into a file same as WRITE, except it will
| |
| append it to the end of the file
| |
| | |
| READ will read the content of a file and store it into the variable.
| |
| It will start at the given offset and read up to numBytes. If the
| |
| argument HEX is given, the binary data will be converted to
| |
| hexadecimal representation and this will be stored in the variable.
| |
| | |
| STRINGS will parse a list of ASCII strings from a file and store it in
| |
| a variable. Binary data in the file are ignored. Carriage return
| |
| (CR) characters are ignored. It works also for Intel Hex and Motorola
| |
| S-record files, which are automatically converted to binary format
| |
| when reading them. Disable this using NO_HEX_CONVERSION.
| |
| | |
| LIMIT_COUNT sets the maximum number of strings to return. LIMIT_INPUT
| |
| sets the maximum number of bytes to read from the input file.
| |
| LIMIT_OUTPUT sets the maximum number of bytes to store in the output
| |
| variable. LENGTH_MINIMUM sets the minimum length of a string to
| |
| return. Shorter strings are ignored. LENGTH_MAXIMUM sets the maximum
| |
| length of a string to return. Longer strings are split into strings
| |
| no longer than the maximum length. NEWLINE_CONSUME allows newlines to
| |
| be included in strings instead of terminating them.
| |
| | |
| REGEX specifies a regular expression that a string must match to be
| |
| returned. Typical usage
| |
| | |
| file(STRINGS myfile.txt myfile)
| |
| | |
| stores a list in the variable "myfile" in which each item is a line
| |
| from the input file.
| |
| | |
| GLOB will generate a list of all files that match the globbing
| |
| expressions and store it into the variable. Globbing expressions are
| |
| similar to regular expressions, but much simpler. If RELATIVE flag is
| |
| specified for an expression, the results will be returned as a
| |
| relative path to the given path.
| |
| | |
| Examples of globbing expressions include:
| |
| | |
| *.cxx - match all files with extension cxx
| |
| *.vt? - match all files with extension vta,...,vtz
| |
| f[3-5].txt - match files f3.txt, f4.txt, f5.txt
| |
| | |
| GLOB_RECURSE will generate similar list as the regular GLOB, except it
| |
| will traverse all the subdirectories of the matched directory and
| |
| match the files.
| |
| | |
| Examples of recursive globbing include:
| |
| | |
| /dir/*.py - match all python files in /dir and subdirectories
| |
| | |
| MAKE_DIRECTORY will create the given directories, also if their parent
| |
| directories don't exist yet
| |
| | |
| REMOVE will remove the given files, also in subdirectories
| |
| | |
| REMOVE_RECURSE will remove the given files and directories, also
| |
| non-empty directories
| |
| | |
| RELATIVE_PATH will determine relative path from directory to the given
| |
| file.
| |
| | |
| TO_CMAKE_PATH will convert path into a cmake style path with unix /.
| |
| The input can be a single path or a system path like "$ENV{PATH}".
| |
| Note the double quotes around the ENV call TO_CMAKE_PATH only takes
| |
| one argument.
| |
| | |
| TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a
| |
| cmake style path into the native path style \ for windows and / for
| |
| UNIX.
| |
| | |
| DOWNLOAD will download the givin URL to the given file. If LOG var is
| |
| specified a log of the download will be put in var. If STATUS var is
| |
| specified the status of the operation will be put in var. The status
| |
| is returned in a list of length 2. The first element is the numeric
| |
| return value for the operation, and the second element is a string
| |
| value for the error. A 0 numeric error means no error in the
| |
| operation. If TIMEOUT time is specified, the operation will timeout
| |
| after time seconds, time can be specified as a float.
| |
| | |
| | |
| find_file
| |
| Find the full path to a file.
| |
| | |
| find_path(<VAR> name1 [path1 path2 ...])
| |
| | |
| This is the short-hand signature for the command that is sufficient in
| |
| many cases. It is the same as find_path(<VAR> name1 [PATHS path1
| |
| path2 ...])
| |
| | |
| find_path(
| |
| <VAR>
| |
| name | NAMES name1 [name2 ...]
| |
| [HINTS path1 [path2 ... ENV var]]
| |
| [PATHS path1 [path2 ... ENV var]]
| |
| [PATH_SUFFIXES suffix1 [suffix2 ...]]
| |
| [DOC "cache documentation string"]
| |
| [NO_DEFAULT_PATH]
| |
| [NO_CMAKE_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_PATH]
| |
| [NO_SYSTEM_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_SYSTEM_PATH]
| |
| [CMAKE_FIND_ROOT_PATH_BOTH |
| |
| ONLY_CMAKE_FIND_ROOT_PATH |
| |
| NO_CMAKE_FIND_ROOT_PATH]
| |
| )
| |
| | |
| This command is used to find a full path to named file. A cache entry
| |
| named by <VAR> is created to store the result of this command. If the
| |
| full path to a file is found the result is stored in the variable and
| |
| the search will not be repeated unless the variable is cleared. If
| |
| nothing is found, the result will be <VAR>-NOTFOUND, and the search
| |
| will be attempted again the next time find_path is invoked with the
| |
| same variable. The name of the full path to a file that is searched
| |
| for is specified by the names listed after the NAMES argument.
| |
| Additional search locations can be specified after the PATHS argument.
| |
| If ENV var is found in the HINTS or PATHS section the environment
| |
| variable var will be read and converted from a system environment
| |
| variable to a cmake style list of paths. For example ENV PATH would
| |
| be a way to list the system path variable. The argument after DOC
| |
| will be used for the documentation string in the cache. PATH_SUFFIXES
| |
| can be used to give sub directories that will be appended to the
| |
| search paths.
| |
| | |
| If NO_DEFAULT_PATH is specified, then no additional paths are added to
| |
| the search. If NO_DEFAULT_PATH is not specified, the search process
| |
| is as follows:
| |
| | |
| 1. Search paths specified in cmake-specific cache variables. These
| |
| are intended to be used on the command line with a -DVAR=value. This
| |
| can be skipped if NO_CMAKE_PATH is passed.
| |
| | |
| <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_INCLUDE_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| | |
| 2. Search paths specified in cmake-specific environment variables.
| |
| These are intended to be set in the user's shell configuration. This
| |
| can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
| |
| | |
| <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_INCLUDE_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| | |
| 3. Search the paths specified by the HINTS option. These should be
| |
| paths computed by system introspection, such as a hint provided by the
| |
| location of another item already found. Hard-coded guesses should be
| |
| specified with the PATHS option.
| |
| | |
| 4. Search the standard system environment variables. This can be
| |
| skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
| |
| | |
| PATH
| |
| INCLUDE
| |
| | |
| 5. Search cmake variables defined in the Platform files for the
| |
| current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
| |
| passed.
| |
| | |
| <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
| |
| CMAKE_SYSTEM_INCLUDE_PATH
| |
| CMAKE_SYSTEM_FRAMEWORK_PATH
| |
| | |
| 6. Search the paths specified by the PATHS option or in the
| |
| short-hand version of the command. These are typically hard-coded
| |
| guesses.
| |
| | |
| On Darwin or systems supporting OS X Frameworks, the cmake variable
| |
| CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
| |
| | |
| "FIRST" - Try to find frameworks before standard
| |
| libraries or headers. This is the default on Darwin.
| |
| "LAST" - Try to find frameworks after standard
| |
| libraries or headers.
| |
| "ONLY" - Only try to find frameworks.
| |
| "NEVER". - Never try to find frameworks.
| |
| | |
| On Darwin or systems supporting OS X Application Bundles, the cmake
| |
| variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
| |
| following:
| |
| | |
| "FIRST" - Try to find application bundles before standard
| |
| programs. This is the default on Darwin.
| |
| "LAST" - Try to find application bundles after standard
| |
| programs.
| |
| "ONLY" - Only try to find application bundles.
| |
| "NEVER". - Never try to find application bundles.
| |
| | |
| The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
| |
| directories to be prepended to all other search directories. This
| |
| effectively "re-roots" the entire search under given locations. By
| |
| default it is empty. It is especially useful when cross-compiling to
| |
| point to the root directory of the target environment and CMake will
| |
| search there too. By default at first the directories listed in
| |
| CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
| |
| searched. The default behavior can be adjusted by setting
| |
| CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually
| |
| overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
| |
| the search order will be as described above. If
| |
| NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
| |
| used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
| |
| directories will be searched.
| |
| | |
| The default search order is designed to be most-specific to
| |
| least-specific for common use cases. Projects may override the order
| |
| by simply calling the command multiple times and using the NO_*
| |
| options:
| |
| | |
| find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
| |
| find_path(<VAR> NAMES name)
| |
| | |
| Once one of the calls succeeds the result variable will be set and
| |
| stored in the cache so that no call will search again.
| |
| | |
| find_library
| |
| Find a library.
| |
| | |
| find_library(<VAR> name1 [path1 path2 ...])
| |
| | |
| This is the short-hand signature for the command that is sufficient in
| |
| many cases. It is the same as find_library(<VAR> name1 [PATHS path1
| |
| path2 ...])
| |
| | |
| find_library(
| |
| <VAR>
| |
| name | NAMES name1 [name2 ...]
| |
| [HINTS path1 [path2 ... ENV var]]
| |
| [PATHS path1 [path2 ... ENV var]]
| |
| [PATH_SUFFIXES suffix1 [suffix2 ...]]
| |
| [DOC "cache documentation string"]
| |
| [NO_DEFAULT_PATH]
| |
| [NO_CMAKE_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_PATH]
| |
| [NO_SYSTEM_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_SYSTEM_PATH]
| |
| [CMAKE_FIND_ROOT_PATH_BOTH |
| |
| ONLY_CMAKE_FIND_ROOT_PATH |
| |
| NO_CMAKE_FIND_ROOT_PATH]
| |
| )
| |
| | |
| This command is used to find a library. A cache entry named by <VAR>
| |
| is created to store the result of this command. If the library is
| |
| found the result is stored in the variable and the search will not be
| |
| repeated unless the variable is cleared. If nothing is found, the
| |
| result will be <VAR>-NOTFOUND, and the search will be attempted again
| |
| the next time find_library is invoked with the same variable. The
| |
| name of the library that is searched for is specified by the names
| |
| listed after the NAMES argument. Additional search locations can be
| |
| specified after the PATHS argument. If ENV var is found in the HINTS
| |
| or PATHS section the environment variable var will be read and
| |
| converted from a system environment variable to a cmake style list of
| |
| paths. For example ENV PATH would be a way to list the system path
| |
| variable. The argument after DOC will be used for the documentation
| |
| string in the cache. PATH_SUFFIXES can be used to give sub
| |
| directories that will be appended to the search paths.
| |
| | |
| If NO_DEFAULT_PATH is specified, then no additional paths are added to
| |
| the search. If NO_DEFAULT_PATH is not specified, the search process
| |
| is as follows:
| |
| | |
| 1. Search paths specified in cmake-specific cache variables. These
| |
| are intended to be used on the command line with a -DVAR=value. This
| |
| can be skipped if NO_CMAKE_PATH is passed.
| |
| | |
| <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_LIBRARY_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| | |
| 2. Search paths specified in cmake-specific environment variables.
| |
| These are intended to be set in the user's shell configuration. This
| |
| can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
| |
| | |
| <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_LIBRARY_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| | |
| 3. Search the paths specified by the HINTS option. These should be
| |
| paths computed by system introspection, such as a hint provided by the
| |
| location of another item already found. Hard-coded guesses should be
| |
| specified with the PATHS option.
| |
| | |
| 4. Search the standard system environment variables. This can be
| |
| skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
| |
| | |
| PATH
| |
| LIB
| |
| | |
| 5. Search cmake variables defined in the Platform files for the
| |
| current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
| |
| passed.
| |
| | |
| <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
| |
| CMAKE_SYSTEM_LIBRARY_PATH
| |
| CMAKE_SYSTEM_FRAMEWORK_PATH
| |
| | |
| 6. Search the paths specified by the PATHS option or in the
| |
| short-hand version of the command. These are typically hard-coded
| |
| guesses.
| |
| | |
| On Darwin or systems supporting OS X Frameworks, the cmake variable
| |
| CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
| |
| | |
| "FIRST" - Try to find frameworks before standard
| |
| libraries or headers. This is the default on Darwin.
| |
| "LAST" - Try to find frameworks after standard
| |
| libraries or headers.
| |
| "ONLY" - Only try to find frameworks.
| |
| "NEVER". - Never try to find frameworks.
| |
| | |
| On Darwin or systems supporting OS X Application Bundles, the cmake
| |
| variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
| |
| following:
| |
| | |
| "FIRST" - Try to find application bundles before standard
| |
| programs. This is the default on Darwin.
| |
| "LAST" - Try to find application bundles after standard
| |
| programs.
| |
| "ONLY" - Only try to find application bundles.
| |
| "NEVER". - Never try to find application bundles.
| |
| | |
| The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
| |
| directories to be prepended to all other search directories. This
| |
| effectively "re-roots" the entire search under given locations. By
| |
| default it is empty. It is especially useful when cross-compiling to
| |
| point to the root directory of the target environment and CMake will
| |
| search there too. By default at first the directories listed in
| |
| CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
| |
| searched. The default behavior can be adjusted by setting
| |
| CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually
| |
| overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
| |
| the search order will be as described above. If
| |
| NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
| |
| used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
| |
| directories will be searched.
| |
| | |
| The default search order is designed to be most-specific to
| |
| least-specific for common use cases. Projects may override the order
| |
| by simply calling the command multiple times and using the NO_*
| |
| options:
| |
| | |
| find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
| |
| find_library(<VAR> NAMES name)
| |
| | |
| Once one of the calls succeeds the result variable will be set and
| |
| stored in the cache so that no call will search again.
| |
| | |
| If the library found is a framework, then VAR will be set to the full
| |
| path to the framework <fullPath>/A.framework. When a full path to a
| |
| framework is used as a library, CMake will use a -framework A, and a
| |
| -F<fullPath> to link the framework to the target.
| |
| | |
| find_package
| |
| Load settings for an external project.
| |
| | |
| find_package(<package> [major[.minor[.patch]]] [EXACT] [QUIET]
| |
| [[REQUIRED|COMPONENTS] [components...]])
| |
| | |
| Finds and loads settings from an external project. <package>_FOUND
| |
| will be set to indicate whether the package was found. When the
| |
| package is found package-specific information is provided through
| |
| variables documented by the package itself. The QUIET option disables
| |
| messages if the package cannot be found. The REQUIRED option stops
| |
| processing with an error message if the package cannot be found. A
| |
| package-specific list of components may be listed after the REQUIRED
| |
| option or after the COMPONENTS option if no REQUIRED option is given.
| |
| The "[major[.minor[.patch]]]" version argument specifies a desired
| |
| version with which the package found should be compatible. The EXACT
| |
| option requests that the version be matched exactly. Version support
| |
| is currently provided only on a package-by-package basis (details
| |
| below).
| |
| | |
| User code should generally look for packages using the above simple
| |
| signature. The remainder of this command documentation specifies the
| |
| full command signature and details of the search process. Project
| |
| maintainers wishing to provide a package to be found by this command
| |
| are encouraged to read on.
| |
| | |
| The command has two modes by which it searches for packages: "Module"
| |
| mode and "Config" mode. Module mode is available when the command is
| |
| invoked with the above reduced signature. CMake searches for a file
| |
| called "Find<package>.cmake" in the CMAKE_MODULE_PATH followed by the
| |
| CMake installation. If the file is found, it is read and processed by
| |
| CMake. It is responsible for finding the package, checking the
| |
| version, and producing any needed messages. Many find-modules provide
| |
| limited or no support for versioning; check the module documentation.
| |
| If no module is found the command proceeds to Config mode.
| |
| | |
| The complete Config mode command signature is:
| |
| | |
| find_package(<package> [major[.minor[.patch]]] [EXACT] [QUIET]
| |
| [[REQUIRED|COMPONENTS] [components...]] [NO_MODULE]
| |
| [NAMES name1 [name2 ...]]
| |
| [CONFIGS config1 [config2 ...]]
| |
| [HINTS path1 [path2 ... ]]
| |
| [PATHS path1 [path2 ... ]]
| |
| [PATH_SUFFIXES suffix1 [suffix2 ...]]
| |
| [NO_DEFAULT_PATH]
| |
| [NO_CMAKE_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_PATH]
| |
| [NO_SYSTEM_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_BUILDS_PATH]
| |
| [NO_CMAKE_SYSTEM_PATH]
| |
| [CMAKE_FIND_ROOT_PATH_BOTH |
| |
| ONLY_CMAKE_FIND_ROOT_PATH |
| |
| NO_CMAKE_FIND_ROOT_PATH])
| |
| | |
| The NO_MODULE option may be used to skip Module mode explicitly. It
| |
| is also implied by use of options not specified in the reduced
| |
| signature.
| |
| | |
| Config mode attempts to locate a configuration file provided by the
| |
| package to be found. A cache entry called <package>_DIR is created to
| |
| hold the directory containing the file. By default the command
| |
| searches for a package with the name <package>. If the NAMES option
| |
| is given the names following it are used instead of <package>. The
| |
| command searches for a file called "<name>Config.cmake" or
| |
| "<lower-case-name>-config.cmake" for each name specified. A
| |
| replacement set of possible configuration file names may be given
| |
| using the CONFIGS option. The search procedure is specified below.
| |
| Once found, the configuration file is read and processed by CMake.
| |
| Since the file is provided by the package it already knows the
| |
| location of package contents. The full path to the configuration file
| |
| is stored in the cmake variable <package>_CONFIG.
| |
| | |
| If the package configuration file cannot be found CMake will generate
| |
| an error describing the problem unless the QUIET argument is
| |
| specified. If REQUIRED is specified and the package is not found a
| |
| fatal error is generated and the configure step stops executing. If
| |
| <package>_DIR has been set to a directory not containing a
| |
| configuration file a fatal error is always generated because user
| |
| intervention is required.
| |
| | |
| When the "[major[.minor[.patch]]]" version argument is specified
| |
| Config mode will only find a version of the package that claims
| |
| compatibility with the requested version. If the EXACT option is
| |
| given only a version of the package claiming an exact match of the
| |
| requested version may be found. CMake does not establish any
| |
| convention for the meaning of version numbers. Package version
| |
| numbers are checked by "version" files provided by the packages
| |
| themselves. For a candidate package confguration file
| |
| "<config-file>.cmake" the corresponding version file is located next
| |
| to it and named either "<config-file>-version.cmake" or
| |
| "<config-file>Version.cmake". If no such version file is available
| |
| then the configuration file is assumed to not be compatible with any
| |
| requested version. When a version file is found it is loaded to check
| |
| the requested version number. The version file is loaded in a nested
| |
| scope in which the following variables have been defined:
| |
| | |
| PACKAGE_FIND_NAME = the <package> name
| |
| PACKAGE_FIND_VERSION = full requested version string
| |
| PACKAGE_FIND_VERSION_MAJOR = requested major version, if any
| |
| PACKAGE_FIND_VERSION_MINOR = requested minor version, if any
| |
| PACKAGE_FIND_VERSION_PATCH = requested patch version, if any
| |
| | |
| The version file checks whether it satisfies the requested version and
| |
| sets these variables:
| |
| | |
| PACKAGE_VERSION = package version (major[.minor[.patch]])
| |
| PACKAGE_VERSION_EXACT = true if version is exact match
| |
| PACKAGE_VERSION_COMPATIBLE = true if version is compatible
| |
| | |
| These variables are checked by the find_package command to determine
| |
| whether the configuration file provides an acceptable version. They
| |
| are not available after the find_package call returns. If the version
| |
| is acceptable the following variables are set:
| |
| | |
| <package>_VERSION = package version (major[.minor[.patch]])
| |
| <package>_VERSION_MAJOR = major from major[.minor[.patch]], if any
| |
| <package>_VERSION_MINOR = minor from major[.minor[.patch]], if any
| |
| <package>_VERSION_PATCH = patch from major[.minor[.patch]], if any
| |
| | |
| and the corresponding package configuration file is loaded. When
| |
| multiple package configuration files are available whose version files
| |
| claim compatibility with the version requested it is unspecified which
| |
| one is chosen. No attempt is made to choose a highest or closest
| |
| version number.
| |
| | |
| Config mode provides an elaborate interface and search procedure.
| |
| Much of the interface is provided for completeness and for use
| |
| internally by find-modules loaded by Module mode. Most user code
| |
| should simply call
| |
| | |
| find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
| |
| | |
| in order to find a package. Package maintainers providing CMake
| |
| package configuration files are encouraged to name and install them
| |
| such that the procedure outlined below will find them without
| |
| requiring use of additional options.
| |
| | |
| CMake constructs a set of possible installation prefixes for the
| |
| package. Under each prefix several directories are searched for a
| |
| configuration file. The tables below show the directories searched.
| |
| Each entry is meant for installation trees following Windows (W), UNIX
| |
| (U), or Apple (A) conventions.
| |
| | |
| <prefix>/ (W)
| |
| <prefix>/(cmake|CMake)/ (W)
| |
| <prefix>/(share|lib)/<name>*/ (U)
| |
| <prefix>/(share|lib)/<name>*/(cmake|CMake)/ (U)
| |
| | |
| On systems supporting OS X Frameworks and Application Bundles the
| |
| following directories are searched for frameworks or bundles
| |
| containing a configuration file:
| |
| | |
| <prefix>/<name>.framework/Resources/ (A)
| |
| <prefix>/<name>.framework/Resources/CMake/ (A)
| |
| <prefix>/<name>.framework/Versions/*/Resources/ (A)
| |
| <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
| |
| <prefix>/<name>.app/Contents/Resources/ (A)
| |
| <prefix>/<name>.app/Contents/Resources/CMake/ (A)
| |
| | |
| In all cases the <name> is treated as case-insensitive and corresponds
| |
| to any of the names specified (<package> or names given by NAMES). If
| |
| PATH_SUFFIXES is specified the suffixes are appended to each (W) or
| |
| (U) directory entry one-by-one.
| |
| | |
| This set of directories is intended to work in cooperation with
| |
| projects that provide configuration files in their installation trees.
| |
| Directories above marked with (W) are intended for installations on
| |
| Windows where the prefix may point at the top of an application's
| |
| installation directory. Those marked with (U) are intended for
| |
| installations on UNIX platforms where the prefix is shared by multiple
| |
| packages. This is merely a convention, so all (W) and (U) directories
| |
| are still searched on all platforms. Directories marked with (A) are
| |
| intended for installations on Apple platforms. The cmake variables
| |
| CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the order of
| |
| preference as specified below.
| |
| | |
| The set of installation prefixes is constructed using the following
| |
| steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
| |
| | |
| 1. Search paths specified in cmake-specific cache variables. These
| |
| are intended to be used on the command line with a -DVAR=value. This
| |
| can be skipped if NO_CMAKE_PATH is passed.
| |
| | |
| CMAKE_PREFIX_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| CMAKE_APPBUNDLE_PATH
| |
| | |
| 2. Search paths specified in cmake-specific environment variables.
| |
| These are intended to be set in the user's shell configuration. This
| |
| can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
| |
| | |
| CMAKE_PREFIX_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| CMAKE_APPBUNDLE_PATH
| |
| | |
| 3. Search paths specified by the HINTS option. These should be paths
| |
| computed by system introspection, such as a hint provided by the
| |
| location of another item already found. Hard-coded guesses should be
| |
| specified with the PATHS option.
| |
| | |
| 4. Search the standard system environment variables. This can be
| |
| skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries ending
| |
| in "/bin" or "/sbin" are automatically converted to their parent
| |
| directories.
| |
| | |
| PATH
| |
| | |
| 5. Search project build trees recently configured in a CMake GUI.
| |
| This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It is intended
| |
| for the case when a user is building multiple dependent projects one
| |
| after another.
| |
| | |
| 6. Search cmake variables defined in the Platform files for the
| |
| current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
| |
| passed.
| |
| | |
| CMAKE_SYSTEM_PREFIX_PATH
| |
| CMAKE_SYSTEM_FRAMEWORK_PATH
| |
| CMAKE_SYSTEM_APPBUNDLE_PATH
| |
| | |
| 7. Search paths specified by the PATHS option. These are typically
| |
| hard-coded guesses.
| |
| | |
| On Darwin or systems supporting OS X Frameworks, the cmake variable
| |
| CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
| |
| | |
| "FIRST" - Try to find frameworks before standard
| |
| libraries or headers. This is the default on Darwin.
| |
| "LAST" - Try to find frameworks after standard
| |
| libraries or headers.
| |
| "ONLY" - Only try to find frameworks.
| |
| "NEVER". - Never try to find frameworks.
| |
| | |
| On Darwin or systems supporting OS X Application Bundles, the cmake
| |
| variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
| |
| following:
| |
| | |
| "FIRST" - Try to find application bundles before standard
| |
| programs. This is the default on Darwin.
| |
| "LAST" - Try to find application bundles after standard
| |
| programs.
| |
| "ONLY" - Only try to find application bundles.
| |
| "NEVER". - Never try to find application bundles.
| |
| | |
| The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
| |
| directories to be prepended to all other search directories. This
| |
| effectively "re-roots" the entire search under given locations. By
| |
| default it is empty. It is especially useful when cross-compiling to
| |
| point to the root directory of the target environment and CMake will
| |
| search there too. By default at first the directories listed in
| |
| CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
| |
| searched. The default behavior can be adjusted by setting
| |
| CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually
| |
| overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
| |
| the search order will be as described above. If
| |
| NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
| |
| used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
| |
| directories will be searched.
| |
| | |
| The default search order is designed to be most-specific to
| |
| least-specific for common use cases. Projects may override the order
| |
| by simply calling the command multiple times and using the NO_*
| |
| options:
| |
| | |
| find_package(<package> PATHS paths... NO_DEFAULT_PATH)
| |
| find_package(<package>)
| |
| | |
| Once one of the calls succeeds the result variable will be set and
| |
| stored in the cache so that no call will search again.
| |
| | |
| find_path
| |
| Find the directory containing a file.
| |
| | |
| find_path(<VAR> name1 [path1 path2 ...])
| |
| | |
| This is the short-hand signature for the command that is sufficient in
| |
| many cases. It is the same as find_path(<VAR> name1 [PATHS path1
| |
| path2 ...])
| |
| | |
| find_path(
| |
| <VAR>
| |
| name | NAMES name1 [name2 ...]
| |
| [HINTS path1 [path2 ... ENV var]]
| |
| [PATHS path1 [path2 ... ENV var]]
| |
| [PATH_SUFFIXES suffix1 [suffix2 ...]]
| |
| [DOC "cache documentation string"]
| |
| [NO_DEFAULT_PATH]
| |
| [NO_CMAKE_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_PATH]
| |
| [NO_SYSTEM_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_SYSTEM_PATH]
| |
| [CMAKE_FIND_ROOT_PATH_BOTH |
| |
| ONLY_CMAKE_FIND_ROOT_PATH |
| |
| NO_CMAKE_FIND_ROOT_PATH]
| |
| )
| |
| | |
| This command is used to find a directory containing the named file. A
| |
| cache entry named by <VAR> is created to store the result of this
| |
| command. If the file in a directory is found the result is stored in
| |
| the variable and the search will not be repeated unless the variable
| |
| is cleared. If nothing is found, the result will be <VAR>-NOTFOUND,
| |
| and the search will be attempted again the next time find_path is
| |
| invoked with the same variable. The name of the file in a directory
| |
| that is searched for is specified by the names listed after the NAMES
| |
| argument. Additional search locations can be specified after the
| |
| PATHS argument. If ENV var is found in the HINTS or PATHS section the
| |
| environment variable var will be read and converted from a system
| |
| environment variable to a cmake style list of paths. For example ENV
| |
| PATH would be a way to list the system path variable. The argument
| |
| after DOC will be used for the documentation string in the cache.
| |
| PATH_SUFFIXES can be used to give sub directories that will be
| |
| appended to the search paths.
| |
| | |
| If NO_DEFAULT_PATH is specified, then no additional paths are added to
| |
| the search. If NO_DEFAULT_PATH is not specified, the search process
| |
| is as follows:
| |
| | |
| 1. Search paths specified in cmake-specific cache variables. These
| |
| are intended to be used on the command line with a -DVAR=value. This
| |
| can be skipped if NO_CMAKE_PATH is passed.
| |
| | |
| <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_INCLUDE_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| | |
| 2. Search paths specified in cmake-specific environment variables.
| |
| These are intended to be set in the user's shell configuration. This
| |
| can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
| |
| | |
| <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_INCLUDE_PATH
| |
| CMAKE_FRAMEWORK_PATH
| |
| | |
| 3. Search the paths specified by the HINTS option. These should be
| |
| paths computed by system introspection, such as a hint provided by the
| |
| location of another item already found. Hard-coded guesses should be
| |
| specified with the PATHS option.
| |
| | |
| 4. Search the standard system environment variables. This can be
| |
| skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
| |
| | |
| PATH
| |
| INCLUDE
| |
| | |
| 5. Search cmake variables defined in the Platform files for the
| |
| current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
| |
| passed.
| |
| | |
| <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
| |
| CMAKE_SYSTEM_INCLUDE_PATH
| |
| CMAKE_SYSTEM_FRAMEWORK_PATH
| |
| | |
| 6. Search the paths specified by the PATHS option or in the
| |
| short-hand version of the command. These are typically hard-coded
| |
| guesses.
| |
| | |
| On Darwin or systems supporting OS X Frameworks, the cmake variable
| |
| CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
| |
| | |
| "FIRST" - Try to find frameworks before standard
| |
| libraries or headers. This is the default on Darwin.
| |
| "LAST" - Try to find frameworks after standard
| |
| libraries or headers.
| |
| "ONLY" - Only try to find frameworks.
| |
| "NEVER". - Never try to find frameworks.
| |
| | |
| On Darwin or systems supporting OS X Application Bundles, the cmake
| |
| variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
| |
| following:
| |
| | |
| "FIRST" - Try to find application bundles before standard
| |
| programs. This is the default on Darwin.
| |
| "LAST" - Try to find application bundles after standard
| |
| programs.
| |
| "ONLY" - Only try to find application bundles.
| |
| "NEVER". - Never try to find application bundles.
| |
| | |
| The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
| |
| directories to be prepended to all other search directories. This
| |
| effectively "re-roots" the entire search under given locations. By
| |
| default it is empty. It is especially useful when cross-compiling to
| |
| point to the root directory of the target environment and CMake will
| |
| search there too. By default at first the directories listed in
| |
| CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
| |
| searched. The default behavior can be adjusted by setting
| |
| CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually
| |
| overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
| |
| the search order will be as described above. If
| |
| NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
| |
| used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
| |
| directories will be searched.
| |
| | |
| The default search order is designed to be most-specific to
| |
| least-specific for common use cases. Projects may override the order
| |
| by simply calling the command multiple times and using the NO_*
| |
| options:
| |
| | |
| find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
| |
| find_path(<VAR> NAMES name)
| |
| | |
| Once one of the calls succeeds the result variable will be set and
| |
| stored in the cache so that no call will search again.
| |
| | |
| When searching for frameworks, if the file is specified as A/b.h, then
| |
| the framework search will look for A.framework/Headers/b.h. If that
| |
| is found the path will be set to the path to the framework. CMake
| |
| will convert this to the correct -F option to include the file.
| |
| | |
| find_program
| |
| Find an executable program.
| |
| | |
| find_program(<VAR> name1 [path1 path2 ...])
| |
| | |
| This is the short-hand signature for the command that is sufficient in
| |
| many cases. It is the same as find_program(<VAR> name1 [PATHS path1
| |
| path2 ...])
| |
| | |
| find_program(
| |
| <VAR>
| |
| name | NAMES name1 [name2 ...]
| |
| [HINTS path1 [path2 ... ENV var]]
| |
| [PATHS path1 [path2 ... ENV var]]
| |
| [PATH_SUFFIXES suffix1 [suffix2 ...]]
| |
| [DOC "cache documentation string"]
| |
| [NO_DEFAULT_PATH]
| |
| [NO_CMAKE_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_PATH]
| |
| [NO_SYSTEM_ENVIRONMENT_PATH]
| |
| [NO_CMAKE_SYSTEM_PATH]
| |
| [CMAKE_FIND_ROOT_PATH_BOTH |
| |
| ONLY_CMAKE_FIND_ROOT_PATH |
| |
| NO_CMAKE_FIND_ROOT_PATH]
| |
| )
| |
| | |
| This command is used to find a program. A cache entry named by <VAR>
| |
| is created to store the result of this command. If the program is
| |
| found the result is stored in the variable and the search will not be
| |
| repeated unless the variable is cleared. If nothing is found, the
| |
| result will be <VAR>-NOTFOUND, and the search will be attempted again
| |
| the next time find_program is invoked with the same variable. The
| |
| name of the program that is searched for is specified by the names
| |
| listed after the NAMES argument. Additional search locations can be
| |
| specified after the PATHS argument. If ENV var is found in the HINTS
| |
| or PATHS section the environment variable var will be read and
| |
| converted from a system environment variable to a cmake style list of
| |
| paths. For example ENV PATH would be a way to list the system path
| |
| variable. The argument after DOC will be used for the documentation
| |
| string in the cache. PATH_SUFFIXES can be used to give sub
| |
| directories that will be appended to the search paths.
| |
| | |
| If NO_DEFAULT_PATH is specified, then no additional paths are added to
| |
| the search. If NO_DEFAULT_PATH is not specified, the search process
| |
| is as follows:
| |
| | |
| 1. Search paths specified in cmake-specific cache variables. These
| |
| are intended to be used on the command line with a -DVAR=value. This
| |
| can be skipped if NO_CMAKE_PATH is passed.
| |
| | |
| <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_PROGRAM_PATH
| |
| CMAKE_APPBUNDLE_PATH
| |
| | |
| 2. Search paths specified in cmake-specific environment variables.
| |
| These are intended to be set in the user's shell configuration. This
| |
| can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
| |
| | |
| <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
| |
| CMAKE_PROGRAM_PATH
| |
| CMAKE_APPBUNDLE_PATH
| |
| | |
| 3. Search the paths specified by the HINTS option. These should be
| |
| paths computed by system introspection, such as a hint provided by the
| |
| location of another item already found. Hard-coded guesses should be
| |
| specified with the PATHS option.
| |
| | |
| 4. Search the standard system environment variables. This can be
| |
| skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
| |
| | |
| PATH
| |
|
| |
| | |
| 5. Search cmake variables defined in the Platform files for the
| |
| current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
| |
| passed.
| |
| | |
| <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
| |
| CMAKE_SYSTEM_PROGRAM_PATH
| |
| CMAKE_SYSTEM_APPBUNDLE_PATH
| |
| | |
| 6. Search the paths specified by the PATHS option or in the
| |
| short-hand version of the command. These are typically hard-coded
| |
| guesses.
| |
| | |
| On Darwin or systems supporting OS X Frameworks, the cmake variable
| |
| CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
| |
| | |
| "FIRST" - Try to find frameworks before standard
| |
| libraries or headers. This is the default on Darwin.
| |
| "LAST" - Try to find frameworks after standard
| |
| libraries or headers.
| |
| "ONLY" - Only try to find frameworks.
| |
| "NEVER". - Never try to find frameworks.
| |
| | |
| On Darwin or systems supporting OS X Application Bundles, the cmake
| |
| variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
| |
| following:
| |
| | |
| "FIRST" - Try to find application bundles before standard
| |
| programs. This is the default on Darwin.
| |
| "LAST" - Try to find application bundles after standard
| |
| programs.
| |
| "ONLY" - Only try to find application bundles.
| |
| "NEVER". - Never try to find application bundles.
| |
| | |
| The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
| |
| directories to be prepended to all other search directories. This
| |
| effectively "re-roots" the entire search under given locations. By
| |
| default it is empty. It is especially useful when cross-compiling to
| |
| point to the root directory of the target environment and CMake will
| |
| search there too. By default at first the directories listed in
| |
| CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
| |
| searched. The default behavior can be adjusted by setting
| |
| CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually
| |
| overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
| |
| the search order will be as described above. If
| |
| NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
| |
| used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
| |
| directories will be searched.
| |
| | |
| The default search order is designed to be most-specific to
| |
| least-specific for common use cases. Projects may override the order
| |
| by simply calling the command multiple times and using the NO_*
| |
| options:
| |
| | |
| find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
| |
| find_program(<VAR> NAMES name)
| |
| | |
| Once one of the calls succeeds the result variable will be set and
| |
| stored in the cache so that no call will search again.
| |
| | |
| foreach
| |
| Evaluate a group of commands for each value in a list.
| |
| | |
| foreach(loop_var arg1 arg2 ...)
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| endforeach(loop_var)
| |
| foreach(loop_var RANGE total)
| |
| foreach(loop_var RANGE start stop [step])
| |
| | |
| All commands between foreach and the matching endforeach are recorded
| |
| without being invoked. Once the endforeach is evaluated, the recorded
| |
| list of commands is invoked once for each argument listed in the
| |
| original foreach command. Before each iteration of the loop
| |
| "${loop_var}" will be set as a variable with the current value in the
| |
| list.
| |
| | |
| Foreach can also iterate over a generated range of numbers. There are
| |
| three types of this iteration:
| |
| | |
| * When specifying single number, the range will have elements 0 to
| |
| "total".
| |
| | |
| * When specifying two numbers, the range will have elements from the
| |
| first number to the second number.
| |
| | |
| * The third optional number is the increment used to iterate from the
| |
| first number to the second number.
| |
| | |
| function
| |
| Start recording a function for later invocation as a command.
| |
| | |
| function(<name> [arg1 [arg2 [arg3 ...]]])
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| endfunction(<name>)
| |
| | |
| Define a function named <name> that takes arguments named arg1 arg2
| |
| arg3 (...). Commands listed after function, but before the matching
| |
| endfunction, are not invoked until the function is invoked. When it
| |
| is invoked, the commands recorded in the function are first modified
| |
| by replacing formal parameters (${arg1}) with the arguments passed,
| |
| and then invoked as normal commands. In addition to referencing the
| |
| formal parameters you can reference the variable ARGC which will be
| |
| set to the number of arguments passed into the function as well as
| |
| ARGV0 ARGV1 ARGV2 ... which will have the actual values of the
| |
| arguments passed in. This facilitates creating functions with
| |
| optional arguments. Additionally ARGV holds the list of all arguments
| |
| given to the function and ARGN holds the list of argument pass the
| |
| last expected argument.
| |
| | |
| get_cmake_property
| |
| Get a property of the CMake instance.
| |
| | |
| get_cmake_property(VAR property)
| |
| | |
| Get a property from the CMake instance. The value of the property is
| |
| stored in the variable VAR. If the property is not found, CMake will
| |
| report an error. Some supported properties include: VARIABLES,
| |
| CACHE_VARIABLES, COMMANDS, MACROS, and COMPONENTS.
| |
| | |
| get_directory_property
| |
| Get a property of the directory.
| |
| | |
| get_directory_property(VAR [DIRECTORY dir] property)
| |
| | |
| Get a property from the Directory. The value of the property is
| |
| stored in the variable VAR. If the property is not found, CMake will
| |
| report an error. The properties include: VARIABLES, CACHE_VARIABLES,
| |
| COMMANDS, MACROS, INCLUDE_DIRECTORIES, LINK_DIRECTORIES, DEFINITIONS,
| |
| INCLUDE_REGULAR_EXPRESSION, LISTFILE_STACK, PARENT_DIRECTORY, and
| |
| DEFINITION varname. If the DIRECTORY argument is provided then the
| |
| property of the provided directory will be retrieved instead of the
| |
| current directory. You can only get properties of a directory during
| |
| or after it has been traversed by cmake.
| |
| | |
| get_filename_component
| |
| Get a specific component of a full filename.
| |
| | |
| get_filename_component(VarName FileName
| |
| PATH|ABSOLUTE|NAME|EXT|NAME_WE
| |
| [CACHE])
| |
| | |
| Set VarName to be the path (PATH), file name (NAME), file extension
| |
| (EXT), file name without extension (NAME_WE) of FileName, or the full
| |
| absolute (ABSOLUTE) file name without symlinks. Note that the path is
| |
| converted to Unix slashes format and has no trailing slashes. The
| |
| longest file extension is always considered. If the optional CACHE
| |
| argument is specified, the result variable is added to the cache.
| |
| | |
| get_filename_component(VarName FileName
| |
| PROGRAM [PROGRAM_ARGS ArgVar]
| |
| [CACHE])
| |
| | |
| The program in FileName will be found in the system search path or
| |
| left as a full path. If PROGRAM_ARGS is present with PROGRAM, then
| |
| any command-line arguments present in the FileName string are split
| |
| from the program name and stored in ArgVar. This is used to separate
| |
| a program name from its arguments in a command line string.
| |
| | |
| get_property
| |
| Get a property.
| |
| | |
| get_property(<variable>
| |
| <GLOBAL |
| |
| DIRECTORY [dir] |
| |
| TARGET <target> |
| |
| SOURCE <source> |
| |
| TEST <test> |
| |
| VARIABLE>
| |
| PROPERTY <name>
| |
| [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
| |
| | |
| Get one property from one object in a scope. The first argument
| |
| specifies the variable in which to store the result. The second
| |
| argument determines the scope from which to get the property. It must
| |
| be one of the following:
| |
| | |
| GLOBAL scope is unique and does not accept a name.
| |
| | |
| DIRECTORY scope defaults to the current directory but another
| |
| directory (already processed by CMake) may be named by full or
| |
| relative path.
| |
| | |
| TARGET scope must name one existing target.
| |
| | |
| SOURCE scope must name one source file.
| |
| | |
| TEST scope must name one existing test.
| |
| | |
| VARIABLE scope is unique and does not accept a name.
| |
| | |
| The required PROPERTY option is immediately followed by the name of
| |
| the property to get. If the property is not set an empty value is
| |
| returned. If the SET option is given the variable is set to a boolean
| |
| value indicating whether the property has been set.If the DEFINED
| |
| option is given the variable is set to a boolean value indicating
| |
| whether the property has been defined such as with define_property.
| |
| If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
| |
| string containing documentation for the requested property. If
| |
| documentation is requested for a property that has not been defined
| |
| NOTFOUND is returned.
| |
| | |
| if
| |
| Conditionally execute a group of commands.
| |
| | |
| if(expression)
| |
| # then section.
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| elseif(expression2)
| |
| # elseif section.
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| else(expression)
| |
| # else section.
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| endif(expression)
| |
| | |
| Evaluates the given expression. If the result is true, the commands
| |
| in the THEN section are invoked. Otherwise, the commands in the else
| |
| section are invoked. The elseif and else sections are optional. You
| |
| may have multiple elseif clauses. Note that the same expression must
| |
| be given to if, and endif. Long expressions can be used and the order
| |
| or precedence is that the EXISTS, COMMAND, and DEFINED operators will
| |
| be evaluated first. Then any EQUAL, LESS, GREATER, STRLESS,
| |
| STRGREATER, STREQUAL, MATCHES will be evaluated. Then NOT operators
| |
| and finally AND, OR operators will be evaluated. Possible expressions
| |
| are:
| |
| | |
| if(variable)
| |
| | |
| True if the variable's value is not empty, 0, N, NO, OFF, FALSE,
| |
| NOTFOUND, or <variable>-NOTFOUND.
| |
| | |
| if(NOT variable)
| |
| | |
| True if the variable's value is empty, 0, N, NO, OFF, FALSE, NOTFOUND,
| |
| or <variable>-NOTFOUND.
| |
| | |
| if(variable1 AND variable2)
| |
| | |
| True if both variables would be considered true individually.
| |
| | |
| if(variable1 OR variable2)
| |
| | |
| True if either variable would be considered true individually.
| |
| | |
| if(COMMAND command-name)
| |
| | |
| True if the given name is a command, macro or function that can be
| |
| invoked.
| |
| | |
| if(POLICY policy-id)
| |
| | |
| True if the given name is an existing policy (of the form CMP<NNNN>).
| |
| | |
| if(EXISTS file-name)
| |
| if(EXISTS directory-name)
| |
| | |
| True if the named file or directory exists. Behavior is well-defined
| |
| only for full paths.
| |
| | |
| if(file1 IS_NEWER_THAN file2)
| |
| | |
| True if file1 is newer than file2 or if one of the two files doesn't
| |
| exist. Behavior is well-defined only for full paths.
| |
| | |
| if(IS_DIRECTORY directory-name)
| |
| | |
| True if the given name is a directory. Behavior is well-defined only
| |
| for full paths.
| |
| | |
| if(IS_ABSOLUTE path)
| |
| | |
| True if the given path is an absolute path.
| |
| | |
| if(variable MATCHES regex)
| |
| if(string MATCHES regex)
| |
| | |
| True if the given string or variable's value matches the given regular
| |
| expression.
| |
| | |
| if(variable LESS number)
| |
| if(string LESS number)
| |
| if(variable GREATER number)
| |
| if(string GREATER number)
| |
| if(variable EQUAL number)
| |
| if(string EQUAL number)
| |
| | |
| True if the given string or variable's value is a valid number and the
| |
| inequality or equality is true.
| |
| | |
| if(variable STRLESS string)
| |
| if(string STRLESS string)
| |
| if(variable STRGREATER string)
| |
| if(string STRGREATER string)
| |
| if(variable STREQUAL string)
| |
| if(string STREQUAL string)
| |
| | |
| True if the given string or variable's value is lexicographically less
| |
| (or greater, or equal) than the string on the right.
| |
| | |
| if(DEFINED variable)
| |
| | |
| True if the given variable is defined. It does not matter if the
| |
| variable is true or false just if it has been set.
| |
| | |
| include
| |
| Read CMake listfile code from the given file.
| |
| | |
| include(file1 [OPTIONAL] [RESULT_VARIABLE <VAR>])
| |
| include(module [OPTIONAL] [RESULT_VARIABLE <VAR>])
| |
| | |
| Reads CMake listfile code from the given file. Commands in the file
| |
| are processed immediately as if they were written in place of the
| |
| include command. If OPTIONAL is present, then no error is raised if
| |
| the file does not exist. If RESULT_VARIABLE is given the variable
| |
| will be set to the full filename which has been included or NOTFOUND
| |
| if it failed.
| |
| | |
| If a module is specified instead of a file, the file with name
| |
| <modulename>.cmake is searched in the CMAKE_MODULE_PATH.
| |
| | |
| list
| |
| List operations.
| |
| | |
| list(LENGTH <list> <output variable>)
| |
| list(GET <list> <element index> [<element index> ...] <output variable>)
| |
| list(APPEND <list> <element> [<element> ...])
| |
| list(FIND <list> <value> <output variable>)
| |
| list(INSERT <list> <element_index> <element> [<element> ...])
| |
| list(REMOVE_ITEM <list> <value> [<value> ...])
| |
| list(REMOVE_AT <list> <index> [<index> ...])
| |
| list(REMOVE_DUPLICATES <list>)
| |
| list(REVERSE <list>)
| |
| list(SORT <list>)
| |
| | |
| LENGTH will return a given list's length.
| |
| | |
| GET will return list of elements specified by indices from the list.
| |
| | |
| APPEND will append elements to the list.
| |
| | |
| FIND will return the index of the element specified in the list or -1
| |
| if it wasn't found.
| |
| | |
| INSERT will insert elements to the list to the specified location.
| |
| | |
| REMOVE_AT and REMOVE_ITEM will remove items from the list. The
| |
| difference is that REMOVE_ITEM will remove the given items, while
| |
| REMOVE_AT will remove the items at the given indices.
| |
| | |
| REMOVE_DUPLICATES will remove duplicated items in the list.
| |
| | |
| REVERSE reverses the contents of the list in-place.
| |
| | |
| SORT sorts the list in-place alphabetically.
| |
| | |
| NOTES: A list in cmake is a ; separated group of strings. To create a
| |
| list the set command can be used. For example, set(var a b c d e)
| |
| creates a list with a;b;c;d;e, and set(var "a b c d e") creates a
| |
| string or a list with one item in it.
| |
| | |
| When specifying index values, if <element index> is 0 or greater, it
| |
| is indexed from the beginning of the list, with 0 representing the
| |
| first list element. If <element index> is -1 or lesser, it is indexed
| |
| from the end of the list, with -1 representing the last list element.
| |
| Be careful when counting with negative indices: they do not start from
| |
| 0. -0 is equivalent to 0, the first list element.
| |
| | |
| | |
| macro
| |
| Start recording a macro for later invocation as a command.
| |
| | |
| macro(<name> [arg1 [arg2 [arg3 ...]]])
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| endmacro(<name>)
| |
| | |
| Define a macro named <name> that takes arguments named arg1 arg2 arg3
| |
| (...). Commands listed after macro, but before the matching endmacro,
| |
| are not invoked until the macro is invoked. When it is invoked, the
| |
| commands recorded in the macro are first modified by replacing formal
| |
| parameters (${arg1}) with the arguments passed, and then invoked as
| |
| normal commands. In addition to referencing the formal parameters you
| |
| can reference the values ${ARGC} which will be set to the number of
| |
| arguments passed into the function as well as ${ARGV0} ${ARGV1}
| |
| ${ARGV2} ... which will have the actual values of the arguments
| |
| passed in. This facilitates creating macros with optional arguments.
| |
| Additionally ${ARGV} holds the list of all arguments given to the
| |
| macro and ${ARGN} holds the list of argument pass the last expected
| |
| argument. Note that the parameters to a macro and values such as ARGN
| |
| are not variables in the usual CMake sense. They are string
| |
| replacements much like the c preprocessor would do with a macro. If
| |
| you want true CMake variables you should look at the function command.
| |
| | |
| make_directory
| |
| Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
| |
| | |
| make_directory(directory)
| |
| | |
| Creates the specified directory. Full paths should be given. Any
| |
| parent directories that do not exist will also be created. Use with
| |
| care.
| |
| | |
| mark_as_advanced
| |
| Mark cmake cached variables as advanced.
| |
| | |
| mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
| |
| | |
| Mark the named cached variables as advanced. An advanced variable
| |
| will not be displayed in any of the cmake GUIs unless the show
| |
| advanced option is on. If CLEAR is the first argument advanced
| |
| variables are changed back to unadvanced. If FORCE is the first
| |
| argument, then the variable is made advanced. If neither FORCE nor
| |
| CLEAR is specified, new values will be marked as advanced, but if the
| |
| variable already has an advanced/non-advanced state, it will not be
| |
| changed.
| |
| | |
| It does nothing in script mode.
| |
| | |
| math
| |
| Mathematical expressions.
| |
| | |
| math(EXPR <output variable> <math expression>)
| |
| | |
| EXPR evaluates mathematical expression and return result in the output
| |
| variable. Example mathematical expression is '5 * ( 10 + 13 )'.
| |
| Supported operators are + - * / % | & ^ ~ << >> * / %. They have the
| |
| same meaning as they do in c code.
| |
| | |
| message
| |
| Display a message to the user.
| |
| | |
| message([SEND_ERROR | STATUS | FATAL_ERROR]
| |
| "message to display" ...)
| |
| | |
| By default the message is displayed in a pop up window (CMakeSetup),
| |
| or in the stdout of cmake, or the error section of ccmake. If the
| |
| first argument is SEND_ERROR then an error is raised, and the generate
| |
| phase will be skipped. If the first argument is FATAL_ERROR, all
| |
| processing is halted. If the first argument is STATUS then the
| |
| message is displayed in the progress line for the GUI, or with a -- in
| |
| the command line cmake.
| |
| | |
| option
| |
| Provides an option that the user can optionally select.
| |
| | |
| option(<option_variable> "help string describing option"
| |
| [initial value])
| |
| | |
| Provide an option for the user to select as ON or OFF. If no initial
| |
| value is provided, OFF is used.
| |
| | |
| remove
| |
| Deprecated. Use the list(REMOVE_ITEM ) command instead.
| |
| | |
| remove(VAR VALUE VALUE ...)
| |
| | |
| Removes VALUE from the variable VAR. This is typically used to remove
| |
| entries from a vector (e.g. semicolon separated list). VALUE is
| |
| expanded.
| |
| | |
| return
| |
| Return from a directory or function.
| |
| | |
| return()
| |
| | |
| Returns from a directory or function. When this command is
| |
| encountered, it caused process of the current function or directory to
| |
| stop and control is return to the caller of the function, or the
| |
| parent directory if any. Note that a macro is not a function and does
| |
| not handle return like a function does.
| |
| | |
| separate_arguments
| |
| Split space separated arguments into a semi-colon separated list.
| |
| | |
| separate_arguments(VARIABLE)
| |
| | |
| Convert the value of VARIABLE to a semi-colon separated list. All
| |
| spaces are replaced with ';'. This helps with generating command
| |
| lines.
| |
| | |
| set
| |
| Set a CMAKE variable to a given value.
| |
| | |
| set(<variable> <value> [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
| |
| | |
| Within CMake sets <variable> to the value <value>. <value> is
| |
| expanded before <variable> is set to it. If CACHE is present, then
| |
| the <variable> is put in the cache. <type> and <docstring> are then
| |
| required. <type> is used by the CMake GUI to choose a widget with
| |
| which the user sets a value. The value for <type> may be one of
| |
| | |
| FILEPATH = File chooser dialog.
| |
| PATH = Directory chooser dialog.
| |
| STRING = Arbitrary string.
| |
| BOOL = Boolean ON/OFF checkbox.
| |
| INTERNAL = No GUI entry (used for persistent variables).
| |
| | |
| If <type> is INTERNAL, then the <value> is always written into the
| |
| cache, replacing any values existing in the cache. If it is not a
| |
| cache variable, then this always writes into the current makefile.
| |
| The FORCE option will overwrite the cache value removing any changes
| |
| by the user.
| |
| | |
| If PARENT_SCOPE is present, the variable will be set in the scope
| |
| above the current scope. Each new directory or function creates a new
| |
| scope. This command will set the value of a variable into the parent
| |
| directory or calling function (whichever is applicable to the case at
| |
| hand) If VALUE is not specified then the variable is removed from the
| |
| parent scope.
| |
| | |
| set(<variable> <value1> ... <valueN>)
| |
| | |
| In this case <variable> is set to a semicolon separated list of
| |
| values.
| |
| | |
| <variable> can be an environment variable such as:
| |
| | |
| set( ENV{PATH} /home/martink )
| |
| | |
| in which case the environment variable will be set.
| |
| | |
| set_directory_properties
| |
| Set a property of the directory.
| |
| | |
| set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
| |
| | |
| Set a property for the current directory and subdirectories. If the
| |
| property is not found, CMake will report an error. The properties
| |
| include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
| |
| INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
| |
| | |
| ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be cleaned as
| |
| a part of "make clean" stage.
| |
| | |
| set_property
| |
| Set a named property in a given scope.
| |
| | |
| set_property(<GLOBAL |
| |
| DIRECTORY [dir] |
| |
| TARGET [target1 [target2 ...]] |
| |
| SOURCE [src1 [src2 ...]] |
| |
| TEST [test1 [test2 ...]]>
| |
| [APPEND]
| |
| PROPERTY <name> [value1 [value2 ...]])
| |
| | |
| Set one property on zero or more objects of a scope. The first
| |
| argument determines the scope in which the property is set. It must
| |
| be one of the following:
| |
| | |
| GLOBAL scope is unique and does not accept a name.
| |
| | |
| DIRECTORY scope defaults to the current directory but another
| |
| directory (already processed by CMake) may be named by full or
| |
| relative path.
| |
| | |
| TARGET scope may name zero or more existing targets.
| |
| | |
| SOURCE scope may name zero or more source files.
| |
| | |
| TEST scope may name zero or more existing tests.
| |
| | |
| The required PROPERTY option is immediately followed by the name of
| |
| the property to set. Remaining arguments are used to compose the
| |
| property value in the form of a semicolon-separated list. If the
| |
| APPEND option is given the list is appended to any existing property
| |
| value.
| |
| | |
| site_name
| |
| Set the given variable to the name of the computer.
| |
| | |
| site_name(variable)
| |
| | |
| | |
| string
| |
| String operations.
| |
| | |
| string(REGEX MATCH <regular_expression>
| |
| <output variable> <input> [<input>...])
| |
| string(REGEX MATCHALL <regular_expression>
| |
| <output variable> <input> [<input>...])
| |
| string(REGEX REPLACE <regular_expression>
| |
| <replace_expression> <output variable>
| |
| <input> [<input>...])
| |
| string(REPLACE <match_string>
| |
| <replace_string> <output variable>
| |
| <input> [<input>...])
| |
| string(COMPARE EQUAL <string1> <string2> <output variable>)
| |
| string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
| |
| string(COMPARE LESS <string1> <string2> <output variable>)
| |
| string(COMPARE GREATER <string1> <string2> <output variable>)
| |
| string(ASCII <number> [<number> ...] <output variable>)
| |
| string(CONFIGURE <string1> <output variable>
| |
| [@ONLY] [ESCAPE_QUOTES])
| |
| string(TOUPPER <string1> <output variable>)
| |
| string(TOLOWER <string1> <output variable>)
| |
| string(LENGTH <string> <output variable>)
| |
| string(SUBSTRING <string> <begin> <length> <output variable>)
| |
| string(STRIP <string> <output variable>)
| |
| string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
| |
| <output variable>)
| |
| | |
| REGEX MATCH will match the regular expression once and store the match
| |
| in the output variable.
| |
| | |
| REGEX MATCHALL will match the regular expression as many times as
| |
| possible and store the matches in the output variable as a list.
| |
| | |
| REGEX REPLACE will match the regular expression as many times as
| |
| possible and substitute the replacement expression for the match in
| |
| the output. The replace expression may refer to paren-delimited
| |
| subexpressions of the match using \1, \2, ..., \9. Note that two
| |
| backslashes (\\1) are required in CMake code to get a backslash
| |
| through argument parsing.
| |
| | |
| REPLACE will replace all occurrences of match_string in the input with
| |
| replace_string and store the result in the output.
| |
| | |
| COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and store
| |
| true or false in the output variable.
| |
| | |
| ASCII will convert all numbers into corresponding ASCII characters.
| |
| | |
| CONFIGURE will transform a string like CONFIGURE_FILE transforms a
| |
| file.
| |
| | |
| TOUPPER/TOLOWER will convert string to upper/lower characters.
| |
| | |
| LENGTH will return a given string's length.
| |
| | |
| SUBSTRING will return a substring of a given string.
| |
| | |
| STRIP will return a substring of a given string with leading and
| |
| trailing spaces removed.
| |
| | |
| RANDOM will return a random string of given length consisting of
| |
| characters from the given alphabet. Default length is 5 characters
| |
| and default alphabet is all numbers and upper and lower case letters.
| |
| | |
| The following characters have special meaning in regular expressions:
| |
| | |
| ^ Matches at beginning of a line
| |
| $ Matches at end of a line
| |
| . Matches any single character
| |
| [ ] Matches any character(s) inside the brackets
| |
| [^ ] Matches any character(s) not inside the brackets
| |
| - Matches any character in range on either side of a dash
| |
| * Matches preceding pattern zero or more times
| |
| + Matches preceding pattern one or more times
| |
| ? Matches preceding pattern zero or once only
| |
| | Matches a pattern on either side of the |
| |
| () Saves a matched subexpression, which can be referenced in the REGEX REPLACE operation. Additionally it is saved in the special CMake variables CMAKE_MATCH_(0..9).
| |
| | |
| variable_watch
| |
| Watch the CMake variable for change.
| |
| | |
| variable_watch(<variable name> [<command to execute>])
| |
| | |
| If the specified variable changes, the message will be printed about
| |
| the variable being changed. If the command is specified, the command
| |
| will be executed. The command will receive the following arguments:
| |
| COMMAND(<variable> <access> <value> <current list file> <stack>)
| |
| | |
| while
| |
| Evaluate a group of commands while a condition is true
| |
| | |
| while(condition)
| |
| COMMAND1(ARGS ...)
| |
| COMMAND2(ARGS ...)
| |
| ...
| |
| endwhile(condition)
| |
| | |
| All commands between while and the matching endwhile are recorded
| |
| without being invoked. Once the endwhile is evaluated, the recorded
| |
| list of commands is invoked as long as the condition is true. The
| |
| condition is evaluated using the same logic as the if command.
| |
| | |
| write_file
| |
| Deprecated. Use the file(WRITE ) command instead.
| |
| | |
| write_file(filename "message to write"... [APPEND])
| |
| | |
| The first argument is the file name, the rest of the arguments are
| |
| messages to write. If the argument APPEND is specified, then the
| |
| message will be appended.
| |
| | |
| NOTE 1: file(WRITE ... and file(APPEND ... do exactly the same as
| |
| this one but add some more functionality.
| |
| | |
| NOTE 2: When using write_file the produced file cannot be used as an
| |
| input to CMake (CONFIGURE_FILE, source file ...) because it will lead
| |
| to an infinite loop. Use configure_file if you want to generate input
| |
| files to CMake.
| |
| | |
| ------------------------------------------------------------------------------
| |
| Properties
| |
| | |
| CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
| |
| | |
| This is the documentation for the properties supported by CMake. Properties
| |
| can have different scopes. They can either be assigned to a source file, a
| |
| directory, a target or globally to CMake. By modifying the values of
| |
| properties the behaviour of the build system can be customized.
| |
| | |
| ------------------------------------------------------------------------------
| |
| Compatibility Commands
| |
| | |
| CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.
| |
| | |
| This is the documentation for now obsolete listfile commands from previous
| |
| CMake versions, which are still supported for compatibility reasons. You
| |
| should instead use the newer, faster and shinier new commands. ;-)
| |
| | |
| ------------------------------------------------------------------------------
| |
| Standard CMake Modules
| |
| | |
| ------------------------------------------------------------------------------
| |
| Copyright
| |
| | |
| Copyright (c) 2002 Kitware, Inc., Insight Consortium. All rights reserved.
| |
| | |
| Redistribution and use in source and binary forms, with or without
| |
| modification, are permitted provided that the following conditions are met:
| |
| | |
| Redistributions of source code must retain the above copyright notice, this
| |
| list of conditions and the following disclaimer.
| |
| | |
| Redistributions in binary form must reproduce the above copyright notice,
| |
| this list of conditions and the following disclaimer in the documentation
| |
| and/or other materials provided with the distribution.
| |
| | |
| The names of Kitware, Inc., the Insight Consortium, or the names of any
| |
| consortium members, or of any contributors, may not be used to endorse or
| |
| promote products derived from this software without specific prior written
| |
| permission.
| |
| | |
| Modified source versions must be plainly marked as such, and must not be
| |
| misrepresented as being the original software.
| |
| | |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS''
| |
| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
| |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
| |
| ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
| |
| ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
| |
| DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
| |
| SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
| |
| CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
| |
| OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
| |
| OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
| |
| | |
| ------------------------------------------------------------------------------
| |
| See Also | |
| | |
| The following resources are available to get help using CMake:
| |
| | |
| Home Page
| |
| http://www.cmake.org
| |
| | |
| The primary starting point for learning about CMake.
| |
| | |
| Frequently Asked Questions
| |
| http://www.cmake.org/Wiki/CMake_FAQ
| |
| | |
| A Wiki is provided containing answers to frequently asked questions.
| |
| | |
| Online Documentation
| |
| http://www.cmake.org/HTML/Documentation.html
| |
| | |
| Links to available documentation may be found on this web page.
| |
| | |
| Mailing List
| |
| http://www.cmake.org/HTML/MailingLists.html
| |
| | |
| For help and discussion about using cmake, a mailing list is provided
| |
| at cmake@cmake.org. The list is member-post-only but one may sign up
| |
| on the CMake web page. Please first read the full documentation at
| |
| http://www.cmake.org before posting questions to the list.
| |
| | |
| Summary of helpful links:
| |
| | |
| Home: http://www.cmake.org
| |
| Docs: http://www.cmake.org/HTML/Documentation.html
| |
| Mail: http://www.cmake.org/HTML/MailingLists.html
| |
| FAQ: http://www.cmake.org/Wiki/CMake_FAQ
| |
| | |
| </pre>
| |
