1======================= 2LLVM Common CMake Utils 3======================= 4 5What goes here 6-------------- 7 8These are CMake modules to be shared between LLVM projects strictly at build 9time. In other words, they must not be included from an installed CMake module, 10such as the ``Add*.cmake`` ones. Modules that are reachable from installed 11modules should instead go in ``${project}/cmake/modules`` of the most upstream 12project that uses them. 13 14The 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 24How to use 25---------- 26 27For 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 41Notes: 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 50For 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 58If ``llvm/tools`` legacy-style combined builds are deprecated, we should then 59skip it everywhere, bringing the tools and runtimes boilerplate back in line. 60