From 847eefe5bfd77777f92ee470c60cf052a67c9ec1 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Sat, 8 Jan 2022 06:08:45 +0000 Subject: [doc][cmake] Convert read-me for the common CMake utils to reST @phosek mentioned others might want it reST for consistency. As I personally do not like Markdown at all and just did the "usual GitHub read-me thing" out of habit, I am more than happy to oblige. Also fix the typos found in the original. Reviewed By: phosek, lebedev.ri Differential Revision: https://reviews.llvm.org/D116524 --- cmake/README.md | 53 -------------------------------------------------- cmake/README.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 53 deletions(-) delete mode 100644 cmake/README.md create mode 100644 cmake/README.rst (limited to 'cmake') diff --git a/cmake/README.md b/cmake/README.md deleted file mode 100644 index e7bd143..0000000 --- a/cmake/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# LLVM Common CMake Utils - -## What goes here - -These are CMake modules to be shared between LLVM projects strictly at build -time. In other words, they must not be included from an installed CMake module, -such as the `Add*.cmake` ones. Modules that are reachable from installed -modules should instead go in `${project}/cmake/modules` of the most upstream -project that use them. - -The advantage of not putting these modules in an existing location like -`llvm/cmake/modules` is two-fold: - -- Since they are not installed, we don't have to worry about any out-of-tree - downstream usage, and thus there is no need for stability. - -- Since they are available as part of the source at build-time, we don't have - to do the usual stand-alone vs combined-build dances, avoiding much - complexity. - -## How to use - -For tools, please do: - -```cmake -if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS) - set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake) -endif() - -# Add path for custom modules. -list(INSERT CMAKE_MODULE_PATH 0 - # project-specific module dirs first - "${LLVM_COMMON_CMAKE_UTILS}/Modules" - ) -``` - -- The `if(NOT DEFINED ...)` guard is there because in combined builds, LLVM - will set this variable. This is useful for legacy builds where projects are - found in `llvm/tools` instead. - -- `INSERT ... 0` ensures these new entries are prepended to the front of the - module path, so nothing might shadow them by mistake. - -If runtime libs, we skip the `if(NOT DEFINED` part: - -```cmake -set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake) - -... # same as before -``` - -If `llvm/tools` legacy-style combined builds are deprecated, we should then -skip it everywhere, bringing the tools and runtimes boilerplate back in line. diff --git a/cmake/README.rst b/cmake/README.rst new file mode 100644 index 0000000..e28409a --- /dev/null +++ b/cmake/README.rst @@ -0,0 +1,59 @@ +======================= +LLVM Common CMake Utils +======================= + +What goes here +-------------- + +These are CMake modules to be shared between LLVM projects strictly at build +time. In other words, they must not be included from an installed CMake module, +such as the ``Add*.cmake`` ones. Modules that are reachable from installed +modules should instead go in ``${project}/cmake/modules`` of the most upstream +project that uses them. + +The advantage of not putting these modules in an existing location like +``llvm/cmake/modules`` is two-fold: + +- Since they are not installed, we don't have to worry about any out-of-tree + downstream usage, and thus there is no need for stability. + +- Since they are available as part of the source at build-time, we don't have + to do the usual stand-alone vs combined-build dances, avoiding much + complexity. + +How to use +---------- + +For tools, please do: + +.. code-block:: cmake + + if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS) + set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake) + endif() + + # Add path for custom modules. + list(INSERT CMAKE_MODULE_PATH 0 + # project-specific module dirs first + "${LLVM_COMMON_CMAKE_UTILS}/Modules" + ) + +Notes: + +- The ``if(NOT DEFINED ...)`` guard is there because in combined builds, LLVM + will set this variable. This is useful for legacy builds where projects are + found in ``llvm/tools`` instead. + +- ``INSERT ... 0`` ensures these new entries are prepended to the front of the + module path, so nothing might shadow them by mistake. + +For runtime libs, we skip the ``if(NOT DEFINED`` part: + +.. code-block:: cmake + + set(LLVM_COMMON_CMAKE_UTILS ${LLVM_COMMON_CMAKE_UTILS}/../cmake) + + ... # same as before + +If ``llvm/tools`` legacy-style combined builds are deprecated, we should then +skip it everywhere, bringing the tools and runtimes boilerplate back in line. -- cgit v1.1