https://github.com/rnk created https://github.com/llvm/llvm-project/pull/214921
Myst has an extension, [colon_fence](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence), that we enable in our docs. There are many Markdown-aware tools out there that know to interpret triple backtick as a code block fence, so they highlight them as pre-formatted text. Colon fences are an unrecognized Myst extension, and if the Sphinx directive contains a block of markdown formatted text, that's the desired behavior. Therefore, at some point during the migration, I started using them. However, I didn't document this guideline, and I didn't apply it consistently to the early docs. This PR does that: documents the guideline, and applies it to our docs. After this change: ``` ❯ rg '```\{(option|note|todo|admonition|warning)\}' | cut -d / -f 1 | sort | uniq -c 72 clang-tools-extra 5 flang 2 lldb ``` The generated HTML was byte-identical. I plan to leave clang-tools-extra untouched since there are PRs in flight. LLM-assisted >From b9f4d1d607eb4654be062b686c3ce5c327bbaab7 Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Sat, 8 Aug 2026 02:37:26 +0000 Subject: [PATCH 1/3] [docs] Recommend colon fences for rich MyST directives --- llvm/docs/SphinxQuickstartTemplate.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/llvm/docs/SphinxQuickstartTemplate.md b/llvm/docs/SphinxQuickstartTemplate.md index 1df31aee800d4..bc9afc686d7f5 100644 --- a/llvm/docs/SphinxQuickstartTemplate.md +++ b/llvm/docs/SphinxQuickstartTemplate.md @@ -160,6 +160,29 @@ without any syntax highlighting like this: ``` +## Sphinx Directives + +Sphinx directives that contain rich, formatted Markdown content should use +[colon fences][colon_fence] instead of backtick fences. This keeps directive +containers visually distinct from code blocks while still allowing normal +Markdown markup inside the directive. + +:::{note} +Use colon fences for rich directives such as `{note}`, `{warning}`, `{option}`, +and similar content blocks. +::: + +Prefer triple backtick fences for code regions and literal examples: + +```cpp +int value = 0; +``` + +Keep `{eval-rst}` blocks fenced with backticks, because their contents are +reStructuredText rather than Markdown. + +[colon_fence]: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence + ## Generating the documentation You can generate the HTML documentation from the sources locally if you want to >From 0d465dedd340e9e0bed48c07698d47a33dd73bcc Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Sat, 8 Aug 2026 02:39:10 +0000 Subject: [PATCH 2/3] [docs] Use colon fences for rich MyST directives --- clang/docs/LanguageExtensions.md | 8 ++-- clang/docs/LifetimeSafety.md | 12 ++--- clang/docs/MisExpect.md | 12 ++--- clang/docs/ReleaseNotes.md | 9 ++-- clang/docs/ReleaseNotesTemplate.txt | 9 ++-- clang/docs/Toolchain.md | 16 +++---- llvm/docs/AMDGPUMemoryModel.md | 8 ++-- llvm/docs/AliasAnalysis.md | 16 +++---- llvm/docs/BitCodeFormat.md | 16 +++---- llvm/docs/BuildingADistribution.md | 12 ++--- llvm/docs/CMake.md | 16 +++---- llvm/docs/CodeGenerator.md | 28 ++++++------ llvm/docs/CodingStandards.md | 8 ++-- llvm/docs/CommandLine.md | 12 ++--- llvm/docs/CompilerWriterInfo.md | 4 +- llvm/docs/Contributing.md | 12 ++--- llvm/docs/Coroutines.md | 8 ++-- llvm/docs/CoverageMappingFormat.md | 4 +- llvm/docs/DeveloperPolicy.md | 8 ++-- llvm/docs/ExceptionHandling.md | 8 ++-- llvm/docs/GettingStarted.md | 12 ++--- llvm/docs/GettingStartedVS.md | 4 +- llvm/docs/GitHub.md | 24 +++++----- llvm/docs/HowToBuildWithPGO.md | 4 +- llvm/docs/HowToCrossCompileLLVM.md | 8 ++-- llvm/docs/InstrProfileFormat.md | 32 +++++++------- llvm/docs/LangRef.md | 44 +++++++++---------- llvm/docs/Lexicon.md | 4 +- llvm/docs/MIRLangRef.md | 4 +- llvm/docs/MemProf.md | 12 ++--- llvm/docs/Passes.md | 4 +- llvm/docs/ProgrammersManual.md | 12 ++--- llvm/docs/ReleaseNotes.md | 8 ++-- llvm/docs/ReleaseNotesTemplate.txt | 8 ++-- llvm/docs/Remarks.md | 68 ++++++++++++++--------------- llvm/docs/SourceLevelDebugging.md | 24 +++++----- llvm/docs/TestSuiteGuide.md | 4 +- llvm/docs/TestingGuide.md | 12 ++--- llvm/docs/WritingAnLLVMNewPMPass.md | 4 +- llvm/docs/WritingAnLLVMPass.md | 4 +- llvm/docs/index.md | 4 +- 41 files changed, 264 insertions(+), 262 deletions(-) diff --git a/clang/docs/LanguageExtensions.md b/clang/docs/LanguageExtensions.md index f5313e0378ca0..ee0b272c0a102 100644 --- a/clang/docs/LanguageExtensions.md +++ b/clang/docs/LanguageExtensions.md @@ -57,7 +57,7 @@ It can be used like this: ... ``` -```{note} +:::{note} Prior to Clang 10, `__has_builtin` could not be used to detect most builtin pseudo-functions. @@ -66,7 +66,7 @@ use `#ifdef` instead. When compiling with target offloading, `__has_builtin` only considers the currently active target. -``` +::: ### `__has_constexpr_builtin` @@ -5016,10 +5016,10 @@ will be used. ### C++ Coroutines support builtins -```{warning} +:::{warning} This is a work in progress. Compatibility across Clang/LLVM releases is not guaranteed. -``` +::: Clang provides experimental builtins to support C++ Coroutines as defined by <https://wg21.link/P0057>. The following four are intended to be used by the diff --git a/clang/docs/LifetimeSafety.md b/clang/docs/LifetimeSafety.md index 0159db898bb73..e41d618c029bd 100644 --- a/clang/docs/LifetimeSafety.md +++ b/clang/docs/LifetimeSafety.md @@ -30,11 +30,11 @@ with attributes like [clang::lifetimebound](https://clang.llvm.org/docs/Attribut lifetime safety at call sites with higher accuracy. This approach supports gradual adoption in existing codebases. -```{note} +:::{note} This analysis is designed for bug finding, not verification. It may miss some lifetime issues and can produce false positives. It does not guarantee the absence of all lifetime bugs. -``` +::: ### Getting Started @@ -128,14 +128,14 @@ details on these attributes, see the Clang attribute reference for [gsl::Owner](https://clang.llvm.org/docs/AttributeReference.html#gsl-owner) and [gsl::Pointer](https://clang.llvm.org/docs/AttributeReference.html#gsl-pointer). -```{note} +:::{note} Types with mixed ownership semantics (owning some data while holding views to other data) or types with multiple view fields with different lifetimes should not be annotated. The analysis does not yet support expressing such nuanced lifetime relationships. Future enhancements, such as named lifetimes, may provide better support for these patterns. -``` +::: ### LifetimeBound @@ -384,9 +384,9 @@ as `std::unique_ptr` after operations like `reset`. For example, adding elements to `std::vector` may cause reallocation, invalidating all existing iterators, pointers and references to its elements. -```{note} +:::{note} Invalidation checking is highly experimental and may produce false positives. -``` +::: ````{list-table} :widths: 50 50 diff --git a/clang/docs/MisExpect.md b/clang/docs/MisExpect.md index aba6f349a9bec..277fc86e3241d 100644 --- a/clang/docs/MisExpect.md +++ b/clang/docs/MisExpect.md @@ -42,24 +42,24 @@ MisExpect diagnostics are also available in the form of optimization remarks, which can be serialized and processed through the `opt-viewer.py` scripts in LLVM. -```{option} -Rpass=misexpect +:::{option} -Rpass=misexpect Enables optimization remarks for misexpect when profiling data conflicts with use of `llvm.expect` intrinsics. -``` +::: -```{option} -Wmisexpect +:::{option} -Wmisexpect Enables misexpect warnings when profiling data conflicts with use of `llvm.expect` intrinsics. -``` +::: -```{option} -fdiagnostic-misexpect-tolerance=N +:::{option} -fdiagnostic-misexpect-tolerance=N Relaxes misexpect checking to tolerate profiling values within N% of the expected branch weight. e.g., a value of `N=5` allows misexpect to check against `0.95 * Threshold` -``` +::: LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and Sampling. MisExpect Diagnostics are compatible with all Profiling formats. diff --git a/clang/docs/ReleaseNotes.md b/clang/docs/ReleaseNotes.md index 7976b82b63f6e..76e8745ae3019 100644 --- a/clang/docs/ReleaseNotes.md +++ b/clang/docs/ReleaseNotes.md @@ -2,6 +2,7 @@ myst: enable_extensions: - attrs_block + - colon_fence - substitution --- @@ -18,14 +19,14 @@ myst: Written by the [LLVM Team](https://llvm.org/) -````{only} PreRelease +::::{only} PreRelease -```{warning} +:::{warning} These are in-progress notes for the upcoming Clang {{env.config.version}} release. Release notes for previous releases can be found on [the Releases Page](https://llvm.org/releases/). -``` -```` +::: +:::: ## Introduction diff --git a/clang/docs/ReleaseNotesTemplate.txt b/clang/docs/ReleaseNotesTemplate.txt index 465f1eec8c05f..df98f9adc0338 100644 --- a/clang/docs/ReleaseNotesTemplate.txt +++ b/clang/docs/ReleaseNotesTemplate.txt @@ -2,6 +2,7 @@ myst: enable_extensions: - attrs_block + - colon_fence - substitution --- @@ -18,14 +19,14 @@ myst: Written by the [LLVM Team](https://llvm.org/) -````{only} PreRelease +::::{only} PreRelease -```{warning} +:::{warning} These are in-progress notes for the upcoming Clang {{env.config.version}} release. Release notes for previous releases can be found on [the Releases Page](https://llvm.org/releases/). -``` -```` +::: +:::: ## Introduction diff --git a/clang/docs/Toolchain.md b/clang/docs/Toolchain.md index a5578b5904a60..2456cfcbd58bc 100644 --- a/clang/docs/Toolchain.md +++ b/clang/docs/Toolchain.md @@ -18,12 +18,12 @@ This document describes the required and optional components in a complete toolchain, where to find them, and the supported versions and limitations of each option. -```{warning} +:::{warning} This document currently describes Clang configurations on POSIX-like operating systems with the GCC-compatible `clang` driver. When targeting Windows with the MSVC-compatible `clang-cl` driver, some of the details are different. -``` +::: ## Tools @@ -126,11 +126,11 @@ The set of implicitly-linked libraries depend on the language mode. As a consequence, you should use `clang++` when linking C++ programs in order to ensure the C++ runtimes are provided. -```{note} +:::{note} There may exist other implementations for these components not described below. Please let us know how well those other implementations work with Clang so they can be added to this list! -``` +::: % FIXME: Describe Objective-C runtime libraries @@ -193,12 +193,12 @@ libgcc_s does not provide an implementation of an atomics library. Instead, [GCC's libatomic library](https://gcc.gnu.org/wiki/Atomic/GCCMM) can be used to supply these when using libgcc_s. -```{note} +:::{note} Clang does not currently automatically link against libatomic when using libgcc_s. You may need to manually add `-latomic` to support this configuration when using non-native atomic operations (if you see link errors referring to `__atomic_*` functions). -``` +::: ### Unwind library @@ -281,11 +281,11 @@ libsupc++ is GCC's implementation of this specification. However, this library is only used when libstdc++ is linked statically. The dynamic library version of libstdc++ contains a copy of libsupc++. -```{note} +:::{note} Clang does not currently automatically link against libsupc++ when statically linking libstdc++. You may need to manually add `-lsupc++` to support this configuration when using `-static` or `-static-libstdc++`. -``` +::: #### libcxxrt (PathScale) diff --git a/llvm/docs/AMDGPUMemoryModel.md b/llvm/docs/AMDGPUMemoryModel.md index 2fadb245d10c4..0a7f023bf19ac 100644 --- a/llvm/docs/AMDGPUMemoryModel.md +++ b/llvm/docs/AMDGPUMemoryModel.md @@ -203,12 +203,12 @@ Any access to `addrspace(0)` (aka flat or generic) always results in a *store-available* or *load-visible* operation with scope "workgroup", if the flat address resolves to `addrspace(3)`. -```{note} +:::{note} This is independent of the `syncscope` of an atomic access. For example, even if a `store atomic` to `addrspace(3)` specifies a smaller `syncscope` such as "wavefront", the side-effects are made available at "workgroup" scope. In other words, the scope for atomicity is not always the same as the scope for availability/visibility. -``` +::: ### volatile Accesses @@ -228,12 +228,12 @@ A `volatile` atomic access is not widened in this way. Its availability and visibility remain limited to its `syncscope`, as described for atomic accesses above. -```{note} +:::{note} The availability and visibility of volatile accesses is specific to AMDGPU, and orthogonal to the {ref}`base semantics defined in LLVM IR<volatile>`. This fully specifies the behavior that the {ref}`LLVM memory model<memmodel>` otherwise leaves target-dependent for `volatile` accesses. -``` +::: (amdgpu-av-metadata)= diff --git a/llvm/docs/AliasAnalysis.md b/llvm/docs/AliasAnalysis.md index 62b3572dc3d23..a3a544427937f 100644 --- a/llvm/docs/AliasAnalysis.md +++ b/llvm/docs/AliasAnalysis.md @@ -496,10 +496,10 @@ information for call instructions. This allows the optimizer to know that calls to a function do not clobber or read the value of the global, allowing loads and stores to be eliminated. -```{note} +:::{note} This pass is somewhat limited in its scope (only support non-address taken globals), but is very quick analysis. -``` +::: #### The `-steens-aa` pass @@ -513,10 +513,10 @@ version of Steensgaard's algorithm using the Data Structure Analysis framework. This gives it substantially more precision than the standard algorithm while maintaining excellent analysis scalability. -```{note} +:::{note} `-steens-aa` is available in the optional "poolalloc" module. It is not part of the LLVM core. -``` +::: #### The `-ds-aa` pass @@ -530,10 +530,10 @@ queries, and can provide context-sensitive mod/ref information as well. The only major facility not implemented so far is support for must-alias information. -```{note} +:::{note} `-ds-aa` is available in the optional "poolalloc" module. It is not part of the LLVM core. -``` +::: #### The `-scev-aa` pass @@ -613,11 +613,11 @@ algorithm will have a lower number of may aliases). ## Memory Dependence Analysis -```{note} +:::{note} We are currently in the process of migrating things from `MemoryDependenceAnalysis` to {doc}`MemorySSA`. Please try to use that instead. -``` +::: If you're just looking to be a client of alias analysis information, consider using the Memory Dependence Analysis interface instead. MemDep is a lazy, diff --git a/llvm/docs/BitCodeFormat.md b/llvm/docs/BitCodeFormat.md index 406cd10a0df1f..5ea909fcb74ff 100644 --- a/llvm/docs/BitCodeFormat.md +++ b/llvm/docs/BitCodeFormat.md @@ -862,12 +862,12 @@ in the `PARAMATTR_GROUP_BLOCK` block. #### PARAMATTR_CODE_ENTRY_OLD Record -```{note} +:::{note} This is a legacy encoding for attributes, produced by LLVM versions 3.2 and earlier. It is guaranteed to be understood by the current LLVM version, as specified in the {ref}`IR backwards compatibility` policy. -``` +::: `[ENTRY, paramidx0, attr0, paramidx1, attr1...]` @@ -971,21 +971,21 @@ Correspond to: The mappings between the enumeration and the attribute name string may be found in the file [Attributes.td](https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/IR/Attributes.td). -```{note} +:::{note} The `allocsize` attribute has a special encoding for its arguments. Its two arguments, which are 32-bit integers, are packed into one 64-bit integer value (i.e., `(EltSizeParam << 32) | NumEltsParam`), with `NumEltsParam` taking on the sentinel value -1 if it is not specified. -``` +::: -```{note} +:::{note} The `vscale_range` attribute has a special encoding for its arguments. Its two arguments, which are 32-bit integers, are packed into one 64-bit integer value (i.e., `(Min << 32) | Max`), with `Max` taking on the value of `Min` if it is not specified. -``` +::: (TYPE_BLOCK)= @@ -1080,12 +1080,12 @@ operand fields are: #### TYPE_CODE_FUNCTION_OLD Record -```{note} +:::{note} This is a legacy encoding for functions, produced by LLVM versions 3.0 and earlier. It is guaranteed to be understood by the current LLVM version, as specified in the {ref}`IR backwards compatibility` policy. -``` +::: `[FUNCTION_OLD, vararg, ignored, retty, ...paramty... ]` diff --git a/llvm/docs/BuildingADistribution.md b/llvm/docs/BuildingADistribution.md index e3672e7e26afb..14274b09e19f4 100644 --- a/llvm/docs/BuildingADistribution.md +++ b/llvm/docs/BuildingADistribution.md @@ -40,14 +40,14 @@ at process launch time, which can be very slow for C++ code. (shared-libs)= -```{warning} +:::{warning} One very important note: Distributions should never be built using the *BUILD_SHARED_LIBS* CMake option. That option exists for optimizing developer workflow only. Due to design and implementation decisions, LLVM relies on global data which can end up being duplicated across shared libraries resulting in bugs. As such this is not a safe way to distribute LLVM or LLVM-based tools. -``` +::: The simplest example of building a distribution with reasonable performance is captured in the DistributionExample CMake cache file located at @@ -175,10 +175,10 @@ generation using dtrace is also non-deterministic. ## Options for Reducing Size -```{warning} +:::{warning} Any steps taken to reduce binary size will come at the cost of runtime performance in the generated binaries. -``` +::: The simplest and least significant way to reduce binary size is to set the *CMAKE_BUILD_TYPE* variable to `MinSizeRel`, which will set the compiler @@ -190,10 +190,10 @@ all the tools. This reduces code size by decreasing duplication of common code among the LLVM-based tools. This can be done by setting the following two CMake options to `On`: *LLVM_BUILD_LLVM_DYLIB* and *LLVM_LINK_LLVM_DYLIB*. -```{warning} +:::{warning} Distributions should never be built using the *BUILD_SHARED_LIBS* CMake option. ({ref}`See the warning above for more explanation <shared-libs>`.). -``` +::: ## Relevant CMake Options diff --git a/llvm/docs/CMake.md b/llvm/docs/CMake.md index c12c95bbc3dec..c64b419cd06ba 100644 --- a/llvm/docs/CMake.md +++ b/llvm/docs/CMake.md @@ -134,9 +134,9 @@ for building with NMake. By default, CMake chooses the most specific generator supported by your development environment. If you want an alternative generator, you must specify this to CMake with the `-G` option. -```{todo} +:::{todo} Explain variables and cache. Move explanation here from #options section. -``` +::: (Options and variables)= ## Options and variables @@ -314,9 +314,9 @@ sub-projects. Nearly all of these variable names begin with `LLVM_`. Windows, shared libraries may be used when building with MinGW, including mingw-w64, but not when building with the Microsoft toolchain. - ```{note} + :::{note} `BUILD_SHARED_LIBS` is only recommended for use by LLVM developers. If you want to build LLVM as a shared library, you should use the `LLVM_BUILD_LLVM_DYLIB` option. - ``` + ::: **LLVM_ABI_BREAKING_CHECKS**:STRING @@ -643,9 +643,9 @@ sub-projects. Nearly all of these variable names begin with `LLVM_`. `bolt;clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;mlir;openmp;polly` - ```{note} + :::{note} Some projects listed here can also go in `LLVM_ENABLE_RUNTIMES`. They should only appear in one of the two lists. If a project is a valid possibility for both, prefer putting it in `LLVM_ENABLE_RUNTIMES`. - ``` + ::: **LLVM_ENABLE_RTTI**:BOOL @@ -660,9 +660,9 @@ sub-projects. Nearly all of these variable names begin with `LLVM_`. using a system compiler, see the [libc++ documentation](https://libcxx.llvm.org/VendorDocumentation.html). - ```{note} + :::{note} The list should not have duplicates with `LLVM_ENABLE_PROJECTS`. - ``` + ::: To list all possible runtimes, include an invalid name. For example `-DLLVM_ENABLE_RUNTIMES=notaruntime`. The resulting CMake error will list diff --git a/llvm/docs/CodeGenerator.md b/llvm/docs/CodeGenerator.md index cd37407de79e4..32242b413c2a8 100644 --- a/llvm/docs/CodeGenerator.md +++ b/llvm/docs/CodeGenerator.md @@ -16,9 +16,9 @@ ``` -```{warning} +:::{warning} This is a work in progress. -``` +::: ## Introduction The LLVM target-independent code generator is a framework that provides a suite @@ -1196,9 +1196,9 @@ of the basic block. Live intervals for virtual registers are computed for some ordering of the machine instructions `[1, N]`. A live interval is an interval `[i, j)`, where `1 >= i >= j > N`, for which a variable is live. -```{note} +:::{note} More to come... -``` +::: (Register Allocation)= (register allocator)= @@ -1448,9 +1448,9 @@ $ llc -regalloc=pbqp file.bc -o pbqp.s ### Prolog/Epilog Code Insertion -```{note} +:::{note} To Be Written -``` +::: ### Compact Unwind Throwing an exception requires *unwinding* out of a function. The information on @@ -1522,9 +1522,9 @@ the function in bits 9-12 (mask: `0x00001C00`). ### Late Machine Code Optimizations -```{note} +:::{note} To Be Written -``` +::: (Code Emission)= ### Code Emission @@ -1645,9 +1645,9 @@ compiler. ### Instruction Parsing -```{note} +:::{note} To Be Written -``` +::: ### Instruction Alias Processing Once the instruction is parsed, it enters the MatchInstructionImpl function. @@ -1750,9 +1750,9 @@ as the third parameter to the InstAlias definition. ### Instruction Matching -```{note} +:::{note} To Be Written -``` +::: (Implementations of the abstract target description interfaces)= (implement the target description)= @@ -2091,9 +2091,9 @@ makes it convenient to locate programmatically and during debugging. #### Dynamic Allocation -```{note} +:::{note} TODO - More to come. -``` +::: ### The NVPTX backend The NVPTX code generator under lib/Target/NVPTX is an open-source version of diff --git a/llvm/docs/CodingStandards.md b/llvm/docs/CodingStandards.md index 716a959d1cfd2..24df36285ba21 100644 --- a/llvm/docs/CodingStandards.md +++ b/llvm/docs/CodingStandards.md @@ -899,10 +899,10 @@ If you really need to do something like this, put a private header file in the same directory as the source files, and include it locally. This ensures that your private interface remains private and undisturbed by outsiders. -```{note} +:::{note} It's okay to put extra implementation methods in a public class itself. Just make them private (or protected) and all is well. -``` +::: #### Use Namespace Qualifiers to Define Previously Declared Symbols @@ -1497,10 +1497,10 @@ problematic in this regard --- just `<iostream>`. However, `raw_ostream` provides various APIs that are better performing for almost every use than `std::ostream` style APIs. -```{note} +:::{note} New code should always use {ref}`raw_ostream <raw_ostream>` for writing, or the `llvm::MemoryBuffer` API for reading files. -``` +::: (raw_ostream)= diff --git a/llvm/docs/CommandLine.md b/llvm/docs/CommandLine.md index fab5894acc3df..2cf37ebc52d42 100644 --- a/llvm/docs/CommandLine.md +++ b/llvm/docs/CommandLine.md @@ -922,12 +922,12 @@ cl::opt<bool> Quiet("quiet"); defaults to the value created by the default constructor for the type. -```{warning} +:::{warning} If you specify both **cl::init** and **cl::location** for an option, you must specify **cl::location** first, so that when the command-line parser sees **cl::init**, it knows where to put the initial value. (You will get an error at runtime if you don't put them in the right order.) -``` +::: (cl::location)= @@ -1695,14 +1695,14 @@ library. Examples of this include the `llvm::DebugFlag` exported by the `lib/Support/Debug.cpp` file and the `llvm::TimePassesIsEnabled` flag exported by the `lib/IR/PassManager.cpp` file. -```{todo} +:::{todo} TODO: complete this section -``` +::: (dynamically loaded options)= ### Dynamically adding command line options -```{todo} +:::{todo} TODO: fill in this section -``` +::: diff --git a/llvm/docs/CompilerWriterInfo.md b/llvm/docs/CompilerWriterInfo.md index a275f604da820..f7d94414837bc 100644 --- a/llvm/docs/CompilerWriterInfo.md +++ b/llvm/docs/CompilerWriterInfo.md @@ -1,10 +1,10 @@ # Architecture & Platform Information for Compiler Writers -```{note} +:::{note} This document is a work-in-progress. Additions and clarifications are welcome. -``` +::: ## Hardware diff --git a/llvm/docs/Contributing.md b/llvm/docs/Contributing.md index e87cc7896d565..8c75e4ff0da3c 100644 --- a/llvm/docs/Contributing.md +++ b/llvm/docs/Contributing.md @@ -63,7 +63,7 @@ recent commit: % git clang-format HEAD~1 ``` -```{note} +:::{note} For some patches, formatting them may add changes that obscure the intent of the patch. For example, adding to an enum that was not previously formatted may result in the entire enum being reformatted. This happens because not all @@ -79,7 +79,7 @@ Request that will be merged before your actual changes. This means that if the formatting changes are the first commit, you will have an easier time doing this. If they are not, that is ok too, but you will have to do a bit more work to separate it out. -``` +::: Note that `git clang-format` modifies the files, but does not commit them -- you will likely want to run one of the following to add the changes to a commit: @@ -91,12 +91,12 @@ you will likely want to run one of the following to add the changes to a commit: % git commit --amend -a ``` -```{note} +:::{note} If you don't already have `clang-format` or `git clang-format` installed on your system, the `clang-format` binary will be built alongside clang, and the git integration can be run from `clang/tools/clang-format/git-clang-format`. -``` +::: The LLVM project has migrated to GitHub Pull Requests as its review process. For more information about the workflow of using GitHub Pull Requests see our @@ -133,10 +133,10 @@ For more information on LLVM's code-review process, please see ### For developers to commit changes from Git -```{note} +:::{note} See also {ref}`GitHub <github-reviews>` for more details on merging your changes into LLVM project monorepo. -``` +::: Once a pull request is approved, you can select the "Squash and merge" button in the GitHub web interface. diff --git a/llvm/docs/Coroutines.md b/llvm/docs/Coroutines.md index e7f629bf4ef08..fa18a71ad66dd 100644 --- a/llvm/docs/Coroutines.md +++ b/llvm/docs/Coroutines.md @@ -1,9 +1,9 @@ # Coroutines in LLVM -```{warning} +:::{warning} Compatibility across LLVM releases is not guaranteed. -``` +::: ## Introduction @@ -522,7 +522,7 @@ suspend: If different cleanup code needs to be executed for different suspend points, a similar switch will be in the `f.destroy` function. -```{note} +:::{note} Using suspend index in a coroutine state and having a switch in `f.resume` and `f.destroy` is one of the possible implementation strategies. We explored another option where a distinct `f.resume1`, `f.resume2`, etc. are created for @@ -530,7 +530,7 @@ every suspend point, and instead of storing an index, the resume and destroy function pointers are updated at every suspend. Early testing showed that the current approach is easier on the optimizer than the latter so it is a lowering strategy implemented at the moment. -``` +::: ### Distinct Save and Suspend diff --git a/llvm/docs/CoverageMappingFormat.md b/llvm/docs/CoverageMappingFormat.md index 7b4690f4bb1c7..02fab85fa1c81 100644 --- a/llvm/docs/CoverageMappingFormat.md +++ b/llvm/docs/CoverageMappingFormat.md @@ -586,9 +586,9 @@ The source range record contains the following fields: ## Testing Format -```{warning} +:::{warning} This section is for the LLVM developers who are working on `llvm-cov` only. -``` +::: `llvm-cov` uses a special file format (called `.covmapping` below) for testing purposes. This format is private and should have no use for general diff --git a/llvm/docs/DeveloperPolicy.md b/llvm/docs/DeveloperPolicy.md index 173046650d677..069b8fbb02798 100644 --- a/llvm/docs/DeveloperPolicy.md +++ b/llvm/docs/DeveloperPolicy.md @@ -1113,10 +1113,10 @@ disabled again, until the issues have been resolved. (copyright-license-patents)= ## Copyright, License, and Patents -```{note} +:::{note} This section deals with legal matters but does not provide legal advice. We are not lawyers \-\-- please seek legal counsel from a licensed attorney. -``` +::: This section addresses the issues of copyright, license and patents for the LLVM project. The copyright for the code is held by the contributors of the code. @@ -1318,14 +1318,14 @@ holds though): (legacy)= ### Legacy License Structure -```{note} +:::{note} The code base was previously licensed under the Terms described here. We are in the middle of relicensing to a new approach (described above). More than 99% of all contributions made to LLVM are covered by the Apache-2.0 WITH LLVM-exception license. A small portion of LLVM code remains exclusively covered by the legacy license. Contributions after 2024-06-01 are covered exclusively by the new license. -``` +::: We intend to keep LLVM perpetually open source and to use a permissive open source license. The code in diff --git a/llvm/docs/ExceptionHandling.md b/llvm/docs/ExceptionHandling.md index 978baee70e74d..4b6cf835bac7f 100644 --- a/llvm/docs/ExceptionHandling.md +++ b/llvm/docs/ExceptionHandling.md @@ -236,11 +236,11 @@ Finally, the entry and exit of catch code is bracketed with calls to 1. Destroys the exception if the handler count goes to zero and the exception was not re-thrown by throw. - ```{note} + :::{note} a rethrow from within the catch may replace this call with a `__cxa_rethrow`. - ``` + ::: ### Cleanups @@ -252,14 +252,14 @@ block. To indicate the presence of cleanups, a {ref}`i_landingpad` should have a *cleanup* clause. Otherwise, the unwinder will not stop at the landing pad if there are no catches or filters that require it to. -```{note} +:::{note} Do not allow a new exception to propagate out of the execution of a cleanup. This can corrupt the internal state of the unwinder. Different languages describe different high-level semantics for these situations: for example, C++ requires that the process be terminated, whereas Ada cancels both exceptions and throws a third. -``` +::: When all cleanups are finished, if the exception is not handled by the current function, resume unwinding by calling the {ref}`resume instruction <i_resume>`, diff --git a/llvm/docs/GettingStarted.md b/llvm/docs/GettingStarted.md index 5c1789de9ef39..a8fb74dddd1b2 100644 --- a/llvm/docs/GettingStarted.md +++ b/llvm/docs/GettingStarted.md @@ -243,14 +243,14 @@ LLVM is known to work on the following host platforms: | Windows x64 | x86-64 | Visual Studio, Clang{sup}`4` | | Windows on Arm | ARM64 | Visual Studio, Clang{sup}`4` | -```{note} +:::{note} 1. Code generation supported for Pentium processors and up 1. Code generation supported for 32-bit ABI only 1. To use LLVM modules on a Win32-based system, you may configure LLVM with `-DBUILD_SHARED_LIBS=On`. 1. Visual Studio alone can compile LLVM. When using Clang, you must also have Visual Studio installed. -``` +::: Note that Debug builds require a lot of time and disk space. An LLVM-only build will need about 1-3 GB of space. A full build of LLVM and Clang will need around 15-20 GB of disk space. The exact space requirements will vary by system. (It @@ -282,12 +282,12 @@ uses the package and provides other details. | [GNU Make](http://savannah.gnu.org/projects/make) | 3.79, 3.79.1 | Makefile/build processor{sup}`2` | | [PyYAML](https://pypi.org/project/PyYAML/) | >=5.1 | Header generator{sup}`3` | -```{note} +:::{note} 1. Optional, adds compression/uncompression capabilities to selected LLVM tools. 1. Optional, you can use any other build tool supported by CMake. 1. Only needed when building libc with New Headergen. Mainly used by libc. -``` +::: Additionally, your compilation host is expected to have the usual plethora of Unix utilities. Specifically: @@ -956,10 +956,10 @@ This section gives an example of using LLVM with the Clang front end. ```console % clang hello.c -o hello ``` - ```{note} + :::{note} Clang works just like GCC by default. The standard `-S` and `-c` arguments work as usual (producing a native `.s` or `.o` file, respectively). - ``` + ::: 1. Next, compile the C file into an LLVM bitcode file: ```console diff --git a/llvm/docs/GettingStartedVS.md b/llvm/docs/GettingStartedVS.md index 66b5d7763adef..f70f1157b109a 100644 --- a/llvm/docs/GettingStartedVS.md +++ b/llvm/docs/GettingStartedVS.md @@ -120,7 +120,7 @@ These instructions were tested with Visual Studio 2019 and Python 3.9.6: exit ``` - ```{note} + :::{note} By default, the Visual Studio project files generated by CMake use the 32-bit toolset. If you are developing on a 64-bit version of Windows and want to use the 64-bit toolset, pass the `-Thost=x64` flag when @@ -128,7 +128,7 @@ These instructions were tested with Visual Studio 2019 and Python 3.9.6: For Windows on Arm the equivalent is `-Thost=ARM64`, but this the default for those hosts, so you do not have to use this option. - ``` + ::: `LLVM_ENABLE_PROJECTS` specifies any additional LLVM projects you want to build while `LLVM_TARGETS_TO_BUILD` selects the compiler targets. If diff --git a/llvm/docs/GitHub.md b/llvm/docs/GitHub.md index c08d05a0adc60..717cce12210fa 100644 --- a/llvm/docs/GitHub.md +++ b/llvm/docs/GitHub.md @@ -26,12 +26,12 @@ describes the typical workflow of creating a Pull Request and getting it reviewe and accepted. This is meant as an overview of the GitHub workflow, for complete documentation refer to [GitHub's documentation](https://docs.github.com/pull-requests). -```{note} +:::{note} If you are using a Pull Request for purposes other than review (eg: precommit CI results, convenient web-based reverts, etc) add the [skip-precommit-approval](https://github.com/llvm/llvm-project/labels?q=skip-precommit-approval) label to the PR. -``` +::: ### GitHub Tools @@ -68,11 +68,11 @@ gh pr create When prompted select to create and use your own fork and follow the instructions to add more information needed. -```{note} +:::{note} When you let the GitHub CLI create a fork of llvm-project to your user, it will change the git "remotes" so that "origin" points to your fork and "upstream" points to the main llvm-project repository. -``` +::: ### Updating Pull Requests @@ -116,11 +116,11 @@ or in some dependent code. After your PR is reviewed and accepted, you want to rebase your branch to ensure you won't encounter merge conflicts when landing the PR. -```{note} +:::{note} This guide assumes that the PR branch only has 1 author. If you are collaborating with others on a single branch, be careful how and when you push changes. `--force-with-lease` may be useful in this situation. -``` +::: ### Approvals @@ -137,7 +137,7 @@ After your PR is approved, ensure that: messages of commits in the PR will **not** be used. * You have set a valid email address in your GitHub account, see {ref}`github-email-address`. -```{note} +:::{note} The LLVM Project monorepo on GitHub is configured to always use "Squash and Merge" as the pull request merge option when using the web interface. With this option, GitHub uses the PR summary as the default commit @@ -146,7 +146,7 @@ message. Users with write access who can merge PRs have a final opportunity to edit the commit title and message before merging. However, this option is not available to contributors without write access. -``` +::: At this point, you can merge your changes. If you do not have write permissions for the repository, the merge button in GitHub's web interface will be @@ -231,7 +231,7 @@ To separate related changes or to break down a larger PR into smaller, reviewabl pieces, use "stacked pull requests" — this helps make the review process smoother. -```{note} +:::{note} The LLVM Project monorepo on GitHub is configured to always use "Squash and Merge" as the pull request merge option. As a result, each PR results in exactly one commit being merged into the project. @@ -240,7 +240,7 @@ This means that stacked pull requests are the only available option for landing a series of related changes. In contrast, submitting a PR with multiple commits and merging them as-is (without squashing) is not supported in LLVM. -``` +::: While GitHub does not natively support stacked pull requests, there are several common alternatives. @@ -288,7 +288,7 @@ Your options are as follows: stacked PRs. These tools are also based on using user branches in `llvm/llvm-project`. -```{note} +:::{note} When not using user branches, GitHub will not display proper diffs for subsequent PRs in a stack. Instead, it will show a combined diff that includes all commits from earlier PRs. @@ -299,7 +299,7 @@ For example: “The first N commits are from the base PR.” You can avoid this issue by using user branches directly in the `llvm/llvm-project` repository. -``` +::: ### Using Graphite for stacked Pull Requests diff --git a/llvm/docs/HowToBuildWithPGO.md b/llvm/docs/HowToBuildWithPGO.md index c6ca3c7f31b49..421102a4f6cb9 100644 --- a/llvm/docs/HowToBuildWithPGO.md +++ b/llvm/docs/HowToBuildWithPGO.md @@ -141,12 +141,12 @@ In more detailed steps: From here, you can build whatever targets you need. - ```{note} + :::{note} You may see warnings about a mismatched profile in the build output. These are generally harmless. To silence them, you can add `-DCMAKE_C_FLAGS='-Wno-backend-plugin' -DCMAKE_CXX_FLAGS='-Wno-backend-plugin'` to your CMake invocation. - ``` + ::: Congrats! You now have a Clang built with profile-guided optimizations, and you can delete all but the final build directory if you'd like. diff --git a/llvm/docs/HowToCrossCompileLLVM.md b/llvm/docs/HowToCrossCompileLLVM.md index d22c054222c74..5518b8a2aa5bd 100644 --- a/llvm/docs/HowToCrossCompileLLVM.md +++ b/llvm/docs/HowToCrossCompileLLVM.md @@ -11,11 +11,11 @@ please check <https://clang.llvm.org/docs/CrossCompilation.html>. This document describes cross-building a compiler in a single stage, using an existing `clang` install as the host compiler. -```{note} +:::{note} These instructions have been tested for targeting 32-bit ARM, AArch64, or 64-bit RISC-V from an x86_64 Linux host. But should be equally applicable to any other target. -``` +::: ## Setting up a sysroot @@ -198,11 +198,11 @@ InstalledDir: /home/asb/llvm-project/build/aarch64-linux-gnu/bin ## Installing and using -```{note} +:::{note} Use of the `install` target requires that you have set `CMAKE_INSTALL_PREFIX` otherwise it will attempt to install in directories under `/` on your host. -``` +::: If you want to transfer a copy of the built compiler to another machine, you can first install it to a location on the host via: diff --git a/llvm/docs/InstrProfileFormat.md b/llvm/docs/InstrProfileFormat.md index e09d9992bf907..336139fefd73f 100644 --- a/llvm/docs/InstrProfileFormat.md +++ b/llvm/docs/InstrProfileFormat.md @@ -10,11 +10,11 @@ store instrumented profiles with a specific emphasis on IRPGO use case, in the sense that when specific header fields and payload sections have different ways of interpretation across use cases, the documentation is based on IRPGO. -```{note} +:::{note} Frontend-generated profiles are used together with coverage mapping for [source-based code coverage](https://clang.llvm.org/docs/SourceBasedCodeCoverage.html). The [coverage mapping format](https://llvm.org/docs/CoverageMappingFormat.html) is different from profile format. -``` +::: ## Raw Profile Format @@ -65,11 +65,11 @@ D | Section N | +----+-----------------------+ ``` -```{note} +:::{note} Sections might be padded to meet specific alignment requirements. For simplicity, header fields and data sections solely for padding purposes are omitted in the data layout graph above and the rest of this document. -``` +::: ### Header @@ -115,13 +115,13 @@ It's used jointly with the [CounterPtr](#CounterPtr) field to compute the counte relative to `start(__llvm_prf_cnts)`. Check out [calculation-of-counter-offset](#calculation-of-counter-offset) for a visualized explanation. -```{note} +:::{note} The `__llvm_prf_data` object file section might not be loaded into memory when instrumented binary runs or might not get generated in the instrumented binary in the first place. In those cases, `CountersDelta` is not used and other mechanisms are used to match counters with instrumented code. See [lightweight instrumentation] and [binary profile correlation] for examples. -``` +::: **`BitmapDelta`** This field records the in-memory address difference between the [profile metadata](#profile-metadata) @@ -186,11 +186,11 @@ counters. Counter position is stored this way (as a link-time constant) to reduc instrumented binary size compared with snapshotting the address of symbols directly. See [commit a1532ed](https://github.com/llvm/llvm-project/commit/a1532ed27582038e2d9588108ba0fe8237f01844) for further information. -```{note} +:::{note} `CounterPtr` might represent a different value for non-IRPGO use cases. For example, for [binary profile correlation], it represents the absolute address of counter. When in doubt, check source code. -``` +::: (BitmapPtr)= @@ -198,9 +198,9 @@ When in doubt, check source code. The in-memory address difference between profile data and the start address of corresponding bitmap. -```{note} +:::{note} Similar to [CounterPtr](#CounterPtr), this field may represent a different value for non-IRPGO use cases. -``` +::: **`FunctionPointer`** Records the function address when instrumented binary runs. This is used to @@ -215,10 +215,10 @@ the each element in the second dimension is linked list element, carrying `<profiled-value, count>` as payload. This is used by compiler runtime when writing out value profiles. -```{note} +:::{note} Value profiling is supported by frontend and IR PGO instrumentation, but it's not supported in all cases (e.g., [lightweight instrumentation]). -``` +::: **`NumCounters`** The number of counters for the instrumented function. @@ -399,10 +399,10 @@ payload sections. +-----------------------+---+ ``` -```{note} +:::{note} Profile summary section is at the beginning of payload. It's right after the header so its position is implicitly known after reading the header. -``` +::: ### Header @@ -411,11 +411,11 @@ what's in the header. At a high level, `*Offset` fields record section byte offsets, which are used by readers to locate interesting sections and skip uninteresting ones. -```{note} +:::{note} To maintain backward compatibility of the indexed profiles, existing fields shouldn't be deleted from struct definition; the field order shouldn't be modified. New fields should be appended. -``` +::: ### Payload Sections diff --git a/llvm/docs/LangRef.md b/llvm/docs/LangRef.md index d57f619042f22..56cfa53610d38 100644 --- a/llvm/docs/LangRef.md +++ b/llvm/docs/LangRef.md @@ -840,7 +840,7 @@ and can also be duplicated. Note that a constant with significant address *can* be merged with a `unnamed_addr` constant, the result being a constant whose address is significant. -```{warning} +:::{warning} Constant duplication currently makes it unsound to compare pointers if either may be `unnamed_addr`, because each reference to the global in the IR may return a different pointer, and optimization @@ -850,7 +850,7 @@ will return true if the object is the same, which theoretically can make any usage of `unnamed_addr` unsound, but in practice it is unlikely that input IR that does not explicitly compare pointers will be affected by this issue. -``` +::: If the `local_unnamed_addr` attribute is given, the address is known to not be significant within the module. @@ -4011,7 +4011,7 @@ Likewise, the backend should never split or merge target-legal volatile load/store instructions. Similarly, IR-level volatile loads and stores cannot change from integer to floating-point or vice versa. -```{admonition} Rationale +:::{admonition} Rationale Platforms may rely on volatile loads and stores of natively supported data width to be executed as single instruction. For example, in C this holds for an l-value of volatile primitive type with native @@ -4019,7 +4019,7 @@ hardware support, but not necessarily for aggregate types. The frontend upholds these expectations, which are intentionally unspecified in the IR. The rules above ensure that IR transformations do not violate the frontend's contract with the language. -``` +::: (memmodel)= @@ -5262,12 +5262,12 @@ indicates that the user of the value may receive an unspecified bit-pattern. Undefined values may be of any type (other than '`label`' or '`void`') and be used anywhere a constant is permitted. -```{note} +:::{note} A '`poison`' value (described in the next section) should be used instead of '`undef`' whenever possible. Poison values are stronger than undef, and enable more optimizations. Just the existence of '`undef`' blocks certain optimizations (see the examples below). -``` +::: Undefined values are useful because they indicate to the compiler that the program is well defined no matter what value is used. This gives the @@ -6507,10 +6507,10 @@ There are two metadata primitives: strings and nodes. There are also specialized nodes which have a distinguished name and a set of named arguments. -```{note} +:::{note} One example application of metadata is source-level debug information, which is currently the only user of specialized nodes. -``` +::: Metadata does not have a type, and is not a value. @@ -6526,7 +6526,7 @@ type: - Arguments to certain intrinsic functions, as described in their specification. - Arguments to the `catchpad`/`cleanuppad` instructions. -````{note} +::::{note} Metadata can be "wrapped" in a `MetadataAsValue` so it can be referenced in a value context: `MetadataAsValue` is-a `Value`. @@ -6564,7 +6564,7 @@ And the first element of this `MDTuple` is a `ValueAsMetadata(Value)`: ```llvm !{i32 1} ``` -```` +:::: (metadata-string)= @@ -6576,9 +6576,9 @@ contain any character by escaping non-printable characters with "`\xx`" where "`xx`" is the two digit hex code. For example: "`!"test\00"`". -```{note} +:::{note} A metadata string is metadata, but is not a metadata node. -``` +::: (metadata-node)= @@ -7196,10 +7196,10 @@ LLVM variable relates to the source language variable. See {ref}`diexpression` for details. -```{note} +:::{note} `DIExpression`s are always printed and parsed inline; they can never be referenced by an ID (e.g., `!1`). -``` +::: Some examples of expressions: @@ -11221,10 +11221,10 @@ result of the division and the remainder.) The '`frem`' instruction returns the remainder from the division of its two operands. -```{note} +:::{note} The instruction is implemented as a call to libm's '`fmod`' for some targets, and using the instruction may thus require linking libm. -``` +::: ##### Arguments: @@ -16911,10 +16911,10 @@ This is equivalent to the `llvm.sincos.*` intrinsic where the argument has been multiplied by pi, however, it computes the result more accurately especially for large input values. -```{note} +:::{note} Currently, the default lowering of this intrinsic relies on the `sincospi[f|l]` functions being available in the target's runtime (e.g., libc). -``` +::: When specified with the fast-math-flag 'afn', the result may be approximated using a less accurate calculation. @@ -17476,11 +17476,11 @@ which follow {ref}`LLVM's usual signaling NaN behavior <floatnan>` instead. The `llvm.minnum` intrinsic can be refined into `llvm.minimumnum`, as the latter exhibits a subset of behaviors of the former. -```{warning} +:::{warning} If the intrinsic is used without nsz, not all backends currently respect the specified signed zero ordering. Do not rely on it until this warning has been removed. See [issue #174730](https://github.com/llvm/llvm-project/issues/174730). -``` +::: (i_maxnum)= @@ -17536,11 +17536,11 @@ which follow {ref}`LLVM's usual signaling NaN behavior <floatnan>` instead. The `llvm.maxnum` intrinsic can be refined into `llvm.maximumnum`, as the latter exhibits a subset of behaviors of the former. -```{warning} +:::{warning} If the intrinsic is used without nsz, not all backends currently respect the specified signed zero ordering. Do not rely on it until this warning has been removed. See [issue #174730](https://github.com/llvm/llvm-project/issues/174730). -``` +::: (i_minimum)= diff --git a/llvm/docs/Lexicon.md b/llvm/docs/Lexicon.md index c28615330718f..022e9b5811f38 100644 --- a/llvm/docs/Lexicon.md +++ b/llvm/docs/Lexicon.md @@ -1,8 +1,8 @@ # The LLVM Lexicon -```{note} +:::{note} This document is a work in progress! -``` +::: ## Definitions diff --git a/llvm/docs/MIRLangRef.md b/llvm/docs/MIRLangRef.md index a8540859e30ca..a767d6e2ee239 100644 --- a/llvm/docs/MIRLangRef.md +++ b/llvm/docs/MIRLangRef.md @@ -1,9 +1,9 @@ # Machine IR (MIR) Format Reference Manual -```{warning} +:::{warning} This is a work in progress. -``` +::: ## Introduction diff --git a/llvm/docs/MemProf.md b/llvm/docs/MemProf.md index 8ba84c3db1b70..c5a4b8e6ff131 100644 --- a/llvm/docs/MemProf.md +++ b/llvm/docs/MemProf.md @@ -30,10 +30,10 @@ To enable MemProf instrumentation, compile your application with the `-fmemory-p clang++ -fmemory-profile -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -fno-optimize-sibling-calls -fdebug-info-for-profiling -gmlt -O2 -fno-pie -no-pie -Wl,-z,noseparate-code -Wl,--build-id source.cpp -o app ``` -```{note} +:::{note} Link with `-fmemory-profile` as well to link the necessary runtime libraries. If you use a separate link step, ensure the flag is passed to the linker. On Linux, the flags `-fno-pie -no-pie -Wl,-z,noseparate-code -Wl,--build-id` are currently required to ensure the binary layout (executable segment at offset 0) and Build ID presence are compatible with the `llvm-profdata` profile reader. -``` +::: ### Running and Generating Profiles @@ -83,10 +83,10 @@ opt -passes='memprof-use<profile-filename=memprof.memprofdata>' ... The compiler uses the profile data to annotate allocation instructions with `!memprof` metadata ([MemProf Metadata Documentation](https://llvm.org/docs/LangRef.html#memprof-metadata)), distinguishing between "hot", "cold", and "notcold" allocations. This metadata guides downstream optimizations. Additionally, callsites which are part of allocation contexts are also annotated with `!callsite` metadata ([Callsite Metadata Documentation](https://llvm.org/docs/LangRef.html#callsite-metadata)). -```{note} +:::{note} Ensure that the same debug info flags (e.g. `-gmlt` and `-fdebug-info-for-profiling`) used during instrumentation are also passed during this compilation step to enable correct matching of the profile data. For the optimized binary to fully utilize the hot/cold hinting, it must be linked with an allocator that supports this mechanism, such as [tcmalloc](https://github.com/google/tcmalloc). TCMalloc provides an API (`tcmalloc::hot_cold_t`) that accepts a hint (0 for cold, 255 for hot) to guide data placement and improve locality. To indicate that the library supports these interfaces, the `-mllvm -supports-hot-cold-new` flag is used during the LTO link. -``` +::: ### Context Disambiguation (LTO) @@ -138,7 +138,7 @@ clang++ -fmemory-profile-use=memprof.memprofdata -fpartition-static-data-section The optimized layout clusters hot static data, improving dTLB and cache efficiency. -```{note} +:::{note} When both PGO profiles and memory profiles are provided (using `-fprofile-use` and `-fmemory-profile-use`), global variable hotness are inferred from a combination of PGO profile and data access profile: @@ -150,7 +150,7 @@ inferred from a combination of PGO profile and data access profile: profile. Most notably, symbolizable data with external linkage is only covered by data access profile, and module-internal unsymbolizable data is only covered by PGO profile. -``` +::: ## Developer Manual diff --git a/llvm/docs/Passes.md b/llvm/docs/Passes.md index 60366dddbd300..1615d8890bd85 100644 --- a/llvm/docs/Passes.md +++ b/llvm/docs/Passes.md @@ -11,11 +11,11 @@ LoopFusion ## Introduction -```{warning} +:::{warning} This document is not updated frequently, and the list of passes is most likely incomplete. It is possible to list passes known by the opt tool using `opt -print-passes`. -``` +::: This document serves as a high-level summary of the optimization features that LLVM provides. Optimizations are implemented as Passes that traverse some diff --git a/llvm/docs/ProgrammersManual.md b/llvm/docs/ProgrammersManual.md index e704e852c2031..04d5bb273f686 100644 --- a/llvm/docs/ProgrammersManual.md +++ b/llvm/docs/ProgrammersManual.md @@ -1,8 +1,8 @@ # LLVM Programmer's Manual -````{warning} +::::{warning} This is always a work in progress. -```` +:::: (introduction)= ## Introduction @@ -425,14 +425,14 @@ the program that can handle them appropriately. Handling the error may be as simple as reporting the issue to the user, or it may involve attempts at recovery. -````{note} +::::{note} While it would be ideal to use this error handling scheme throughout LLVM, there are places where this hasn't been practical to apply. In situations where you absolutely must emit a non-programmatic error and the `Error` model isn't workable you can call `reportFatalUsageError`, which will call installed error handlers, print a message, and exit the program. The use of `reportFatalUsageError` in this case is discouraged. -```` +:::: Recoverable errors are modeled using LLVM's `Error` scheme. This scheme represents errors using function return values, similar to classic C integer error codes, or C++'s `std::error_code`. However, the `Error` class is @@ -1556,7 +1556,7 @@ to keep `sizeof(SmallVector<T>)` around 64 bytes). platforms, since it uses `unsigned` (instead of `void*`) for its size and capacity. -````{note} +::::{note} Prefer to use `ArrayRef<T>` or `SmallVectorImpl<T>` as a parameter type. It's rarely appropriate to use `SmallVector<T, N>` as a parameter type. @@ -1592,7 +1592,7 @@ void someFunc2() { Even though it has "`Impl`" in the name, SmallVectorImpl is widely used and is no longer "private to the implementation". A name like `SmallVectorHeader` might be more appropriate. -```` +:::: (dss_pagedvector)= #### llvm/ADT/PagedVector.h diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md index f8fce847b62f3..efd33a907cfa7 100644 --- a/llvm/docs/ReleaseNotes.md +++ b/llvm/docs/ReleaseNotes.md @@ -7,12 +7,12 @@ ReleaseNotes.md and ReleaseNotesTemplate.txt. --> # LLVM {{env.config.release}} Release Notes -````{only} PreRelease -```{warning} These are in-progress notes for the upcoming LLVM {{env.config.release}} +::::{only} PreRelease +:::{warning} These are in-progress notes for the upcoming LLVM {{env.config.release}} release. Release notes for previous releases can be found on [the Download Page](https://releases.llvm.org/download.html). -``` -```` +::: +:::: ## Introduction diff --git a/llvm/docs/ReleaseNotesTemplate.txt b/llvm/docs/ReleaseNotesTemplate.txt index d0c4c1edbf5af..0f11bc0c7b4f7 100644 --- a/llvm/docs/ReleaseNotesTemplate.txt +++ b/llvm/docs/ReleaseNotesTemplate.txt @@ -9,12 +9,12 @@ ReleaseNotes.md and ReleaseNotesTemplate.txt. --> ```{contents} ``` -````{only} PreRelease -```{warning} These are in-progress notes for the upcoming LLVM {{env.config.release}} +::::{only} PreRelease +:::{warning} These are in-progress notes for the upcoming LLVM {{env.config.release}} release. Release notes for previous releases can be found on [the Download Page](https://releases.llvm.org/download.html). -``` -```` +::: +:::: ## Introduction diff --git a/llvm/docs/Remarks.md b/llvm/docs/Remarks.md index ca161094108e6..6f57e0a689e8d 100644 --- a/llvm/docs/Remarks.md +++ b/llvm/docs/Remarks.md @@ -59,20 +59,20 @@ Optimization remarks can be emitted as diagnostics. These diagnostics will be propagated to front-ends if desired, or emitted by tools like {doc}`llc <CommandGuide/llc>` or {doc}`opt <CommandGuide/opt>`. -```{option} -pass-remarks=<regex> +:::{option} -pass-remarks=<regex> Enables optimization remarks from passes whose name match the given (POSIX) regular expression. -``` +::: -```{option} -pass-remarks-missed=<regex> +:::{option} -pass-remarks-missed=<regex> Enables missed optimization remarks from passes whose name match the given (POSIX) regular expression. -``` +::: -```{option} -pass-remarks-analysis=<regex> +:::{option} -pass-remarks-analysis=<regex> Enables optimization analysis remarks from passes whose name match the given (POSIX) regular expression. -``` +::: ### Serialized remarks @@ -92,69 +92,69 @@ following options: `Basic options` -```{option} -pass-remarks-output=<filename> +:::{option} -pass-remarks-output=<filename> Enables the serialization of remarks to a file specified in `<filename>`. By default, the output is serialized to {ref}`YAML <yamlremarks>`. -``` +::: -```{option} -pass-remarks-format=<format> +:::{option} -pass-remarks-format=<format> Specifies the output format of the serialized remarks. Supported formats: - {ref}`yaml <yamlremarks>` (default) - {ref}`bitstream <bitstreamremarks>` -``` +::: `Content configuration` -```{option} -pass-remarks-filter=<regex> +:::{option} -pass-remarks-filter=<regex> Only passes whose name match the given (POSIX) regular expression will be serialized to the final output. -``` +::: -```{option} -pass-remarks-with-hotness +:::{option} -pass-remarks-with-hotness With PGO, include profile count in optimization remarks. -``` +::: -```{option} -pass-remarks-hotness-threshold +:::{option} -pass-remarks-hotness-threshold The minimum profile count required for an optimization remark to be emitted. -``` +::: Other tools that support remarks: {program}`llvm-lto` -```{option} -lto-pass-remarks-output=<filename> -``` +:::{option} -lto-pass-remarks-output=<filename> +::: -```{option} -lto-pass-remarks-filter=<regex> -``` +:::{option} -lto-pass-remarks-filter=<regex> +::: -```{option} -lto-pass-remarks-format=<format> -``` +:::{option} -lto-pass-remarks-format=<format> +::: -```{option} -lto-pass-remarks-with-hotness -``` +:::{option} -lto-pass-remarks-with-hotness +::: -```{option} -lto-pass-remarks-hotness-threshold -``` +:::{option} -lto-pass-remarks-hotness-threshold +::: {program}`gold-plugin` and {program}`lld` -```{option} -opt-remarks-filename=<filename> -``` +:::{option} -opt-remarks-filename=<filename> +::: -```{option} -opt-remarks-filter=<regex> -``` +:::{option} -opt-remarks-filter=<regex> +::: -```{option} -opt-remarks-format=<format> -``` +:::{option} -opt-remarks-format=<format> +::: -```{option} -opt-remarks-with-hotness -``` +:::{option} -opt-remarks-with-hotness +::: (yamlremarks)= diff --git a/llvm/docs/SourceLevelDebugging.md b/llvm/docs/SourceLevelDebugging.md index 5d3c6e0c723e4..45f55c73bcd2e 100644 --- a/llvm/docs/SourceLevelDebugging.md +++ b/llvm/docs/SourceLevelDebugging.md @@ -131,10 +131,10 @@ which can have a value, including at least: - Constants - Formal parameters -```{note} +:::{note} There is no special provision for "true" constants in LLVM today, and they are instead treated as local or global variables. -``` +::: A variable is represented by a {ref}`local variable <dilocalvariable>` or {ref}`global variable <diglobalvariable>` metadata node. @@ -149,10 +149,10 @@ The operands of the `DW_OP_LLVM_fragment` operation encode the bit offset of the fragment relative to the start of the variable, and the size of the fragment in bits, respectively. -```{note} +:::{note} The `DW_OP_LLVM_fragment` operation acts only to encode the fragment information, and does not have an effect on the semantics of the expression. -``` +::: (format)= ## Debugging information format @@ -324,10 +324,10 @@ See {doc}`AssignmentTracking` for more info. ### Debugger intrinsic functions -```{warning} +:::{warning} These intrinsics are deprecated, please use {ref}`debug records <debug_records>` instead. For more details see {doc}`RemoveDIs <RemoveDIsDebugInfo>`. -``` +::: (format_common_intrinsics)= In intrinsic-mode, LLVM uses several intrinsic functions (name prefixed with "`llvm.dbg`") to @@ -412,13 +412,13 @@ direct value. For example, if the first operand is an indirect value, it may be necessary to insert `DW_OP_deref` into the `DIExpression` in order to produce a valid debug record. -```{note} +:::{note} A `DIExpression` is interpreted in the same way regardless of which kind of debug record it's attached to. `DIExpression`s are always printed and parsed inline; they can never be referenced by an ID (e.g. `!1`). -``` +::: (dwarf-opcodes)= #### DWARF Opcodes @@ -462,11 +462,11 @@ vocabulary is limited, but includes at least: Where the DWARF equivalent is not suitable, or no DWARF equivalent exists, LLVM defines internal-only opcodes which have no direct analog in DWARF. -```{note} +:::{note} Some opcodes do not influence the final DWARF expression directly, instead encoding information logically belonging to the debug records which use them. -``` +::: - `DW_OP_LLVM_fragment, <offset>, <size>` may appear at most once in an expression, and must be the last opcode. It specifies the bit offset and bit size of the variable fragment being described by the record or intrinsic @@ -731,7 +731,7 @@ variable's new location. Compared with the `#dbg_declare` record: * A `#dbg_value` terminates the effects that any preceding records have on any common bits of a common variable. - ```{note} + :::{note} The current implementation generally terminates the effect of every record in its entirety if any of its effects would be terminated, rather than carrying forward the effect of previous records for non-overlapping @@ -741,7 +741,7 @@ variable's new location. Compared with the `#dbg_declare` record: One exception to this is {doc}`AssignmentTracking` where certain memory-based locations are carried forward partially in some situations. - ``` + ::: * The `#dbg_value`'s position in the IR defines where in the instruction stream the variable's value changes. * Operands can be constants, indicating the variable is assigned a diff --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md index cdd5ae72204ab..f4780a7d6c855 100644 --- a/llvm/docs/TestSuiteGuide.md +++ b/llvm/docs/TestSuiteGuide.md @@ -87,14 +87,14 @@ MicroBenchmarks/XRay microbenchmarks, you need to add `compiler-rt` to your ... ``` -```{note} +:::{note} Even when you only want compile-time results you still need to run the test with the above `llvm-lit` command. In this case, the `results.json` file will contain compile time metrics only (code size, llvm stats and so on). This mode is enabled by setting `-DTEST_SUITE_RUN_BENCHMARKS=OFF`, more details [here](common_configuration_options). -``` +::: 6. Show and compare result files (optional): diff --git a/llvm/docs/TestingGuide.md b/llvm/docs/TestingGuide.md index 4b034f4851af4..f3017993d781d 100644 --- a/llvm/docs/TestingGuide.md +++ b/llvm/docs/TestingGuide.md @@ -155,10 +155,10 @@ script which is built as part of LLVM. For example, to run the % llvm-lit <path to llvm-project>/llvm/test/Integer/BitPacked.ll ``` -```{note} +:::{note} The test files are in the `llvm-project` directory, not the directory you are building LLVM in. -``` +::: Or you can run a whole folder of tests. To run all of the ARM CodeGen tests: @@ -435,11 +435,11 @@ For convenience, these are the contents: For symmetry, `ident.ll` is just a dummy file that doesn't actually participate in the test besides holding the `RUN:` lines. -```{note} +:::{note} Some existing tests use `RUN: true` in extra files instead of just putting the extra files in an `Inputs/` directory. This pattern is deprecated. -``` +::: ### Elaborated tests @@ -492,7 +492,7 @@ clang --target=x86_64-linux -S -g a.cc -o - # content generated by the script 'gen' ``` -```{note} +:::{note} Consider specifying an explicit target triple to avoid differences when regeneration is needed on another machine. @@ -501,7 +501,7 @@ don't need `-fdebug-compilation-dir=` since its default value is `PWD`. Check prefixes should be placed before `.endif` since the part after `.endif` is replaced. -``` +::: If the test body contains multiple files, you can print `---` separators and utilize `split-file` in `RUN` lines. diff --git a/llvm/docs/WritingAnLLVMNewPMPass.md b/llvm/docs/WritingAnLLVMNewPMPass.md index 471214149f939..065c6b5bb0238 100644 --- a/llvm/docs/WritingAnLLVMNewPMPass.md +++ b/llvm/docs/WritingAnLLVMNewPMPass.md @@ -6,11 +6,11 @@ ## Introduction --- What is a pass? -```{warning} +:::{warning} This document deals with the new pass manager. LLVM uses the legacy pass manager for the codegen pipeline. For more details, see {doc}`WritingAnLLVMPass` and {doc}`NewPassManager`. -``` +::: The LLVM pass framework is an important part of the LLVM system, because LLVM passes are where most of the interesting parts of the compiler exist. Passes diff --git a/llvm/docs/WritingAnLLVMPass.md b/llvm/docs/WritingAnLLVMPass.md index c1cf43d0198d2..7d56a546a4dd7 100644 --- a/llvm/docs/WritingAnLLVMPass.md +++ b/llvm/docs/WritingAnLLVMPass.md @@ -6,13 +6,13 @@ ## Introduction --- What is a pass? -```{warning} +:::{warning} This document deals with the legacy pass manager. LLVM uses the new pass manager for the optimization pipeline (the codegen pipeline still uses the legacy pass manager), which has its own way of defining passes. For more details, see {doc}`WritingAnLLVMNewPMPass` and {doc}`NewPassManager`. -``` +::: The LLVM Pass Framework is an important part of the LLVM system, because LLVM passes are where most of the interesting parts of the compiler exist. Passes diff --git a/llvm/docs/index.md b/llvm/docs/index.md index e933810197c42..14a09935f9e9b 100644 --- a/llvm/docs/index.md +++ b/llvm/docs/index.md @@ -1,9 +1,9 @@ # About -```{warning} +:::{warning} If you are using a released version of LLVM, see [the download page] to find your documentation. -``` +::: [the download page]: https://llvm.org/releases/ >From 4525940478f8904a920e923a15d9ade8afa4995e Mon Sep 17 00:00:00 2001 From: Reid Kleckner <[email protected]> Date: Sat, 8 Aug 2026 03:08:27 +0000 Subject: [PATCH 3/3] [docs] Use colon fences in LLDB and Flang docs --- flang/docs/FAQ.md | 4 ++-- flang/docs/GettingStarted.md | 8 ++++---- flang/docs/ReleaseNotes.md | 8 ++++---- flang/docs/ReleaseNotesTemplate.txt | 8 ++++---- lldb/docs/use/aarch64-linux.md | 4 ++-- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/flang/docs/FAQ.md b/flang/docs/FAQ.md index c220d469380ce..b6a9069145cc8 100644 --- a/flang/docs/FAQ.md +++ b/flang/docs/FAQ.md @@ -32,11 +32,11 @@ An executable stack increases the risk and impact of certain classes of security Therefore, modern linkers often issue a warning or an error if an executable stack is not explicitly requested by the developer. For instance, the GNU Linker (`ld`) issues a warning while the LLVM Linker (`lld`) emits an error. -```{note} +:::{note} The trampoline code generated by Flang is not itself a security risk. The risk comes from the possibility of executing malicious code that an attacker has placed on the stack. You should determine whether such risks are appropriate for your software. -``` +::: When you use the Flang driver (the `flang` command) to generate executables, you can instruct the linker to enable an executable stack with the `-Wl,-z,execstack` or `-Xlinker -zexecstack` flag. diff --git a/flang/docs/GettingStarted.md b/flang/docs/GettingStarted.md index 62920bbb73ce4..98620e6eafb07 100644 --- a/flang/docs/GettingStarted.md +++ b/flang/docs/GettingStarted.md @@ -86,14 +86,14 @@ cmake \ ninja ``` -```{note} +:::{note} Contributions to Flang are expected not to produce any new compiler warnings. This is enforced by post-commit buildbots. To do the same locally, add `-DFLANG_ENABLE_WERROR=ON` to the above `cmake` command. Only Clang builds are checked for this, so we do not recommend using this option with GCC as there will be preexisting warnings. -``` +::: On Darwin, to make flang able to link binaries with the default sysroot without having to specify additional flags, use the `DEFAULT_SYSROOT` CMake flag, e.g. @@ -163,14 +163,14 @@ cmake \ ninja ``` -```{note} +:::{note} Contributions to Flang are expected not to produce any new compiler warnings. This is enforced by post-commit buildbots. To do the same locally, add `-DFLANG_ENABLE_WERROR=ON` to the above `cmake` command. Only Clang builds are checked for this, so we do not recommend using this option with GCC as there will be preexisting warnings. -``` +::: To run the flang tests on this build, execute the command in the `flang/build` directory: diff --git a/flang/docs/ReleaseNotes.md b/flang/docs/ReleaseNotes.md index 2871b4b66c155..bbc7084c4a757 100644 --- a/flang/docs/ReleaseNotes.md +++ b/flang/docs/ReleaseNotes.md @@ -3,13 +3,13 @@ ReleaseNotes.md and ReleaseNotesTemplate.txt. --> # Flang {{version}} {{in_progress}}Release Notes -````{only} PreRelease -```{warning} +::::{only} PreRelease +:::{warning} These are in-progress notes for the upcoming LLVM {{version}} release. Release notes for previous releases can be found on [the Download Page](https://releases.llvm.org/download.html). -``` -```` +::: +:::: ## Introduction diff --git a/flang/docs/ReleaseNotesTemplate.txt b/flang/docs/ReleaseNotesTemplate.txt index 888da4d58b868..0d320d364ba95 100644 --- a/flang/docs/ReleaseNotesTemplate.txt +++ b/flang/docs/ReleaseNotesTemplate.txt @@ -3,13 +3,13 @@ ReleaseNotes.md and ReleaseNotesTemplate.txt. --> # Flang {{version}} {{in_progress}}Release Notes -````{only} PreRelease -```{warning} +::::{only} PreRelease +:::{warning} These are in-progress notes for the upcoming LLVM {{version}} release. Release notes for previous releases can be found on [the Download Page](https://releases.llvm.org/download.html). -``` -```` +::: +:::: ## Introduction diff --git a/lldb/docs/use/aarch64-linux.md b/lldb/docs/use/aarch64-linux.md index 20f2db44e749d..eda848164a3d6 100644 --- a/lldb/docs/use/aarch64-linux.md +++ b/lldb/docs/use/aarch64-linux.md @@ -112,7 +112,7 @@ In LLDB you will see the following new registers: to the vector length of non-streaming mode and may change independently. This register is read only. -```{note} +:::{note} While in non-streaming mode, the `vg` register shows the non-streaming vector length, and the `svg` register shows the streaming vector length. When in streaming mode, both `vg` and `svg` show the streaming mode vector @@ -120,7 +120,7 @@ In LLDB you will see the following new registers: vector length within LLDB, while in streaming mode. This is a limitation of the LLDB implementation not the architecture, which stores both lengths independently. -``` +::: In the example below, the streaming vector length is 16 bytes and we are in streaming mode. Note that bits 0 and 1 of `svcr` are set, indicating that we _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
