Changes between Initial Version and Version 1 of CMakeAddExecutable

Timestamp:

Jun 18, 2007, 11:32:37 AM (15 years ago)

Author:

Douglas Gregor

Comment:

Iniitial documentation

CMakeAddExecutable

@@ +1 @@
+= CMake Macro Reference: `boost_add_executable` =
+
+Creates a new executable from source files.
+
+{{{
+boost_add_executable(exename
+                     source1 source2 ...
+                     [COMPILE_FLAGS compileflags]
+                     [feature_COMPILE_FLAGS compileflags]
+                     [LINK_FLAGS linkflags]
+                     [feature_LINK_FLAGS linkflags]
+                     [LINK_LIBS linklibs]
+                     [feature_LINK_LIBS linklibs]
+                     [DEPENDS libdepend1 libdepend2 ...]
+                     [feature]
+                     [NO_INSTALL])
+}}}
+
+where {{{exename}}} is the name of the executable (e.g., "wave"). {{{source1}}},
+{{{source2}}}, etc. are the source files used to build the executable, e.g.,
+cpp.cpp. If no source files are provided, "{{{exename.cpp}}}" will be
+used.
+
+This macro has a variety of options that affect its behavior. In
+several cases, we use the placeholder "feature" in the option name to
+indicate that there are actually several different kinds of options,
+each referring to a different build feature, e.g., shared libraries,
+multi-threaded, debug build, etc. For a complete listing of these
+features, please refer to the page on [wiki:CMakeBuildFeatures CMake
+Build Features].
+
+The options that affect this macro's behavior are:
+
+  COMPILE_FLAGS::
+  Provides additional compilation flags that will be
+  used when building the executable.
+
+  feature_COMPILE_FLAGS:: 
+  Provides additional compilation flags that
+  will be used only when building the executable with the given
+  feature (e.g., {{{SHARED_COMPILE_FLAGS}}} when we're linking against
+  shared libraries). Note that the set of features used to build the
+  executable depends both on the arguments given to
+  {{{boost_add_executable}}} (see the "feature" argument description,
+  below) and on the user's choice of variants to build.
+
+  LINK_FLAGS:: 
+   Provides additional flags that will be passed to the
+  linker when linking the executable. This option should not be used
+  to link in additional libraries; see {{{LINK_LIBS}}} and {{{DEPENDS}}}.
+
+  feature_LINK_FLAGS:: 
+  Provides additional flags that will be passed
+  to the linker when linking the executable with the given feature
+  (e.g., {{{MULTI_THREADED_LINK_FLAGS}}} when we're linking a
+  multi-threaded executable).
+
+  LINK_LIBS:: 
+  Provides additional libraries against which the
+  executable will be linked. For example, one might provide "expat"
+  as options to LINK_LIBS, to state that the executable will link
+  against the expat library binary. Use LINK_LIBS for libraries
+  external to Boost; for Boost libraries, use DEPENDS.
+
+  feature_LINK_LIBS::
+  Provides additional libraries to link against
+  when linking an executable built with the given feature. 
+
+  DEPENDS:: 
+  States that this executable depends on and links against
+  a Boostlibrary. The arguments to DEPENDS should be the unversioned
+  name of the Boost library, such as "boost_filesystem". Like
+  LINK_LIBS, this option states that the executable will link
+  against the stated libraries. Unlike LINK_LIBS, however, DEPENDS
+  takes particular library variants into account, always linking to
+  the appropriate variant of a Boost library. For example, if the
+  {{{MULTI_THREADED}}} feature was requested in the call to
+  boost_add_executable, DEPENDS will ensure that we only link
+  against multi-threaded libraries.
+
+  feature:: 
+  States that the executable should always be built using a
+  given feature, e.g., SHARED linking (against its libraries) or
+  MULTI_THREADED (for multi-threaded builds). If that feature has
+  been turned off by the user, the executable will not build.
+
+  NO_INSTALL:: 
+  Don't install this executable with the rest of Boost.
+
+  OUTPUT_NAME:: 
+  If you want the executable to be generated somewhere
+  other than the binary directory, pass the path (including
+  directory and file name) via the OUTPUT_NAME parameter.
+
+== Example ==
+
+The Boost.Wave library also includes the {{{wave}}} tool, which
+provides a complete C89/C99/C++ preprocessor. It uses the Wave,
+Program Options, Filesystem, and Serialization libraries in Boost and
+is built with the following invocation of {{{boost_add_executable}}}:
+
+{{{
+boost_add_executable(wave cpp.cpp 
+  DEPENDS boost_wave boost_program_options boost_filesystem boost_serialization
+  )
+}}}
+
+This example is from [http://svn.boost.org/svn/boost/sandbox-branches/boost-cmake/boost_1_34_0/tools/wave/CMakeLists.txt tools/wave/CMakeLists.txt].
+
+== Where Defined ==
+This macro is defined in the Boost Core module in [http://svn.boost.org/svn/boost/sandbox-branches/boost-cmake/boost_1_34_0/tools/build/CMake/BoostCore.cmake tools/build/CMake/BoostCore.cmake]