Help/command/add_subdirectory.rst

   1 add_subdirectory
   2 ----------------
   3
   4 Add a subdirectory to the build.
   5
   6 .. code-block:: cmake
   7
   8   add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
   9
  10 Adds a subdirectory to the build.  The source_dir specifies the
  11 directory in which the source CMakeLists.txt and code files are
  12 located.  If it is a relative path it will be evaluated with respect
  13 to the current directory (the typical usage), but it may also be an
  14 absolute path.  The ``binary_dir`` specifies the directory in which to
  15 place the output files.  If it is a relative path it will be evaluated
  16 with respect to the current output directory, but it may also be an
  17 absolute path.  If ``binary_dir`` is not specified, the value of
  18 ``source_dir``, before expanding any relative path, will be used (the
  19 typical usage).  The CMakeLists.txt file in the specified source
  20 directory will be processed immediately by CMake before processing in
  21 the current input file continues beyond this command.
  22
  23 If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the
  24 subdirectory will not be included in the ``ALL`` target of the parent
  25 directory by default, and will be excluded from IDE project files.
  26 Users must explicitly build targets in the subdirectory.  This is
  27 meant for use when the subdirectory contains a separate part of the
  28 project that is useful but not necessary, such as a set of examples.
  29 Typically the subdirectory should contain its own :command:`project`
  30 command invocation so that a full build system will be generated in the
  31 subdirectory (such as a VS IDE solution file).  Note that inter-target
  32 dependencies supersede this exclusion.  If a target built by the
  33 parent project depends on a target in the subdirectory, the dependee
  34 target will be included in the parent project build system to satisfy
  35 the dependency.