1 files changed, 72 insertions, 0 deletions
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
new file mode 100644
index 0000000000..224c67b45d
--- /dev/null
+++ b/Help/command/try_compile.rst
@@ -0,0 +1,72 @@
+try_compile
+-----------
+
+Try building some code.
+
+::
+
+  try_compile(RESULT_VAR <bindir> <srcdir>
+              <projectName> [targetName] [CMAKE_FLAGS flags...]
+              [OUTPUT_VARIABLE <var>])
+
+Try building a project.  In this form, srcdir should contain a
+complete CMake project with a CMakeLists.txt file and all sources.
+The bindir and srcdir will not be deleted after this command is run.
+Specify targetName to build a specific target instead of the 'all' or
+'ALL_BUILD' target.
+
+::
+
+  try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
+              [CMAKE_FLAGS flags...]
+              [COMPILE_DEFINITIONS flags...]
+              [LINK_LIBRARIES libs...]
+              [OUTPUT_VARIABLE <var>]
+              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
+
+Try building an executable from one or more source files.  In this
+form the user need only supply one or more source files that include a
+definition for 'main'.  CMake will create a CMakeLists.txt file to
+build the source(s) as an executable.  Specify COPY_FILE to get a copy
+of the linked executable at the given fileName and optionally
+COPY_FILE_ERROR to capture any error.
+
+In this version all files in bindir/CMakeFiles/CMakeTmp will be
+cleaned automatically.  For debugging, --debug-trycompile can be
+passed to cmake to avoid this clean.  However, multiple sequential
+try_compile operations reuse this single output directory.  If you use
+--debug-trycompile, you can only debug one try_compile call at a time.
+The recommended procedure is to protect all try_compile calls in your
+project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake
+all the way through once, then delete the cache entry associated with
+the try_compile call of interest, and then re-run cmake again with
+--debug-trycompile.
+
+Some extra flags that can be included are, INCLUDE_DIRECTORIES,
+LINK_DIRECTORIES, and LINK_LIBRARIES.  COMPILE_DEFINITIONS are
+-Ddefinition that will be passed to the compile line.
+
+The srcfile signature also accepts a LINK_LIBRARIES argument which may
+contain a list of libraries or IMPORTED targets which will be linked
+to in the generated project.  If LINK_LIBRARIES is specified as a
+parameter to try_compile, then any LINK_LIBRARIES passed as
+CMAKE_FLAGS will be ignored.
+
+try_compile creates a CMakeList.txt file on the fly that looks like
+this:
+
+::
+
+  add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
+  include_directories(${INCLUDE_DIRECTORIES})
+  link_directories(${LINK_DIRECTORIES})
+  add_executable(cmTryCompileExec sources)
+  target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
+
+In both versions of the command, if OUTPUT_VARIABLE is specified, then
+the output from the build process is stored in the given variable.
+The success or failure of the try_compile, i.e.  TRUE or FALSE
+respectively, is returned in RESULT_VAR.  CMAKE_FLAGS can be used to
+pass -DVAR:TYPE=VALUE flags to the cmake that is run during the build.
+Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
+configuration.