replica
/
hanchenye-llvm-project
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[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
This commit is contained in:
John Ericson 2022-01-08 06:08:45 +00:00
parent 84654f2733
commit 847eefe5bf
2 changed files with 59 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
cmake/README.md
View File

@ -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.

59
cmake/README.rst Normal file
View File

@ -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.