|
|
| Line 1: |
Line 1: |
| <pre>
| | See https://cmake.org/cmake/help/v2.8.0/ctest.html |
| ctest version 2.8.0
| |
| ------------------------------------------------------------------------------
| |
| 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.
| |
| | |
| --output-on-failure
| |
| Output anything outputted by the test program if the test should fail.
| |
| This option can also be enabled by setting the environment variable
| |
| CTEST_OUTPUT_ON_FAILURE
| |
| | |
| -F
| |
| Enable failover.
| |
| | |
| This option allows ctest to resume a test set execution that was
| |
| previously interrupted. If no interruption occurred, the -F option
| |
| will have no effect.
| |
| | |
| -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.
| |
| | |
| -L <regex>, --label-regex <regex>
| |
| Run tests with labels matching regular expression.
| |
| | |
| This option tells ctest to run only the tests whose labels match the
| |
| given regular expression.
| |
| | |
| -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.
| |
| | |
| -LE <regex>, --label-exclude <regex>
| |
| Exclude tests with labels matching regular expression.
| |
| | |
| This option tells ctest to NOT run the tests whose labels 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.
| |
| | |
| --max-width <width>
| |
| Set the max width for a test name to output
| |
| | |
| Set the maximum width for each test name to show in the output. This
| |
| allows the user to widen the output to avoid cliping the test name
| |
| which can be very annoying.
| |
| | |
| --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.
| |
| | |
| --no-label-summary
| |
| Disable timing summary information for labels.
| |
| | |
| This option tells ctest to not print summary information for each
| |
| label associated with the tests run. If there are no labels on the
| |
| tests, nothing extra is printed.
| |
| | |
| --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.
| |
| | |
| --help-command <cmd> [<file>]
| |
| Show help for a single command and exit.
| |
| | |
| Prints the help for the command to stdout or to the specified file.
| |
| | |
| --help-command-list [<file>]
| |
| List available commands and exit.
| |
| | |
| Prints the list of all available listfile commands to stdout or the
| |
| specified file.
| |
| | |
| --help-commands [<file>]
| |
| Print help for all commands and exit.
| |
| | |
| Prints the help for all commands to stdout or to the specified file.
| |
| | |
| ------------------------------------------------------------------------------
| |
| 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 by CMake 2.6 and
| |
| higher. It should be specified so CMake versions 2.4 and lower fail
| |
| with an error instead of just a warning.
| |
| | |
| 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 unset. 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(GET CMP<NNNN> <variable>)
| |
| | |
| Check whether a given policy is set to OLD or NEW behavior. The
| |
| output variable value will be "OLD" or "NEW" if the policy is set, and
| |
| empty otherwise.
| |
| | |
| CMake keeps policy settings on a stack, so changes made by the
| |
| cmake_policy command affect only the top of the stack. A new entry on
| |
| the policy stack is managed automatically for each subdirectory to
| |
| protect its parents and siblings. CMake also manages a new entry for
| |
| scripts loaded by include() and find_package() commands except when
| |
| invoked with the NO_POLICY_SCOPE option (see also policy CMP0011).
| |
| The cmake_policy command provides an interface to manage custom
| |
| entries on the policy stack:
| |
| | |
| cmake_policy(PUSH)
| |
| cmake_policy(POP)
| |
| | |
| Each PUSH must have a matching POP to erase any changes. This is
| |
| useful to make temporary changes to policy settings.
| |
| | |
| Functions and macros record policy settings when they are created and
| |
| use the pre-record policies when they are invoked. If the function or
| |
| macro implementation sets policies, the changes automatically
| |
| propagate up through callers until they reach the closest nested
| |
| policy stack entry.
| |
| | |
| configure_file
| |
| Copy a file to another location and modify its contents.
| |
| | |
| configure_file(<input> <output>
| |
| [COPYONLY] [ESCAPE_QUOTES] [@ONLY])
| |
| | |
| Copies a file <input> to file <output> and substitutes variable values
| |
| referenced in the file content. If <input> is a relative path it is
| |
| evaluated with respect to the current source directory. The <input>
| |
| must be a file, not a directory. If <output> is a relative path it is
| |
| evaluated with respect to the current binary directory. If <output>
| |
| names an existing directory the input file is placed in that directory
| |
| with its original name.
| |
| | |
| 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. Any occurrences of
| |
| #cmakedefine01 VAR will be replaced with either #define VAR 1 or
| |
| #define VAR 0 depending on whether VAR evaluates to TRUE or FALSE in
| |
| CMake
| |
| | |
| ctest_build
| |
| Build the project.
| |
| | |
| ctest_build([BUILD build_dir] [RETURN_VALUE res] [APPEND]
| |
| [NUMBER_ERRORS val] [NUMBER_WARNINGS val])
| |
| | |
| Builds the given build directory and stores results in Build.xml. If
| |
| no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used. The
| |
| RETURN_VALUE option specifies a variable in which to store the return
| |
| value of the native build tool. The NUMBER_ERRORS and NUMBER_WARNINGS
| |
| options specify variables in which to store the number of build errors
| |
| and warnings detected.
| |
| | |
| The APPEND option marks results for append to those previously
| |
| submitted to a dashboard server since the last ctest_start. Append
| |
| semantics are defined by the dashboard server in use.
| |
| | |
| ctest_configure
| |
| Configure the project build tree.
| |
| | |
| ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]
| |
| [OPTIONS options] [RETURN_VALUE res])
| |
| | |
| Configures the given build directory and stores results in
| |
| Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY
| |
| variable is used. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY
| |
| variable is used. The OPTIONS argument specifies command line
| |
| arguments to pass to the configuration tool. The RETURN_VALUE option
| |
| specifies a variable in which to store the return value of the native
| |
| build tool.
| |
| | |
| The APPEND option marks results for append to those previously
| |
| submitted to a dashboard server since the last ctest_start. Append
| |
| semantics are defined by the dashboard server in use.
| |
| | |
| ctest_coverage
| |
| Collect coverage tool results.
| |
| | |
| ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
| |
| [LABELS label1 [label2 [...]]])
| |
| | |
| Perform the coverage of the given build directory and stores results
| |
| in Coverage.xml. The second argument is a variable that will hold
| |
| value.
| |
| | |
| The LABELS option filters the coverage report to include only source
| |
| files labeled with at least one of the labels specified.
| |
| | |
| The APPEND option marks results for append to those previously
| |
| submitted to a dashboard server since the last ctest_start. Append
| |
| semantics are defined by the dashboard server in use.
| |
| | |
| 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
| |
| Run tests with a dynamic analysis tool.
| |
| | |
| ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]
| |
| [START start number] [END end number]
| |
| [STRIDE stride number] [EXCLUDE exclude regex ]
| |
| [INCLUDE include regex]
| |
| [EXCLUDE_LABEL exclude regex]
| |
| [INCLUDE_LABEL label regex]
| |
| [PARALLEL_LEVEL level] )
| |
| | |
| Tests the given build directory and stores results in MemCheck.xml.
| |
| The second argument is a variable that will hold value. Optionally,
| |
| you can specify the starting test number START, the ending test number
| |
| END, the number of tests to skip between each test STRIDE, a regular
| |
| expression for tests to run INCLUDE, or a regular expression for tests
| |
| not to run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular
| |
| expressions for tests to be included or excluded by the test property
| |
| LABEL. PARALLEL_LEVEL should be set to a positive number representing
| |
| the number of tests to be run in parallel.
| |
| | |
| The APPEND option marks results for append to those previously
| |
| submitted to a dashboard server since the last ctest_start. Append
| |
| semantics are defined by the dashboard server in use.
| |
| | |
| 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 ... [RETURN_VALUE var])
| |
| | |
| 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.If RETURN_VALUE is specified
| |
| the return value of the last script run will be put into var.
| |
| | |
| 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
| |
| Submit results to a dashboard server.
| |
| | |
| ctest_submit([PARTS ...] [FILES ...] [RETURN_VALUE res])
| |
| | |
| By default all available parts are submitted if no PARTS or FILES are
| |
| specified. The PARTS option lists a subset of parts to be submitted.
| |
| Valid part names are:
| |
| | |
| Start = nothing
| |
| Update = ctest_update results, in Update.xml
| |
| Configure = ctest_configure results, in Configure.xml
| |
| Build = ctest_build results, in Build.xml
| |
| Test = ctest_test results, in Test.xml
| |
| Coverage = ctest_coverage results, in Coverage.xml
| |
| MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
| |
| Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
| |
| ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
| |
| Submit = nothing
| |
| | |
| The FILES option explicitly lists specific files to be submitted.
| |
| Each individual file must exist at the time of the call.
| |
| | |
| | |
| ctest_test
| |
| Run tests in the project build tree.
| |
| | |
| ctest_test([BUILD build_dir] [APPEND]
| |
| [START start number] [END end number]
| |
| [STRIDE stride number] [EXCLUDE exclude regex ]
| |
| [INCLUDE include regex] [RETURN_VALUE res]
| |
| [EXCLUDE_LABEL exclude regex]
| |
| [INCLUDE_LABEL label regex]
| |
| [PARALLEL_LEVEL level])
| |
| | |
| Tests the given build directory and stores results in Test.xml. The
| |
| second argument is a variable that will hold value. Optionally, you
| |
| can specify the starting test number START, the ending test number
| |
| END, the number of tests to skip between each test STRIDE, a regular
| |
| expression for tests to run INCLUDE, or a regular expression for tests
| |
| to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular
| |
| expression for test to be included or excluded by the test property
| |
| LABEL. PARALLEL_LEVEL should be set to a positive number representing
| |
| the number of tests to be run in parallel.
| |
| | |
| The APPEND option marks results for append to those previously
| |
| submitted to a dashboard server since the last ctest_start. Append
| |
| semantics are defined by the dashboard server in use.
| |
| | |
| ctest_update
| |
| Update the work tree from version control.
| |
| | |
| ctest_update([SOURCE source] [RETURN_VALUE res])
| |
| | |
| Updates the given source directory and stores results in Update.xml.
| |
| If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used.
| |
| The RETURN_VALUE option specifies a variable in which to store the
| |
| result, which is the number of files updated or -1 on error.
| |
| | |
| 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]
| |
| [FOLLOW_SYMLINKS] [globbing expressions]...)
| |
| file(RENAME <oldname> <newname>)
| |
| 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 a list similar to the regular GLOB, except
| |
| it will traverse all the subdirectories of the matched directory and
| |
| match the files. Subdirectories that are symlinks are only traversed
| |
| if FOLLOW_SYMLINKS is given or cmake policy CMP0009 is not set to NEW.
| |
| See cmake --help-policy CMP0009 for more information.
| |
| | |
| 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
| |
| | |
| RENAME moves a file or directory within a filesystem, replacing the
| |
| destination atomically.
| |
| | |
| 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 given 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 should be specified as an integer.
| |
| | |
| The file() command also provides COPY and INSTALL signatures:
| |
| | |
| file(<COPY|INSTALL> files... DESTINATION <dir>
| |
| [FILE_PERMISSIONS permissions...]
| |
| [DIRECTORY_PERMISSIONS permissions...]
| |
| [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
| |
| [FILES_MATCHING]
| |
| [[PATTERN <pattern> | REGEX <regex>]
| |
| [EXCLUDE] [PERMISSIONS permissions...]] [...])
| |
| | |
| The COPY signature copies files, directories, and symlinks to a
| |
| destination folder. Relative input paths are evaluated with respect
| |
| to the current source directory, and a relative destination is
| |
| evaluated with respect to the current build directory. Copying
| |
| preserves input file timestamps, and optimizes out a file if it exists
| |
| at the destination with the same timestamp. Copying preserves input
| |
| permissions unless explicit permissions or NO_SOURCE_PERMISSIONS are
| |
| given (default is USE_SOURCE_PERMISSIONS). See the install(DIRECTORY)
| |
| command for documentation of permissions, PATTERN, REGEX, and EXCLUDE
| |
| options.
| |
| | |
| The INSTALL signature differs slightly from COPY: it prints status
| |
| messages, and NO_SOURCE_PERMISSIONS is default. Installation scripts
| |
| generated by the install() command use this signature (with some
| |
| undocumented options for internal use).
| |
| | |
| find_file
| |
| Find the full path to a file.
| |
| | |
| find_file(<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_file(<VAR> name1 [PATHS path1
| |
| path2 ...])
| |
| | |
| find_file(
| |
| <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_file 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
| |
| specifies additional subdirectories to check below each search path.
| |
| | |
| 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_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
| |
| find_file(<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 specifies additional
| |
| subdirectories to check below each search path.
| |
| | |
| 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> [version] [EXACT] [QUIET]
| |
| [[REQUIRED|COMPONENTS] [components...]]
| |
| [NO_POLICY_SCOPE])
| |
| | |
| 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 [version] argument requests a version with which the package found
| |
| should be compatible (format is major[.minor[.patch[.tweak]]]). The
| |
| EXACT option requests that the version be matched exactly. If no
| |
| [version] is given to a recursive invocation inside a find-module, the
| |
| [version] and EXACT arguments are forwarded automatically from the
| |
| outer call. 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> [version] [EXACT] [QUIET]
| |
| [[REQUIRED|COMPONENTS] [components...]] [NO_MODULE]
| |
| [NO_POLICY_SCOPE]
| |
| [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_PACKAGE_REGISTRY]
| |
| [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 CMake will ignore it and search from scratch.
| |
| | |
| When the [version] argument is given Config mode will only find a
| |
| version of the package that claims compatibility with the requested
| |
| version (format is major[.minor[.patch[.tweak]]]). 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 configuration 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 = major version if requested, else 0
| |
| PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
| |
| PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
| |
| PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
| |
| PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
| |
| | |
| The version file checks whether it satisfies the requested version and
| |
| sets these variables:
| |
| | |
| PACKAGE_VERSION = full provided version string
| |
| PACKAGE_VERSION_EXACT = true if version is exact match
| |
| PACKAGE_VERSION_COMPATIBLE = true if version is compatible
| |
| PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
| |
| | |
| 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 = full provided version string
| |
| <package>_VERSION_MAJOR = major version if provided, else 0
| |
| <package>_VERSION_MINOR = minor version if provided, else 0
| |
| <package>_VERSION_PATCH = patch version if provided, else 0
| |
| <package>_VERSION_TWEAK = tweak version if provided, else 0
| |
| <package>_VERSION_COUNT = number of version components, 0 to 4
| |
| | |
| 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>/<name>*/ (W)
| |
| <prefix>/<name>*/(cmake|CMake)/ (W)
| |
| <prefix>/(share|lib)/cmake/<name>*/ (U)
| |
| <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 paths stored in the CMake user package registry. This can
| |
| be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. Paths are stored
| |
| in the registry when CMake configures a project that invokes
| |
| export(PACKAGE <name>). See the export(PACKAGE) command documentation
| |
| for more details.
| |
| | |
| 7. 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
| |
| | |
| 8. 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.
| |
| | |
| See the cmake_policy() command documentation for discussion of the
| |
| NO_POLICY_SCOPE option.
| |
| | |
| 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 specifies additional subdirectories to check below each
| |
| search path.
| |
| | |
| 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 specifies additional
| |
| subdirectories to check below each search path.
| |
| | |
| 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)
| |
| | |
| 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(loop_var RANGE total)
| |
| foreach(loop_var RANGE start stop [step])
| |
| | |
| 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.
| |
| | |
| foreach(loop_var IN [LISTS [list1 [...]]]
| |
| [ITEMS [item1 [...]]])
| |
| | |
| Iterates over a precise list of items. The LISTS option names
| |
| list-valued variables to be traversed, including empty elements (an
| |
| empty string is a zero-length list). The ITEMS option ends argument
| |
| parsing and includes all arguments following it in the iteration.
| |
| | |
| 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 past the
| |
| last expected argument.
| |
| | |
| See the cmake_policy() command documentation for the behavior of
| |
| policies inside functions.
| |
| | |
| 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 DIRECTORY scope.
| |
| | |
| get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
| |
| | |
| Store a property of directory scope in the named variable. If the
| |
| property is not defined the empty-string is returned. The DIRECTORY
| |
| argument specifies another directory from which to retrieve the
| |
| property value. The specified directory must have already been
| |
| traversed by CMake.
| |
| | |
| get_directory_property(<variable> [DIRECTORY <dir>]
| |
| DEFINITION <var-name>)
| |
| | |
| Get a variable definition from a directory. This form is useful to
| |
| get a variable definition from another directory.
| |
| | |
| get_filename_component
| |
| Get a specific component of a full filename.
| |
| | |
| get_filename_component(VarName FileName
| |
| PATH|ABSOLUTE|NAME|EXT|NAME_WE|REALPATH
| |
| [CACHE])
| |
| | |
| Set VarName to be the path (PATH), file name (NAME), file extension
| |
| (EXT), file name without extension (NAME_WE) of FileName, the full
| |
| path (ABSOLUTE), or the full path with all symlinks resolved
| |
| (REALPATH). 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> |
| |
| CACHE <entry> |
| |
| 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.
| |
| | |
| CACHE scope must name one cache entry.
| |
| | |
| 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 expression in the
| |
| else and endif clause is optional. Long expressions can be used and
| |
| there is a traditional order of precedence. Parenthetical expressions
| |
| are evaluated first followed by unary operators such as EXISTS,
| |
| COMMAND, and DEFINED. 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(<constant>)
| |
| | |
| True if the constant is 1, ON, YES, TRUE, Y, or a non-zero number.
| |
| False if the constant is 0, OFF, NO, FALSE, N, IGNORE, "", or ends in
| |
| the suffix '-NOTFOUND'. Named boolean constants are case-insensitive.
| |
| | |
| if(<variable>)
| |
| | |
| True if the variable's value is not a false constant.
| |
| | |
| if(NOT <expression>)
| |
| | |
| True if the expression is not true.
| |
| | |
| if(<expr1> AND <expr2>)
| |
| | |
| True if both expressions would be considered true individually.
| |
| | |
| if(<expr1> OR <expr2>)
| |
| | |
| True if either expression 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(TARGET target-name)
| |
| | |
| True if the given name is an existing target, built or imported.
| |
| | |
| 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 or variable on the right.
| |
| | |
| if(version1 VERSION_LESS version2)
| |
| if(version1 VERSION_EQUAL version2)
| |
| if(version1 VERSION_GREATER version2)
| |
| | |
| Component-wise integer version number comparison (version format is
| |
| major[.minor[.patch[.tweak]]]).
| |
| | |
| 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.
| |
| | |
| if((expression) AND (expression OR (expression)))
| |
| | |
| The expressions inside the parenthesis are evaluated first and then
| |
| the remaining expression is evaluated as in the previous examples.
| |
| Where there are nested parenthesis the innermost are evaluated as part
| |
| of evaluating the expression that contains them.
| |
| | |
| The if statement was written fairly early in CMake's history and it
| |
| has some convenience features that are worth covering. The if
| |
| statement reduces operations until there is a single remaining value,
| |
| at that point if the case insensitive value is: ON, 1, YES, TRUE, Y it
| |
| returns true, if it is OFF, 0, NO, FALSE, N, NOTFOUND, *-NOTFOUND,
| |
| IGNORE it will return false.
| |
| | |
| This is fairly reasonable. The convenience feature that sometimes
| |
| throws new authors is how CMake handles values that do not match the
| |
| true or false list. Those values are treated as variables and are
| |
| dereferenced even though they do not have the required ${} syntax.
| |
| This means that if you write
| |
| | |
| if (boobah)
| |
| | |
| CMake will treat it as if you wrote
| |
| | |
| if (${boobah})
| |
| | |
| likewise if you write
| |
| | |
| if (fubar AND sol)
| |
| | |
| CMake will conveniently treat it as
| |
| | |
| if ("${fubar}" AND "${sol}")
| |
| | |
| The later is really the correct way to write it, but the former will
| |
| work as well. Only some operations in the if statement have this
| |
| special handling of arguments. The specific details follow:
| |
| | |
| 1) The left hand argument to MATCHES is first checked to see if it is
| |
| a defined variable, if so the variable's value is used, otherwise the
| |
| original value is used.
| |
| | |
| 2) If the left hand argument to MATCHES is missing it returns false
| |
| without error
| |
| | |
| 3) Both left and right hand arguments to LESS GREATER EQUAL are
| |
| independently tested to see if they are defined variables, if so their
| |
| defined values are used otherwise the original value is used.
| |
| | |
| 4) Both left and right hand arguments to STRLESS STREQUAL STRGREATER
| |
| are independently tested to see if they are defined variables, if so
| |
| their defined values are used otherwise the original value is used.
| |
| | |
| 5) Both left and right hand argumemnts to VERSION_LESS VERSION_EQUAL
| |
| VERSION_GREATER are independently tested to see if they are defined
| |
| variables, if so their defined values are used otherwise the original
| |
| value is used.
| |
| | |
| 6) The right hand argument to NOT is tested to see if it is a boolean
| |
| constant, if so the value is used, otherwise it is assumed to be a
| |
| variable and it is dereferenced.
| |
| | |
| 7) The left and right hand arguments to AND OR are independently
| |
| tested to see if they are boolean constants, if so they are used as
| |
| such, otherwise they are assumed to be variables and are dereferenced.
| |
| | |
| | |
| | |
| include
| |
| Read CMake listfile code from the given file.
| |
| | |
| include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
| |
| [NO_POLICY_SCOPE])
| |
| | |
| 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.
| |
| | |
| See the cmake_policy() command documentation for discussion of the
| |
| NO_POLICY_SCOPE option.
| |
| | |
| 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 past 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.
| |
| | |
| See the cmake_policy() command documentation for the behavior of
| |
| policies inside macros.
| |
| | |
| 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([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
| |
| "message to display" ...)
| |
| | |
| The optional keyword determines the type of message:
| |
| | |
| (none) = Important information
| |
| STATUS = Incidental information
| |
| WARNING = CMake Warning, continue processing
| |
| AUTHOR_WARNING = CMake Warning (dev), continue processing
| |
| SEND_ERROR = CMake Error, continue but skip generation
| |
| FATAL_ERROR = CMake Error, stop all processing
| |
| | |
| The CMake command-line tool displays STATUS messages on stdout and all
| |
| other message types on stderr. The CMake GUI displays all messages in
| |
| its log area. The interactive dialogs (ccmake and CMakeSetup) show
| |
| STATUS messages one at a time on a status line and other messages in
| |
| interactive pop-up boxes.
| |
| | |
| CMake Warning and Error message text displays using a simple markup
| |
| language. Non-indented text is formatted in line-wrapped paragraphs
| |
| delimited by newlines. Indented text is considered pre-formatted.
| |
| | |
| 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 file, directory or function.
| |
| | |
| return()
| |
| | |
| Returns from a file, directory or function. When this command is
| |
| encountered in an included file (via include() or find_package()), it
| |
| causes processing of the current file to stop and control is returned
| |
| to the including file. If it is encountered in a file which is not
| |
| included by another file, e.g. a CMakeLists.txt, control is returned
| |
| to the parent directory if there is one. If return is called in a
| |
| function, control is returned to the caller of the function. Note
| |
| that a macro is not a function and does not handle return like a
| |
| function does.
| |
| | |
| separate_arguments
| |
| Parse space-separated arguments into a semicolon-separated list.
| |
| | |
| separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
| |
| | |
| Parses a unix- or windows-style command-line string "<args>" and
| |
| stores a semicolon-separated list of the arguments in <var>. The
| |
| entire command line must be given in one "<args>" argument.
| |
| | |
| The UNIX_COMMAND mode separates arguments by unquoted whitespace. It
| |
| recognizes both single-quote and double-quote pairs. A backslash
| |
| escapes the next literal character (\" is "); there are no special
| |
| escapes (\n is just n).
| |
| | |
| The WINDOWS_COMMAND mode parses a windows command-line using the same
| |
| syntax the runtime library uses to construct argv at startup. It
| |
| separates arguments by whitespace that is not double-quoted.
| |
| Backslashes are literal unless they precede double-quotes. See the
| |
| MSDN article "Parsing C Command-Line Arguments" for details.
| |
| | |
| 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 instead of
| |
| set. See also: the unset() command.
| |
| | |
| 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 ...]] |
| |
| CACHE [entry1 [entry2 ...]]>
| |
| [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.
| |
| | |
| CACHE scope must name zero or more cache existing entries.
| |
| | |
| 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>]
| |
| [RANDOM_SEED <seed>] <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.
| |
| If an integer RANDOM_SEED is given, its value will be used to seed the
| |
| random number generator.
| |
| | |
| 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
| |
| by all regular expression-related commands, including
| |
| e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
| |
| | |
| unset
| |
| Unset a variable, cache variable, or environment variable.
| |
| | |
| unset(<variable> [CACHE])
| |
| | |
| Removes the specified variable causing it to become undefined. If
| |
| CACHE is present then the variable is removed from the cache instead
| |
| of the current scope.
| |
| | |
| <variable> can be an environment variable such as:
| |
| | |
| unset(ENV{LD_LIBRARY_PATH})
| |
| | |
| in which case the variable will be removed from the current
| |
| environment.
| |
| | |
| 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 2000-2009 Kitware, Inc., Insight Software 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.
| |
| | |
| Neither the names of Kitware, Inc., the Insight Software Consortium, nor the
| |
| names of their contributors may be used to endorse or promote products
| |
| derived from this software without specific prior written permission.
| |
| | |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDER 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>
| |
