[llvm-branch-commits] [lldb] [llvm] [openmp] [docs] Finish MyST migration for leftover docs (PR #234787)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Oct 22 19:20:09 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-testing-tools
Author: Reid Kleckner (rnk)
<details>
<summary>Changes</summary>
This PR mops up the remaining one-off rst files around the repo, as well as the LLDB man pages, which we decided to migrate after we decided not to block on RHEL myst parser dependencies.
Agent migration notes:
- Converted the SYNOPSIS and command synopsis line blocks in the lldb man pages to `:::{line-block}` fences containing `{program}` roles because the docs toolchain pins myst-parser 5.1.0, which supports the `line-block` directive. The generated man pages and the HTML line blocks are identical to the `{eval-rst}` versions.
- Converted `.. program::` to the native `{program}` directive because it renders identically to the baseline man page.
- Verified the generated `lldb.1` and `lldb-server.1` are byte-identical to the ones built from the `.rst` sources, and that `lldb/test/Shell/Driver/TestHelp.test` still passes its FileCheck patterns against `lldb.md`.
- Renamed the VariableNames footnote labels to match the old citation IDs, and fixed the `Hähnle` label to match its references, because the old reST citation IDs are link targets.
- Added `footnote_transition: false` front matter to VariableNames because its References section contains only footnotes and the default footnote transition made the build fail; other migrated proposals use the same setting.
- Replaced the VariableNames `../CodingStandards.html` links with `../CodingStandards.md` because MyST checks source links and the `.html` form produced missing-reference warnings.
- Accepted that VariableNames citations now render as numbered footnotes, with the `[*]` note moved to the end of the page, because native MyST footnotes render that way; this accounts for the visual diff hunks.
- Wrote the lit, gn, cmake and OpenMP Modules READMEs as plain CommonMark/GFM (dropped the `contents` directives and unused labels, converted block quotes used for lists and commands to lists and fenced `sh` blocks) because GitHub and PyPI render them and they are not part of any Sphinx build.
- Added `long_description_content_type="text/markdown"` to lit's `setup.py` because the long description is now Markdown.
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #<!-- -->234786, which is a standalone commit that
renames *.rst -> *.md before this PR lands for history preservation purposes.
This was prepared with rst2myst plus LLM-assisted cleanup.
---
Patch is 76.37 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/234787.diff
8 Files Affected:
- (modified) cmake/README.md (+26-32)
- (modified) lldb/docs/man/lldb-server.md (+114-118)
- (modified) lldb/docs/man/lldb.md (+210-216)
- (modified) llvm/docs/Proposals/VariableNames.md (+312-279)
- (modified) llvm/utils/gn/README.md (+38-60)
- (modified) llvm/utils/lit/README.md (+32-35)
- (modified) llvm/utils/lit/setup.py (+1)
- (modified) openmp/tools/Modules/README.md (+17-22)
``````````diff
diff --git a/cmake/README.md b/cmake/README.md
index eb6ee30ea0d17..51e3899743de0 100644
--- a/cmake/README.md
+++ b/cmake/README.md
@@ -1,59 +1,53 @@
-=======================
-LLVM Common CMake Utils
-=======================
+# LLVM Common CMake Utils
-What goes here
---------------
+## What goes here
These are CMake modules to be shared between LLVM projects strictly at build
time. In other words, they must not be included from an installed CMake module,
-such as the ``Add*.cmake`` ones. Modules that are reachable from installed
-modules should instead go in ``${project}/cmake/modules`` of the most upstream
+such as the `Add*.cmake` ones. Modules that are reachable from installed
+modules should instead go in `${project}/cmake/modules` of the most upstream
project that uses them.
The advantage of not putting these modules in an existing location like
-``llvm/cmake/modules`` is two-fold:
+`llvm/cmake/modules` is two-fold:
- Since they are not installed, we don't have to worry about any out-of-tree
downstream usage, and thus there is no need for stability.
-
- Since they are available as part of the source at build-time, we don't have
to do the usual stand-alone vs combined-build dances, avoiding much
complexity.
-How to use
-----------
+## How to use
For tools, please do:
-.. code-block:: cmake
-
- if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS)
- set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
- endif()
+```cmake
+if(NOT DEFINED LLVM_COMMON_CMAKE_UTILS)
+ set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
+endif()
- # Add path for custom modules.
- list(INSERT CMAKE_MODULE_PATH 0
- # project-specific module dirs first
- "${LLVM_COMMON_CMAKE_UTILS}/Modules"
- )
+# Add path for custom modules.
+list(INSERT CMAKE_MODULE_PATH 0
+ # project-specific module dirs first
+ "${LLVM_COMMON_CMAKE_UTILS}/Modules"
+ )
+```
Notes:
-- The ``if(NOT DEFINED ...)`` guard is there because in combined builds, LLVM
- will set this variable. This is useful for legacy builds where projects are
- found in ``llvm/tools`` instead.
-
-- ``INSERT ... 0`` ensures these new entries are prepended to the front of the
+- The `if(NOT DEFINED ...)` guard is there because in combined builds, LLVM
+ will set this variable. This is useful for legacy builds where projects are
+ found in `llvm/tools` instead.
+- `INSERT ... 0` ensures these new entries are prepended to the front of the
module path, so nothing might shadow them by mistake.
-For runtime libs, we skip the ``if(NOT DEFINED`` part:
-
-.. code-block:: cmake
+For runtime libs, we skip the `if(NOT DEFINED` part:
- set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
+```cmake
+set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
- ... # same as before
+... # same as before
+```
-If ``llvm/tools`` legacy-style combined builds are deprecated, we should then
+If `llvm/tools` legacy-style combined builds are deprecated, we should then
skip it everywhere, bringing the tools and runtimes boilerplate back in line.
diff --git a/lldb/docs/man/lldb-server.md b/lldb/docs/man/lldb-server.md
index cd1801eafa97e..c20b3023586c6 100644
--- a/lldb/docs/man/lldb-server.md
+++ b/lldb/docs/man/lldb-server.md
@@ -1,157 +1,153 @@
-:orphan:
+---
+orphan: true
+---
-lldb-server -- Server for LLDB Debugging Sessions
-=================================================
+# lldb-server -- Server for LLDB Debugging Sessions
-.. program:: lldb-server
+```{program} lldb-server
+```
-SYNOPSIS
---------
+## SYNOPSIS
-| :program:`lldb-server` v[ersion]
-| :program:`lldb-server` g[dbserver] [*options*]
-| :program:`lldb-server` p[latform] [*options*]
+:::{line-block}
+{program}`lldb-server` v[ersion]
+{program}`lldb-server` g[dbserver] [*options*]
+{program}`lldb-server` p[latform] [*options*]
+:::
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`lldb-server` provides the server counterpart of the LLVM debugger.
+{program}`lldb-server` provides the server counterpart of the LLVM debugger.
The server runs and monitors the debugged program, while the user interfaces
with it via a client, either running locally or connecting remotely.
All of the code in the LLDB project is available under the Apache 2.0 License
with LLVM exceptions.
-COMMANDS
---------
+## COMMANDS
The first argument to lldb-server specifies a command to run.
-.. option:: v[ersion]
+:::{option} v[ersion]
+Prints lldb-server version and exits.
+:::
- Prints lldb-server version and exits.
+:::{option} g[dbserver]
+Runs the server using the gdb-remote protocol. LLDB can afterwards
+connect to the server using *gdb-remote* command.
+:::
-.. option:: g[dbserver]
+:::{option} p[latform]
+Runs the platform server. LLDB can afterwards connect to the server using
+*platform select*, followed by *platform connect*.
+:::
- Runs the server using the gdb-remote protocol. LLDB can afterwards
- connect to the server using *gdb-remote* command.
+## GDBSERVER COMMAND
-.. option:: p[latform]
+:::{line-block}
+{program}`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...]
+:::
- Runs the platform server. LLDB can afterwards connect to the server using
- *platform select*, followed by *platform connect*.
+### CONNECTION
-GDBSERVER COMMAND
------------------
+:::{option} host:port
+Specifies the hostname and TCP port to listen on. Obligatory unless another
+listening option is used. If host is empty, *localhost* will be used. If port
+is zero, a random port will be selected, and written as specified by --pipe
+or --named-pipe options.
+:::
-| :program:`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...]
+:::{option} --fd <fd>
+Communicate over the given file descriptor instead of sockets.
+:::
-CONNECTION
-~~~~~~~~~~
+:::{option} --named-pipe <name>
+Write the listening port number to the specified named pipe.
+:::
-.. option:: host:port
+:::{option} --pipe <fd>
+Write the listening port number to the specified pipe (fd).
+:::
- Specifies the hostname and TCP port to listen on. Obligatory unless another
- listening option is used. If host is empty, *localhost* will be used. If port
- is zero, a random port will be selected, and written as specified by --pipe
- or --named-pipe options.
+:::{option} --reverse-connect
+Connect to the client instead of passively waiting for a connection. In this
+case, [host]:port denotes the remote address to connect to.
+:::
-.. option:: --fd <fd>
+### GENERAL OPTIONS
- Communicate over the given file descriptor instead of sockets.
+:::{option} --help
+Prints out the usage information and exits.
+:::
-.. option:: --named-pipe <name>
+:::{option} --log-channels <channel1 categories...:channel2 categories...>
+Channels to log. A colon-separated list of entries. Each entry starts with
+a channel followed by a space-separated list of categories.
+:::
- Write the listening port number to the specified named pipe.
+:::{option} --log-file <file>
+Destination file to log to. If empty, log to stderr.
+:::
-.. option:: --pipe <fd>
+:::{option} --setsid
+Run lldb-server in a new session.
+:::
- Write the listening port number to the specified pipe (fd).
+### TARGET SELECTION
-.. option:: --reverse-connect
+:::{option} --attach <pid-or-name>
+Attach to the process given by a (numeric) process id or a name.
+:::
- Connect to the client instead of passively waiting for a connection. In this
- case, [host]:port denotes the remote address to connect to.
+:::{option} -- program args
+Launch a program for debugging.
+:::
-GENERAL OPTIONS
-~~~~~~~~~~~~~~~
-
-.. option:: --help
-
- Prints out the usage information and exits.
-
-.. option:: --log-channels <channel1 categories...:channel2 categories...>
-
- Channels to log. A colon-separated list of entries. Each entry starts with
- a channel followed by a space-separated list of categories.
-
-.. option:: --log-file <file>
-
- Destination file to log to. If empty, log to stderr.
-
-.. option:: --setsid
-
- Run lldb-server in a new session.
-
-TARGET SELECTION
-~~~~~~~~~~~~~~~~
-
-.. option:: --attach <pid-or-name>
-
- Attach to the process given by a (numeric) process id or a name.
-
-.. option:: -- program args
-
- Launch a program for debugging.
-
-If neither of target options are used, :program:`lldb-server` is started
+If neither of target options are used, {program}`lldb-server` is started
without a specific target. It can be afterwards instructed by the client
to launch or attach.
-PLATFORM COMMAND
-----------------
-
-| :program:`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*]
-
-CONNECTION
-~~~~~~~~~~
-
-.. option:: --server
-
- Run in server mode, handling multiple connections. If this is not specified,
- lldb-server will accept only one connection and exit when it is finished.
-
-.. option:: --listen <host>:<port>
-
- Hostname and port to listen on. Obligatory. If *port* is zero, a random port
- will be used.
+## PLATFORM COMMAND
-.. option:: --socket-file <path>
+:::{line-block}
+{program}`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*]
+:::
- Write the listening socket port number to the specified file.
+### CONNECTION
-GENERAL OPTIONS
-~~~~~~~~~~~~~~~
+:::{option} --server
+Run in server mode, handling multiple connections. If this is not specified,
+lldb-server will accept only one connection and exit when it is finished.
+:::
-.. option:: --log-channels <channel1 categories...:channel2 categories...>
+:::{option} --listen <host>:<port>
+Hostname and port to listen on. Obligatory. If *port* is zero, a random port
+will be used.
+:::
- Channels to log. A colon-separated list of entries. Each entry starts with
- a channel followed by a space-separated list of categories.
+:::{option} --socket-file <path>
+Write the listening socket port number to the specified file.
+:::
-.. option:: --log-file <file>
+### GENERAL OPTIONS
- Destination file to log to. If empty, log to stderr.
+:::{option} --log-channels <channel1 categories...:channel2 categories...>
+Channels to log. A colon-separated list of entries. Each entry starts with
+a channel followed by a space-separated list of categories.
+:::
-GDB-SERVER CONNECTIONS
-~~~~~~~~~~~~~~~~~~~~~~
+:::{option} --log-file <file>
+Destination file to log to. If empty, log to stderr.
+:::
-.. option:: --gdbserver-port <port>
+### GDB-SERVER CONNECTIONS
- Define a port to be used for gdb-server connections. This port is used for
- multiple connections.
+:::{option} --gdbserver-port <port>
+Define a port to be used for gdb-server connections. This port is used for
+multiple connections.
+:::
-EXAMPLES
---------
+## EXAMPLES
The server can be started in several modes.
@@ -162,35 +158,35 @@ to the debugged executable, arguments starting with a - must be passed after
--. The server will launch the new executable and stop it immediately, waiting
for the client to connect.
- lldb-server g :1234 /path/to/program program-argument -- --program-option
+> lldb-server g :1234 /path/to/program program-argument -- --program-option
For convenience, passing the executable after -- is also supported.
- lldb-server g :1234 -- /path/to/program program-argument --program-option
+> lldb-server g :1234 -- /path/to/program program-argument --program-option
In order to attach to a running process, pass --attach along with the process
identifier or name. The process will be stopped immediately after starting
the server. Note that terminating the server will usually cause the process
to be detached and continue execution.
- lldb-server g :1234 --attach 12345
- lldb-server g :1234 --attach program-name
+> lldb-server g :1234 --attach 12345
+> lldb-server g :1234 --attach program-name
Use *gdb-remote* command to connect to the server:
- (lldb) gdb-remote 1234
+> (lldb) gdb-remote 1234
lldb-server can also be started without an inferior. In this case, the client
can select the target after connecting to the server. Note that some commands
(e.g. *target create*) will disconnect and launch a local lldb-server instead.
- lldb-server g :1234
+> lldb-server g :1234
+>
+> (lldb) gdb-remote 1234
+> (lldb) process launch a.out
- (lldb) gdb-remote 1234
- (lldb) process launch a.out
+## SEE ALSO
-SEE ALSO
---------
+The {doc}`LLDB project page </index>` has many different resources
+for {program}`lldb-server` users.
-The :doc:`LLDB project page </index>` has many different resources
-for :program:`lldb-server` users.
diff --git a/lldb/docs/man/lldb.md b/lldb/docs/man/lldb.md
index 0a2a2093f8c6b..dab6fbdc8843b 100644
--- a/lldb/docs/man/lldb.md
+++ b/lldb/docs/man/lldb.md
@@ -1,257 +1,253 @@
-:orphan:
+---
+orphan: true
+---
-lldb -- The Debugger
-====================
+# lldb -- The Debugger
-.. program:: lldb
+```{program} lldb
+```
-SYNOPSIS
---------
+## SYNOPSIS
-| :program:`lldb` [*options*] *executable*
+:::{line-block}
+{program}`lldb` [*options*] *executable*
+:::
-DESCRIPTION
------------
+## DESCRIPTION
-:program:`lldb` is a next generation, high-performance debugger. It is built as
+{program}`lldb` is a next generation, high-performance debugger. It is built as
a set of reusable components which highly leverage existing libraries in the
larger LLVM Project, such as the Clang expression parser and LLVM disassembler.
-:program:`lldb` is the default debugger in Xcode on macOS and supports
+{program}`lldb` is the default debugger in Xcode on macOS and supports
debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
All of the code in the LLDB project is available under the Apache 2.0 License
with LLVM exceptions.
-ATTACHING
----------
+## ATTACHING
-.. option:: --attach-name <name>
+:::{option} --attach-name <name>
+Tells the debugger to attach to a process with the given name.
+:::
- Tells the debugger to attach to a process with the given name.
+:::{option} --attach-pid <pid>
+Tells the debugger to attach to a process with the given pid.
+:::
-.. option:: --attach-pid <pid>
+:::{option} -n <value>
+Alias for --attach-name
+:::
- Tells the debugger to attach to a process with the given pid.
+:::{option} -p <value>
+Alias for --attach-pid
+:::
-.. option:: -n <value>
+:::{option} --wait-for
+Tells the debugger to wait for a process with the given pid or name to launch before attaching.
+:::
- Alias for --attach-name
+:::{option} -w
+Alias for --wait-for
+:::
-.. option:: -p <value>
+## COMMANDS
- Alias for --attach-pid
+:::{option} --batch
+Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.
+:::
-.. option:: --wait-for
+:::{option} -b
+Alias for --batch
+:::
- Tells the debugger to wait for a process with the given pid or name to launch before attaching.
+:::{option} -K <value>
+Alias for --source-on-crash
+:::
-.. option:: -w
+:::{option} -k <value>
+Alias for --one-line-on-crash
+:::
- Alias for --wait-for
+:::{option} --local-lldbinit
+Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.
+:::
-COMMANDS
---------
+:::{option} --no-lldbinit
+Do not automatically parse any '.lldbinit' files.
+:::
-.. option:: --batch
+:::{option} --one-line-before-file <command>
+Tells the debugger to execute this one-line lldb command before any file provided on the command line has been loaded.
+:::
- Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.
+:::{option} --one-line-on-crash <command>
+When in batch mode, tells the debugger to run this one-line lldb command if the target crashes.
+:::
-.. option:: -b
+:::{option} --one-line <command>
+Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded.
+:::
- Alias for --batch
+:::{option} -O <value>
+Alias for --one-line-before-file
+:::
-.. option:: -K <value>
+:::{option} -o <value>
+Alias for --one-line
+:::
- Alias for --source-on-crash
+:::{option} -Q
+Alias for --source-quietly
+:::
-.. option:: -k <value>
+:::{option} --source-before-file <file>
+Tells the debugger to read in and execute the lldb commands in the given file, before any file has been loaded.
+:::
- Alias for --one-line-on-crash
+:::{option} --source-on-crash <file>
+When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
+:::
-.. option:: --local-lldbinit
+:::{option} --source-quietly
+Tells the debugger not to echo commands while sourcing files or one-line commands provided on the command line.
+:::
- Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.
+:::{option} --source <file>
+Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded.
+:::
-.. option:: --no-lldbinit
+:::{option} -S <value>
+Alias for --source-before-file
+:::
- Do not automatically parse any '.lldbinit' files.
+:::{option} -s <value>
+Alias for --source
+:::
-.. option:: --one-line-before-file <command>
+:::{option} -x
+Alias for --no-lldbinit
+:::
- Tells the debugger to execute this one-line lldb command before any file provided on the command line has been loaded.
+## OPTIONS
-.. option:: --one-line-on-crash <command>
+:::{option} --arch <architecture>
+Tells the debugger to use the specified architecture when starting and running the program.
+:::
- When in batch mode, tells the debugger to run this one-line lldb command if the target crashes.
+:::{option} -a <value>
+Alias for --arch
+:::
-.. option:: --one-line <command>
+:::{option} --capture-path <filename>
+Tells the debugger to use the given filename for the reproducer.
+:::
- Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded.
+:::{option} --capture
+Tells the debugger to capture a reproducer.
+:::
-.. option:: -O <value>
+:::{option} --core <filename>
+Tells the debugger to use the full path to \<filename> as the core file.
+:::
- Alias for --one-line-before-file
+:::{option} -c <value>
+Alias for --core
+:::
-.. option:: -o <value>
+:::{option} --debug
+Tells the debugger to print out extra information for debugging itself.
+:::
- Alias for --one-line
+:::{option} -d
+Alias for --debug
+:::
-.. option:: -Q
+:::{option} --editor
+Tells the debugger to open source files using the host's "external editor" mechanism.
+:::
- Alias for --source-quietly
+:::{option} -e
+Alias for --editor
+:::
-.. option:: --source-before-file <file>
+:::{option} --file <filename>
+Tells the debugger to use the file \<filename> as the program to be debugged.
+:::
- Tells the debugger to read in and execute the lldb commands in the given file, before any file has been loaded.
+:::{option} -f <value>
+Alias for --file
+:::
-.. option:: --source-on-crash <file>
+:::{option} --help
+Prints out the usage information for the LLDB debugger.
+:::
- When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
+:::{option} -h
+Alias for --help
+:::
-.. option:: --source-quietly
+:::{option} --no-use-colors
+Do not use colors.
+:::
- Tells the debugger not to echo commands while sourcing files or one-line commands provided on the command line.
+:::{option} --replay <filename>
+Tells the debugger to replay a reproducer from \<filename>.
+:::
-.. option:: --source <file>
+:::{option} --version
+Prints out the current version number of the LLDB debugger.
+:::
- Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded.
+:::{option} -v
+Alias for --version
+:::
-.. option:: -S <value>
+:::{option} -X
+Alias for --no-use-color
+:::
- Alias for --source-before-file
+## REPL
-.. option:: -s <value>
+:::{option} -r=<flags>
+Alias for --repl=\<flags>
+:::
- Alias for --source
+:::{option} --repl-language <language>
+Chooses the language for the REPL.
+:::
-.. option:: -x
+:::{option} --repl=<flags>
+Runs lldb in REPL mode with a stub process with the given flags.
+:::
- Alias for --no-lldbinit
+:::{option} -R <value>
+Alias for --repl-language
+:::
-OPTIONS
--------
+## SCRIPTING
-.. option:: --arch <architecture>
+:::{option} -l <value>
+Alias for --script-language
+:::
- Tells the deb...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/234787
More information about the llvm-branch-commits
mailing list