[llvm-branch-commits] [llvm] [docs] Finish MyST migration for selected LLVM docs (PR #214618)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Fri Aug 7 11:58:33 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-backend-risc-v
Author: Reid Kleckner (rnk)
<details>
<summary>Changes</summary>
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #<!-- -->214616 , which will be a standalone commit that
renames *.rst -> *.md before this PR lands for history preservation purposes.
This was prepared with rst2myst plus LLM-assisted cleanup. I paged through all the generated HTML looking for migration artifacts, and all of the differences I could find appear to be formatting error corrections. Please spot check my work and approve if it looks good. You can use the HTML links below to confirm it renders properly.
-----
Before/after validation links:
| Source file | Before HTML | After HTML |
| --- | --- | --- |
| `llvm/docs/Benchmarking.md` | [before](https://llvm.org/docs/Benchmarking.html) | [after](https://llvmdocs.staging.reidkleckner.dev/Benchmarking.html) |
| `llvm/docs/CMakePrimer.md` | [before](https://llvm.org/docs/CMakePrimer.html) | [after](https://llvmdocs.staging.reidkleckner.dev/CMakePrimer.html) |
| `llvm/docs/CodeOfConduct.md` | [before](https://llvm.org/docs/CodeOfConduct.html) | [after](https://llvmdocs.staging.reidkleckner.dev/CodeOfConduct.html) |
| `llvm/docs/DirectXUsage.md` | [before](https://llvm.org/docs/DirectXUsage.html) | [after](https://llvmdocs.staging.reidkleckner.dev/DirectXUsage.html) |
| `llvm/docs/FatLTO.md` | [before](https://llvm.org/docs/FatLTO.html) | [after](https://llvmdocs.staging.reidkleckner.dev/FatLTO.html) |
| `llvm/docs/HowToUseAttributes.md` | [before](https://llvm.org/docs/HowToUseAttributes.html) | [after](https://llvmdocs.staging.reidkleckner.dev/HowToUseAttributes.html) |
| `llvm/docs/LFI.md` | [before](https://llvm.org/docs/LFI.html) | [after](https://llvmdocs.staging.reidkleckner.dev/LFI.html) |
| `llvm/docs/MisExpect.md` | [before](https://llvm.org/docs/MisExpect.html) | [after](https://llvmdocs.staging.reidkleckner.dev/MisExpect.html) |
| `llvm/docs/OpaquePointers.md` | [before](https://llvm.org/docs/OpaquePointers.html) | [after](https://llvmdocs.staging.reidkleckner.dev/OpaquePointers.html) |
| `llvm/docs/OptBisect.md` | [before](https://llvm.org/docs/OptBisect.html) | [after](https://llvmdocs.staging.reidkleckner.dev/OptBisect.html) |
| `llvm/docs/PDB/index.md` | [before](https://llvm.org/docs/PDB/index.html) | [after](https://llvmdocs.staging.reidkleckner.dev/PDB/index.html) |
| `llvm/docs/RISCV/RISCVVCIX.md` | [before](https://llvm.org/docs/RISCV/RISCVVCIX.html) | [after](https://llvmdocs.staging.reidkleckner.dev/RISCV/RISCVVCIX.html) |
| `llvm/docs/RISCV/RISCVVectorExtension.md` | [before](https://llvm.org/docs/RISCV/RISCVVectorExtension.html) | [after](https://llvmdocs.staging.reidkleckner.dev/RISCV/RISCVVectorExtension.html) |
| `llvm/docs/RISCVUsage.md` | [before](https://llvm.org/docs/RISCVUsage.html) | [after](https://llvmdocs.staging.reidkleckner.dev/RISCVUsage.html) |
| `llvm/docs/ReportingGuide.md` | [before](https://llvm.org/docs/ReportingGuide.html) | [after](https://llvmdocs.staging.reidkleckner.dev/ReportingGuide.html) |
| `llvm/docs/ResponseGuide.md` | [before](https://llvm.org/docs/ResponseGuide.html) | [after](https://llvmdocs.staging.reidkleckner.dev/ResponseGuide.html) |
| `llvm/docs/SymbolizerMarkupFormat.md` | [before](https://llvm.org/docs/SymbolizerMarkupFormat.html) | [after](https://llvmdocs.staging.reidkleckner.dev/SymbolizerMarkupFormat.html) |
| `llvm/docs/TableGenFundamentals.md` | [before](https://llvm.org/docs/TableGenFundamentals.html) | [after](https://llvmdocs.staging.reidkleckner.dev/TableGenFundamentals.html) |
| `llvm/docs/Telemetry.md` | [before](https://llvm.org/docs/Telemetry.html) | [after](https://llvmdocs.staging.reidkleckner.dev/Telemetry.html) |
| `llvm/docs/yaml2obj.md` | [before](https://llvm.org/docs/yaml2obj.html) | [after](https://llvmdocs.staging.reidkleckner.dev/yaml2obj.html) |
---
Patch is 401.24 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/214618.diff
20 Files Affected:
- (modified) llvm/docs/Benchmarking.md (+51-44)
- (modified) llvm/docs/CMakePrimer.md (+219-240)
- (modified) llvm/docs/CodeOfConduct.md (+79-89)
- (modified) llvm/docs/DirectXUsage.md (+55-61)
- (modified) llvm/docs/FatLTO.md (+63-76)
- (modified) llvm/docs/HowToUseAttributes.md (+39-45)
- (modified) llvm/docs/LFI.md (+528-479)
- (modified) llvm/docs/MisExpect.md (+26-38)
- (modified) llvm/docs/OpaquePointers.md (+109-119)
- (modified) llvm/docs/OptBisect.md (+104-115)
- (modified) llvm/docs/PDB/index.md (+144-123)
- (modified) llvm/docs/RISCV/RISCVVCIX.md (+172-178)
- (modified) llvm/docs/RISCV/RISCVVectorExtension.md (+202-232)
- (modified) llvm/docs/RISCVUsage.md (+558-484)
- (modified) llvm/docs/ReportingGuide.md (+49-64)
- (modified) llvm/docs/ResponseGuide.md (+110-135)
- (modified) llvm/docs/SymbolizerMarkupFormat.md (+153-145)
- (modified) llvm/docs/TableGenFundamentals.md (+4-6)
- (modified) llvm/docs/Telemetry.md (+179-187)
- (modified) llvm/docs/yaml2obj.md (+256-258)
``````````diff
diff --git a/llvm/docs/Benchmarking.md b/llvm/docs/Benchmarking.md
index d168965114459..4edf5ada2f47b 100644
--- a/llvm/docs/Benchmarking.md
+++ b/llvm/docs/Benchmarking.md
@@ -1,87 +1,94 @@
-==================================
-Benchmarking tips
-==================================
+# Benchmarking tips
-
-Introduction
-============
+## Introduction
For benchmarking a patch we want to reduce all possible sources of
noise as much as possible. How to do that is very OS dependent.
Note that low noise is required, but not sufficient. It does not
exclude measurement bias.
-See `"Producing Wrong Data Without Doing Anything Obviously Wrong!" by Mytkowicz, Diwan, Hauswith and Sweeney (ASPLOS 2009) <https://users.cs.northwestern.edu/~robby/courses/322-2013-spring/mytkowicz-wrong-data.pdf>`_
+See ["Producing Wrong Data Without Doing Anything Obviously Wrong!" by Mytkowicz, Diwan, Hauswith and Sweeney (ASPLOS 2009)](https://users.cs.northwestern.edu/~robby/courses/322-2013-spring/mytkowicz-wrong-data.pdf)
for example.
-General
-================================
+## General
-* Use a high-resolution timer, e.g., perf under Linux.
+- Use a high-resolution timer, e.g., perf under Linux.
-* Run the benchmark multiple times to be able to recognize noise.
+- Run the benchmark multiple times to be able to recognize noise.
-* Disable as many processes or services as possible on the target system.
+- Disable as many processes or services as possible on the target system.
-* Disable frequency scaling, Turbo Boost and address space
+- Disable frequency scaling, Turbo Boost and address space
randomization (see OS-specific section).
-* Use static linking if the OS supports it. That avoids any variation that
+- Use static linking if the OS supports it. That avoids any variation that
might be introduced by loading dynamic libraries. This can be done
- by passing ``-DLLVM_BUILD_STATIC=ON`` to CMake.
+ by passing `-DLLVM_BUILD_STATIC=ON` to CMake.
-* Try to avoid storage. On some systems, you can use tmpfs. Putting the
+- Try to avoid storage. On some systems, you can use tmpfs. Putting the
program, inputs and outputs on tmpfs avoids touching a real storage
system, which can have a pretty big variability.
- To mount it (on Linux and FreeBSD at least)::
+ To mount it (on Linux and FreeBSD at least):
- mount -t tmpfs -o size=<XX>g none dir_to_mount
+ ```
+ mount -t tmpfs -o size=<XX>g none dir_to_mount
+ ```
-Linux
-=====
+## Linux
-* Disable address space randomization::
+- Disable address space randomization:
- echo 0 > /proc/sys/kernel/randomize_va_space
+ ```
+ echo 0 > /proc/sys/kernel/randomize_va_space
+ ```
-* Set scaling_governor to performance::
+- Set scaling_governor to performance:
- for i in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
- do
- echo performance > $i
- done
+ ```
+ for i in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
+ do
+ echo performance > $i
+ done
+ ```
-* Use https://github.com/lpechacek/cpuset to reserve CPU cores for just the
+- Use <https://github.com/lpechacek/cpuset> to reserve CPU cores for just the
program you are benchmarking. If using perf, leave at least 2 cores
- so that perf runs in one and your program in another::
+ so that perf runs in one and your program in another:
- cset shield -c N1,N2 -k on
+ ```
+ cset shield -c N1,N2 -k on
+ ```
- This will move all threads out of N1 and N2. The ``-k on`` means
+ This will move all threads out of N1 and N2. The `-k on` means
that even kernel threads are moved out.
-* Disable the SMT pair of the cpus you will use for the benchmark. The
+- Disable the SMT pair of the cpus you will use for the benchmark. The
pair of cpu N can be found in
- ``/sys/devices/system/cpu/cpuN/topology/thread_siblings_list`` and
- disabled with::
-
- echo 0 > /sys/devices/system/cpu/cpuX/online
+ `/sys/devices/system/cpu/cpuN/topology/thread_siblings_list` and
+ disabled with:
+ ```
+ echo 0 > /sys/devices/system/cpu/cpuX/online
+ ```
-* Run the program with::
+- Run the program with:
- cset shield --exec -- perf stat -r 10 <cmd>
+ ```
+ cset shield --exec -- perf stat -r 10 <cmd>
+ ```
- This will run the command after ``--`` in the isolated CPU cores. The
- particular perf command runs the ``<cmd>`` 10 times and reports
+ This will run the command after `--` in the isolated CPU cores. The
+ particular perf command runs the `<cmd>` 10 times and reports
statistics.
With these in place you can expect perf variations of less than 0.1%.
-Linux Intel
------------
+### Linux Intel
+
+- Disable Turbo Boost:
-* Disable Turbo Boost::
+ ```
+ echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo
+ ```
- echo 1 > /sys/devices/system/cpu/intel_pstate/no_turbo
diff --git a/llvm/docs/CMakePrimer.md b/llvm/docs/CMakePrimer.md
index ce4604b0d5d5a..6f954967441c5 100644
--- a/llvm/docs/CMakePrimer.md
+++ b/llvm/docs/CMakePrimer.md
@@ -1,28 +1,22 @@
-============
-CMake Primer
-============
+# CMake Primer
+:::{warning}
+Disclaimer: This documentation is written by LLVM project contributors *not*
+anyone affiliated with the CMake project. This document may contain
+inaccurate terminology, phrasing, or technical details. It is provided with
+the best intentions.
+:::
-.. warning::
- Disclaimer: This documentation is written by LLVM project contributors `not`
- anyone affiliated with the CMake project. This document may contain
- inaccurate terminology, phrasing, or technical details. It is provided with
- the best intentions.
-
-
-Introduction
-============
+## Introduction
The LLVM project and many of the core projects built on LLVM build using CMake.
This document aims to provide a brief overview of CMake for developers modifying
LLVM projects or building their own projects on top of LLVM.
The official CMake language reference is available in the cmake-language
-manpage and `cmake-language online documentation
-<https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html>`_.
+manpage and [cmake-language online documentation](https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html).
-10,000 ft View
-==============
+## 10,000 ft View
CMake is a tool that reads script files in its own language that describe how a
software project builds. As CMake evaluates the scripts, it constructs an
@@ -38,11 +32,10 @@ because it allows the build system to skip long-running checks during
incremental development. CMake caching also has some drawbacks, but that will be
discussed later.
-Scripting Overview
-==================
+## Scripting Overview
CMake's scripting language has a very simple grammar. Every language construct
-is a command that matches the pattern _name_(_args_). Commands come in three
+is a command that matches the pattern `_name_(_args_)`. Commands come in three
primary types: language-defined (commands implemented in C++ in CMake), defined
functions, and defined macros. The CMake distribution also contains a suite of
CMake modules that contain definitions for useful functionality.
@@ -50,33 +43,31 @@ CMake modules that contain definitions for useful functionality.
The example below is the full CMake build for building a C++ "Hello World"
program. The example uses only CMake language-defined functions.
-.. code-block:: cmake
+```cmake
+cmake_minimum_required(VERSION 3.20.0)
+project(HelloWorld)
+add_executable(HelloWorld HelloWorld.cpp)
+```
- cmake_minimum_required(VERSION 3.20.0)
- project(HelloWorld)
- add_executable(HelloWorld HelloWorld.cpp)
-
-The CMake language provides control flow constructs in the form of ``foreach`` loops
-and ``if`` blocks. To make the example above more complicated you could add an if
+The CMake language provides control flow constructs in the form of `foreach` loops
+and `if` blocks. To make the example above more complicated you could add an if
block to define "APPLE" when targeting Apple platforms:
-.. code-block:: cmake
-
- cmake_minimum_required(VERSION 3.20.0)
- project(HelloWorld)
- add_executable(HelloWorld HelloWorld.cpp)
- if(APPLE)
- target_compile_definitions(HelloWorld PUBLIC APPLE)
- endif()
+```cmake
+cmake_minimum_required(VERSION 3.20.0)
+project(HelloWorld)
+add_executable(HelloWorld HelloWorld.cpp)
+if(APPLE)
+ target_compile_definitions(HelloWorld PUBLIC APPLE)
+endif()
+```
-Variables, Types, and Scope
-===========================
+## Variables, Types, and Scope
-Dereferencing
--------------
+### Dereferencing
In CMake, variables are "stringly" typed. All variables are represented as
-strings throughout evaluation. Wrapping a variable in ``${}`` dereferences it
+strings throughout evaluation. Wrapping a variable in `${}` dereferences it
and results in a literal substitution of the name for the value. CMake refers to
this as "variable evaluation" in their documentation. Dereferences are performed
*before* the command being called receives the arguments. This means
@@ -86,11 +77,11 @@ command.
Variable dereferences can be nested and be used to model complex data. For
example:
-.. code-block:: cmake
-
- set(var_name var1)
- set(${var_name} foo) # same as "set(var1 foo)"
- set(${${var_name}}_var bar) # same as "set(foo_var bar)"
+```cmake
+set(var_name var1)
+set(${var_name} foo) # same as "set(var1 foo)"
+set(${${var_name}}_var bar) # same as "set(foo_var bar)"
+```
Dereferencing an unset variable results in an empty expansion. It is a common
pattern in CMake to conditionally set variables knowing that it will be used in
@@ -99,79 +90,74 @@ the LLVM CMake build system.
An example of variable empty expansion is:
-.. code-block:: cmake
-
- if(APPLE)
- set(extra_sources Apple.cpp)
- endif()
- add_executable(HelloWorld HelloWorld.cpp ${extra_sources})
+```cmake
+if(APPLE)
+ set(extra_sources Apple.cpp)
+endif()
+add_executable(HelloWorld HelloWorld.cpp ${extra_sources})
+```
-In this example the ``extra_sources`` variable is only defined if you're
-targeting an Apple platform. For all other targets the ``extra_sources`` will be
+In this example the `extra_sources` variable is only defined if you're
+targeting an Apple platform. For all other targets the `extra_sources` will be
evaluated as empty before add_executable is given its arguments.
-Lists
------
+### Lists
In CMake, lists are semicolon-delimited strings, and it is strongly advised that
you avoid using semicolons in lists; it doesn't go smoothly. A few examples of
defining lists:
-.. code-block:: cmake
+```cmake
+# Creates a list with members a, b, c, and d
+set(my_list a b c d)
+set(my_list "a;b;c;d")
- # Creates a list with members a, b, c, and d
- set(my_list a b c d)
- set(my_list "a;b;c;d")
+# Creates a string "a b c d"
+set(my_string "a b c d")
+```
- # Creates a string "a b c d"
- set(my_string "a b c d")
-
-Lists of Lists
---------------
+### Lists of Lists
One of the more complicated patterns in CMake is lists of lists. Because a list
cannot contain an element with a semicolon to construct a list of lists you
make a list of variable names that refer to other lists. For example:
-.. code-block:: cmake
-
- set(list_of_lists a b c)
- set(a 1 2 3)
- set(b 4 5 6)
- set(c 7 8 9)
+```cmake
+set(list_of_lists a b c)
+set(a 1 2 3)
+set(b 4 5 6)
+set(c 7 8 9)
+```
With this layout you can iterate through the list of lists printing each value
with the following code:
-.. code-block:: cmake
-
- foreach(list_name IN LISTS list_of_lists)
- foreach(value IN LISTS ${list_name})
- message(${value})
- endforeach()
- endforeach()
+```cmake
+foreach(list_name IN LISTS list_of_lists)
+ foreach(value IN LISTS ${list_name})
+ message(${value})
+ endforeach()
+endforeach()
+```
You'll notice that the inner foreach loop's list is doubly dereferenced. This is
-because the first dereference turns ``list_name`` into the name of the sub-list
+because the first dereference turns `list_name` into the name of the sub-list
(a, b, or c in the example), then the second dereference is to get the value of
the list.
This pattern is used throughout CMake, the most common example is the compiler
flags options, which CMake refers to using the following variable expansions:
-``CMAKE_${LANGUAGE}_FLAGS`` and ``CMAKE_${LANGUAGE}_FLAGS_${CMAKE_BUILD_TYPE}``.
+`CMAKE_${LANGUAGE}_FLAGS` and `CMAKE_${LANGUAGE}_FLAGS_${CMAKE_BUILD_TYPE}`.
-Other Types
------------
+### Other Types
Variables that are cached or specified on the command line can have types
associated with them. The variable's type is used by CMake's UI tool to display
the right input field. A variable's type generally doesn't impact evaluation;
-however, CMake does have special handling for some variables such as ``PATH``.
-You can read more about the special handling in `CMake's set documentation
-<https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry>`_.
+however, CMake does have special handling for some variables such as `PATH`.
+You can read more about the special handling in [CMake's set documentation](https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry).
-Scope
------
+### Scope
CMake inherently has a directory-based scoping. Setting a variable in a
CMakeLists file, will set the variable for that file, and all subdirectories.
@@ -181,135 +167,132 @@ set in the scope they are included from, and all subdirectories.
When a variable that is already set is set again in a subdirectory it overrides
the value in that scope and any deeper subdirectories.
-The CMake set command provides two scope-related options. ``PARENT_SCOPE`` sets a
-variable into the parent scope, and not the current scope. The ``CACHE`` option sets
+The CMake set command provides two scope-related options. `PARENT_SCOPE` sets a
+variable into the parent scope, and not the current scope. The `CACHE` option sets
the variable in the CMakeCache, which results in it being set in all scopes. The
-``CACHE`` option will not set a variable that already exists in the ``CACHE`` unless the
-``FORCE`` option is specified.
+`CACHE` option will not set a variable that already exists in the `CACHE` unless the
+`FORCE` option is specified.
In addition to directory-based scope, CMake functions also have their own scope.
This means variables set inside functions do not bleed into the parent scope.
This is not true of macros, and it is for this reason LLVM prefers functions
over macros whenever reasonable.
-.. note::
- Unlike C-based languages, CMake's loop and control flow blocks do not have
- their own scopes.
+:::{note}
+Unlike C-based languages, CMake's loop and control flow blocks do not have
+their own scopes.
+:::
-Control Flow
-============
+## Control Flow
CMake features the same basic control flow constructs you would expect in any
scripting language, but there are a few quirks because, as with everything in
CMake, control flow constructs are commands.
-If, ElseIf, Else
-----------------
+### If, ElseIf, Else
-.. note::
- For the full documentation on the CMake if command go
- `here <https://cmake.org/cmake/help/v3.4/command/if.html>`_. That resource is
- far more complete.
+:::{note}
+For the full documentation on the CMake if command go
+[here](https://cmake.org/cmake/help/v3.4/command/if.html). That resource is
+far more complete.
+:::
-In general, CMake ``if`` blocks work the way you'd expect:
+In general, CMake `if` blocks work the way you'd expect:
-.. code-block:: cmake
+```cmake
+if(<condition>)
+ message("do stuff")
+elseif(<condition>)
+ message("do other stuff")
+else()
+ message("do other other stuff")
+endif()
+```
- if(<condition>)
- message("do stuff")
- elseif(<condition>)
- message("do other stuff")
- else()
- message("do other other stuff")
- endif()
-
-The single most important thing to know about CMake's ``if`` blocks coming from a C
+The single most important thing to know about CMake's `if` blocks coming from a C
background is that they do not have their own scope. Variables set inside
-conditional blocks persist after the ``endif()``.
-
-Loops
------
+conditional blocks persist after the `endif()`.
-The most common form of the CMake ``foreach`` block is:
+### Loops
-.. code-block:: cmake
+The most common form of the CMake `foreach` block is:
- foreach(var ...)
- message("do stuff")
- endforeach()
+```cmake
+foreach(var ...)
+ message("do stuff")
+endforeach()
+```
-The variable argument portion of the ``foreach`` block can contain dereferenced
+The variable argument portion of the `foreach` block can contain dereferenced
lists, values to iterate, or a mix of both:
-.. code-block:: cmake
-
- foreach(var foo bar baz)
- message(${var})
- endforeach()
- # prints:
- # foo
- # bar
- # baz
-
- set(my_list 1 2 3)
- foreach(var ${my_list})
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
-
- foreach(var ${my_list} out_of_bounds)
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
- # out_of_bounds
+```cmake
+foreach(var foo bar baz)
+ message(${var})
+endforeach()
+# prints:
+# foo
+# bar
+# baz
+
+set(my_list 1 2 3)
+foreach(var ${my_list})
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+
+foreach(var ${my_list} out_of_bounds)
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+# out_of_bounds
+```
There is also a more modern CMake foreach syntax. The code below is equivalent
to the code above:
-.. code-block:: cmake
-
- foreach(var IN ITEMS foo bar baz)
- message(${var})
- endforeach()
- # prints:
- # foo
- # bar
- # baz
-
- set(my_list 1 2 3)
- foreach(var IN LISTS my_list)
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
-
- foreach(var IN LISTS my_list ITEMS out_of_bounds)
- message(${var})
- endforeach()
- # prints:
- # 1
- # 2
- # 3
- # out_of_bounds
+```cmake
+foreach(var IN ITEMS foo bar baz)
+ message(${var})
+endforeach()
+# prints:
+# foo
+# bar
+# baz
+
+set(my_list 1 2 3)
+foreach(var IN LISTS my_list)
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+
+foreach(var IN LISTS my_list ITEMS out_of_bounds)
+ message(${var})
+endforeach()
+# prints:
+# 1
+# 2
+# 3
+# out_of_bounds
+```
Similar to the conditional statements, these generally behave how you would
expect, and they do not have their own scope.
-CMake also supports ``while`` loops, although they are not widely used in LLVM.
+CMake also supports `while` loops, although they are not widely used in LLVM.
-Modules, Functions and Macros
-=============================
+## Modules, Functions and Macros
-Modules
--------
+### Modules
Modules are CMake's vehicle for enabling code reuse. CMake modules are just
CMake script files. They can contain code to execute on include as well as
@@ -324,46 +307,44 @@ modules are the fundamental pieces needed to build LLVM-based projects with
CMake. We also rely on modules as a way of organizing the build system's
functionality for maintainability and reuse within LLVM projects.
-Argument Handling
------------------
+### Argument Handling
When defining a CMake command handling arguments is very useful. The examples
-in this section will all use the CMake ``function`` block, but this also applies
-to the ``macro`` block as well.
+in this section will all use the CMake `function` block, but this also applies
+to the `macro` block as well.
CMake commands can have named arguments that are required at every call site. In
addition, all commands will implicitly accept a variable number of extra
arguments (In C parlance, all commands are varargs functions). When a command is
invoked with extra arguments (beyond the named ones) CMake will store the full
-list of arguments (both named and unnamed) in a list named ``ARGV``, and the
-sublist of unnamed arguments in ``ARGN``. Below is a trivial example of
-providing a wrapper function for CMake's built in function ``add_dependencies``.
-
-.. code-block:: cmake
+list of arguments (both named and unnamed) in a list named `ARGV`, and the
+sublist of unnamed arguments in `ARGN`. Below is a trivial example of
+providing a wrapper function for CMake's built in function `add_dependencies`.
- function(add_deps target)
- add_dependencies(${target} ${ARGN})
- endfunc...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/214618
More information about the llvm-branch-commits
mailing list