cmake/README.rst

   1 =======================
   2 LLVM Common CMake Utils
   3 =======================
   4
   5 What goes here
   6 --------------
   7
   8 These are CMake modules to be shared between LLVM projects strictly at build
   9 time. In other words, they must not be included from an installed CMake module,
  10 such as the ``Add*.cmake`` ones. Modules that are reachable from installed
  11 modules should instead go in ``${project}/cmake/modules`` of the most upstream
  12 project that uses them.
  13
  14 The advantage of not putting these modules in an existing location like
  15 ``llvm/cmake/modules`` is two-fold:
  16
  17 - Since they are not installed, we don't have to worry about any out-of-tree
  18   downstream usage, and thus there is no need for stability.
  19
  20 - Since they are available as part of the source at build-time, we don't have
  21   to do the usual stand-alone vs combined-build dances, avoiding much
  22   complexity.
  23
  24 How to use
  25 ----------
  26
  27 For tools, please do:
  28
  29 .. code-block:: cmake
  30
  31   if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS)
  32     set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
  33   endif()
  34
  35   # Add path for custom modules.
  36   list(INSERT CMAKE_MODULE_PATH 0
  37     # project-specific module dirs first
  38     "${LLVM_COMMON_CMAKE_UTILS}/Modules"
  39     )
  40
  41 Notes:
  42
  43 - The ``if(NOT DEFINED ...)`` guard is there because in combined builds, LLVM
  44   will set this variable.  This is useful for legacy builds where projects are
  45   found in ``llvm/tools`` instead.
  46
  47 - ``INSERT ... 0`` ensures these new entries are prepended to the front of the
  48   module path, so nothing might shadow them by mistake.
  49
  50 For runtime libs, we skip the ``if(NOT DEFINED`` part:
  51
  52 .. code-block:: cmake
  53
  54   set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
  55
  56   ... # same as before
  57
  58 If ``llvm/tools`` legacy-style combined builds are deprecated, we should then
  59 skip it everywhere, bringing the tools and runtimes boilerplate back in line.