llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-llvm-ir Author: Reid Kleckner (rnk) <details> <summary>Changes</summary> 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 --- Patch is 67.25 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/214921.diff 47 Files Affected: - (modified) clang/docs/LanguageExtensions.md (+4-4) - (modified) clang/docs/LifetimeSafety.md (+6-6) - (modified) clang/docs/MisExpect.md (+6-6) - (modified) clang/docs/ReleaseNotes.md (+5-4) - (modified) clang/docs/ReleaseNotesTemplate.txt (+5-4) - (modified) clang/docs/Toolchain.md (+8-8) - (modified) flang/docs/FAQ.md (+2-2) - (modified) flang/docs/GettingStarted.md (+4-4) - (modified) flang/docs/ReleaseNotes.md (+4-4) - (modified) flang/docs/ReleaseNotesTemplate.txt (+4-4) - (modified) lldb/docs/use/aarch64-linux.md (+2-2) - (modified) llvm/docs/AMDGPUMemoryModel.md (+4-4) - (modified) llvm/docs/AliasAnalysis.md (+8-8) - (modified) llvm/docs/BitCodeFormat.md (+8-8) - (modified) llvm/docs/BuildingADistribution.md (+6-6) - (modified) llvm/docs/CMake.md (+8-8) - (modified) llvm/docs/CodeGenerator.md (+14-14) - (modified) llvm/docs/CodingStandards.md (+4-4) - (modified) llvm/docs/CommandLine.md (+6-6) - (modified) llvm/docs/CompilerWriterInfo.md (+2-2) - (modified) llvm/docs/Contributing.md (+6-6) - (modified) llvm/docs/Coroutines.md (+4-4) - (modified) llvm/docs/CoverageMappingFormat.md (+2-2) - (modified) llvm/docs/DeveloperPolicy.md (+4-4) - (modified) llvm/docs/ExceptionHandling.md (+4-4) - (modified) llvm/docs/GettingStarted.md (+6-6) - (modified) llvm/docs/GettingStartedVS.md (+2-2) - (modified) llvm/docs/GitHub.md (+12-12) - (modified) llvm/docs/HowToBuildWithPGO.md (+2-2) - (modified) llvm/docs/HowToCrossCompileLLVM.md (+4-4) - (modified) llvm/docs/InstrProfileFormat.md (+16-16) - (modified) llvm/docs/LangRef.md (+22-22) - (modified) llvm/docs/Lexicon.md (+2-2) - (modified) llvm/docs/MIRLangRef.md (+2-2) - (modified) llvm/docs/MemProf.md (+6-6) - (modified) llvm/docs/Passes.md (+2-2) - (modified) llvm/docs/ProgrammersManual.md (+6-6) - (modified) llvm/docs/ReleaseNotes.md (+4-4) - (modified) llvm/docs/ReleaseNotesTemplate.txt (+4-4) - (modified) llvm/docs/Remarks.md (+34-34) - (modified) llvm/docs/SourceLevelDebugging.md (+12-12) - (modified) llvm/docs/SphinxQuickstartTemplate.md (+23) - (modified) llvm/docs/TestSuiteGuide.md (+2-2) - (modified) llvm/docs/TestingGuide.md (+6-6) - (modified) llvm/docs/WritingAnLLVMNewPMPass.md (+2-2) - (modified) llvm/docs/WritingAnLLVMPass.md (+2-2) - (modified) llvm/docs/index.md (+2-2) ``````````diff 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/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 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 ... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/214921 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
