[llvm-branch-commits] [lldb] [llvm] [openmp] [docs] Finish MyST migration for leftover docs (PR #234787)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Oct 22 19:16:48 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/234787
>From 8acb70bd290db838d5b180cee8d2ebe7aec9f033 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Thu, 22 Oct 2026 18:50:06 +0000
Subject: [PATCH 1/2] [docs] Convert leftover rst docs with rst2myst
Mechanical rst2myst output for the renamed documents; no manual cleanup.
LLM-aided
---
cmake/README.md | 59 ++-
lldb/docs/man/lldb-server.md | 243 ++++++-----
lldb/docs/man/lldb.md | 431 ++++++++++----------
llvm/docs/Proposals/VariableNames.md | 588 ++++++++++++++-------------
llvm/utils/gn/README.md | 99 ++---
llvm/utils/lit/README.md | 61 ++-
openmp/tools/Modules/README.md | 41 +-
7 files changed, 784 insertions(+), 738 deletions(-)
diff --git a/cmake/README.md b/cmake/README.md
index eb6ee30ea0d17c..b3b1f67544fcab 100644
--- a/cmake/README.md
+++ b/cmake/README.md
@@ -1,59 +1,54 @@
-=======================
-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:
+For runtime libs, we skip the `if(NOT DEFINED` part:
-.. code-block:: cmake
+```cmake
+set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../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 cd1801eafa97e1..c0cd4d26ba560d 100644
--- a/lldb/docs/man/lldb-server.md
+++ b/lldb/docs/man/lldb-server.md
@@ -1,157 +1,200 @@
-:orphan:
+---
+orphan: true
+---
-lldb-server -- Server for LLDB Debugging Sessions
-=================================================
+# lldb-server -- Server for LLDB Debugging Sessions
+```{eval-rst}
.. program:: lldb-server
+```
-SYNOPSIS
---------
+## SYNOPSIS
-| :program:`lldb-server` v[ersion]
-| :program:`lldb-server` g[dbserver] [*options*]
-| :program:`lldb-server` p[latform] [*options*]
+{program}`lldb-server`
-DESCRIPTION
------------
+ v[ersion]
-:program:`lldb-server` provides the server counterpart of the LLVM debugger.
+{program}`lldb-server`
+
+ g[dbserver] \[
+
+*options*
+
+\]
+
+{program}`lldb-server`
+
+ p[latform] \[
+
+*options*
+
+\]
+
+## DESCRIPTION
+
+{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]
-
- Prints lldb-server version and exits.
+:::{option} v[ersion]
+Prints lldb-server version and exits.
+:::
-.. option:: g[dbserver]
+:::{option} g[dbserver]
+Runs the server using the gdb-remote protocol. LLDB can afterwards
+connect to the server using *gdb-remote* command.
+:::
- Runs the server using the gdb-remote protocol. LLDB can afterwards
- connect to the server using *gdb-remote* command.
+:::{option} p[latform]
+Runs the platform server. LLDB can afterwards connect to the server using
+*platform select*, followed by *platform connect*.
+:::
-.. option:: p[latform]
+## GDBSERVER COMMAND
- Runs the platform server. LLDB can afterwards connect to the server using
- *platform select*, followed by *platform connect*.
+{program}`lldb-server`
-GDBSERVER COMMAND
------------------
+ g[dbserver] \[
-| :program:`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...]
+*options*
-CONNECTION
-~~~~~~~~~~
+\] \[\[
-.. option:: host:port
+*host*
- 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:: --fd <fd>
+*port*
- Communicate over the given file descriptor instead of sockets.
+\] \[[--]
-.. option:: --named-pipe <name>
+*program*
- Write the listening port number to the specified named pipe.
+
-.. option:: --pipe <fd>
+*args*
- Write the listening port number to the specified pipe (fd).
+...\]
-.. option:: --reverse-connect
+### CONNECTION
- Connect to the client instead of passively waiting for a connection. In this
- case, [host]:port denotes the remote address to connect to.
+:::{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.
+:::
-GENERAL OPTIONS
-~~~~~~~~~~~~~~~
+:::{option} --fd <fd>
+Communicate over the given file descriptor instead of sockets.
+:::
-.. option:: --help
+:::{option} --named-pipe <name>
+Write the listening port number to the specified named pipe.
+:::
- Prints out the usage information and exits.
+:::{option} --pipe <fd>
+Write the listening port number to the specified pipe (fd).
+:::
-.. option:: --log-channels <channel1 categories...:channel2 categories...>
+:::{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.
+:::
- Channels to log. A colon-separated list of entries. Each entry starts with
- a channel followed by a space-separated list of categories.
+### GENERAL OPTIONS
-.. option:: --log-file <file>
+:::{option} --help
+Prints out the usage information and exits.
+:::
- 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.
+:::
-.. option:: --setsid
+:::{option} --log-file <file>
+Destination file to log to. If empty, log to stderr.
+:::
- Run lldb-server in a new session.
+:::{option} --setsid
+Run lldb-server in a new session.
+:::
-TARGET SELECTION
-~~~~~~~~~~~~~~~~
+### TARGET SELECTION
-.. option:: --attach <pid-or-name>
+:::{option} --attach <pid-or-name>
+Attach to the process given by a (numeric) process id or a name.
+:::
- Attach to the process given by a (numeric) process id or a name.
+:::{option} -- program args
+Launch a program for debugging.
+:::
-.. 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
-----------------
+## PLATFORM COMMAND
+
+{program}`lldb-server`
-| :program:`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*]
+ p[latform] \[
-CONNECTION
-~~~~~~~~~~
+*options*
-.. option:: --server
+\] --server --listen \[\[
- 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.
+*host*
-.. option:: --listen <host>:<port>
+\]:
- Hostname and port to listen on. Obligatory. If *port* is zero, a random port
- will be used.
+*port*
-.. option:: --socket-file <path>
+\]
- 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 +205,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 0a2a2093f8c6bb..0a9f2b96a58603 100644
--- a/lldb/docs/man/lldb.md
+++ b/lldb/docs/man/lldb.md
@@ -1,257 +1,260 @@
-:orphan:
+---
+orphan: true
+---
-lldb -- The Debugger
-====================
+# lldb -- The Debugger
+```{eval-rst}
.. program:: lldb
+```
-SYNOPSIS
---------
+## SYNOPSIS
-| :program:`lldb` [*options*] *executable*
+{program}`lldb`
-DESCRIPTION
------------
+ \[
-:program:`lldb` is a next generation, high-performance debugger. It is built as
+*options*
+
+\]
+
+*executable*
+
+## DESCRIPTION
+
+{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
----------
-
-.. option:: --attach-name <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:: -n <value>
-
- Alias for --attach-name
-
-.. option:: -p <value>
-
- Alias for --attach-pid
-
-.. option:: --wait-for
-
- Tells the debugger to wait for a process with the given pid or name to launch before attaching.
-
-.. option:: -w
-
- Alias for --wait-for
-
-COMMANDS
---------
-
-.. option:: --batch
-
- Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.
-
-.. option:: -b
-
- Alias for --batch
-
-.. option:: -K <value>
-
- Alias for --source-on-crash
-
-.. option:: -k <value>
-
- Alias for --one-line-on-crash
-
-.. option:: --local-lldbinit
-
- Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.
-
-.. option:: --no-lldbinit
-
- Do not automatically parse any '.lldbinit' files.
+## ATTACHING
-.. option:: --one-line-before-file <command>
+:::{option} --attach-name <name>
+Tells the debugger to attach to a process with the given name.
+:::
- Tells the debugger to execute this one-line lldb command before any file provided on the command line has been loaded.
+:::{option} --attach-pid <pid>
+Tells the debugger to attach to a process with the given pid.
+:::
-.. option:: --one-line-on-crash <command>
+:::{option} -n <value>
+Alias for --attach-name
+:::
- When in batch mode, tells the debugger to run this one-line lldb command if the target crashes.
+:::{option} -p <value>
+Alias for --attach-pid
+:::
-.. option:: --one-line <command>
+:::{option} --wait-for
+Tells the debugger to wait for a process with the given pid or name to launch before attaching.
+:::
- Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded.
+:::{option} -w
+Alias for --wait-for
+:::
-.. option:: -O <value>
+## COMMANDS
- Alias for --one-line-before-file
+:::{option} --batch
+Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.
+:::
-.. option:: -o <value>
+:::{option} -b
+Alias for --batch
+:::
- Alias for --one-line
+:::{option} -K <value>
+Alias for --source-on-crash
+:::
-.. option:: -Q
+:::{option} -k <value>
+Alias for --one-line-on-crash
+:::
- Alias for --source-quietly
+:::{option} --local-lldbinit
+Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.
+:::
-.. option:: --source-before-file <file>
+:::{option} --no-lldbinit
+Do not automatically parse any '.lldbinit' files.
+:::
- Tells the debugger to read in and execute the lldb commands in the given file, before any file has been loaded.
+:::{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.
+:::
-.. option:: --source-on-crash <file>
+:::{option} --one-line-on-crash <command>
+When in batch mode, tells the debugger to run this one-line lldb command if the target crashes.
+:::
- When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
+:::{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.
+:::
-.. option:: --source-quietly
+:::{option} -O <value>
+Alias for --one-line-before-file
+:::
- Tells the debugger not to echo commands while sourcing files or one-line commands provided on the command line.
+:::{option} -o <value>
+Alias for --one-line
+:::
-.. option:: --source <file>
+:::{option} -Q
+Alias for --source-quietly
+:::
- Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded.
+:::{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.
+:::
-.. option:: -S <value>
+:::{option} --source-on-crash <file>
+When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
+:::
- Alias for --source-before-file
+:::{option} --source-quietly
+Tells the debugger not to echo commands while sourcing files or one-line commands provided on the command line.
+:::
-.. option:: -s <value>
+:::{option} --source <file>
+Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded.
+:::
- Alias for --source
+:::{option} -S <value>
+Alias for --source-before-file
+:::
-.. option:: -x
+:::{option} -s <value>
+Alias for --source
+:::
- Alias for --no-lldbinit
+:::{option} -x
+Alias for --no-lldbinit
+:::
-OPTIONS
--------
+## OPTIONS
-.. option:: --arch <architecture>
+:::{option} --arch <architecture>
+Tells the debugger to use the specified architecture when starting and running the program.
+:::
- Tells the debugger to use the specified architecture when starting and running the program.
+:::{option} -a <value>
+Alias for --arch
+:::
-.. option:: -a <value>
+:::{option} --capture-path <filename>
+Tells the debugger to use the given filename for the reproducer.
+:::
- Alias for --arch
+:::{option} --capture
+Tells the debugger to capture a reproducer.
+:::
-.. option:: --capture-path <filename>
+:::{option} --core <filename>
+Tells the debugger to use the full path to \<filename> as the core file.
+:::
- Tells the debugger to use the given filename for the reproducer.
+:::{option} -c <value>
+Alias for --core
+:::
-.. option:: --capture
+:::{option} --debug
+Tells the debugger to print out extra information for debugging itself.
+:::
- Tells the debugger to capture a reproducer.
+:::{option} -d
+Alias for --debug
+:::
-.. option:: --core <filename>
+:::{option} --editor
+Tells the debugger to open source files using the host's "external editor" mechanism.
+:::
- Tells the debugger to use the full path to <filename> as the core file.
+:::{option} -e
+Alias for --editor
+:::
-.. option:: -c <value>
+:::{option} --file <filename>
+Tells the debugger to use the file \<filename> as the program to be debugged.
+:::
- Alias for --core
+:::{option} -f <value>
+Alias for --file
+:::
-.. option:: --debug
+:::{option} --help
+Prints out the usage information for the LLDB debugger.
+:::
- Tells the debugger to print out extra information for debugging itself.
+:::{option} -h
+Alias for --help
+:::
-.. option:: -d
+:::{option} --no-use-colors
+Do not use colors.
+:::
- Alias for --debug
+:::{option} --replay <filename>
+Tells the debugger to replay a reproducer from \<filename>.
+:::
-.. option:: --editor
+:::{option} --version
+Prints out the current version number of the LLDB debugger.
+:::
- Tells the debugger to open source files using the host's "external editor" mechanism.
+:::{option} -v
+Alias for --version
+:::
-.. option:: -e
+:::{option} -X
+Alias for --no-use-color
+:::
- Alias for --editor
+## REPL
-.. option:: --file <filename>
+:::{option} -r=<flags>
+Alias for --repl=\<flags>
+:::
- Tells the debugger to use the file <filename> as the program to be debugged.
+:::{option} --repl-language <language>
+Chooses the language for the REPL.
+:::
-.. option:: -f <value>
+:::{option} --repl=<flags>
+Runs lldb in REPL mode with a stub process with the given flags.
+:::
- Alias for --file
+:::{option} -R <value>
+Alias for --repl-language
+:::
-.. option:: --help
+## SCRIPTING
- Prints out the usage information for the LLDB debugger.
+:::{option} -l <value>
+Alias for --script-language
+:::
-.. option:: -h
+:::{option} --print-script-interpreter-info
+Prints out a json dictionary with information about the scripting language interpreter.
+:::
- Alias for --help
+:::{option} --python-path
+Prints out the path to the lldb.py file for this version of lldb.
+:::
-.. option:: --no-use-colors
+:::{option} -P
+Alias for --python-path
+:::
- Do not use colors.
+:::{option} --script-language <language>
+Tells the debugger to use the specified scripting language for user-defined scripts.
+:::
-.. option:: --replay <filename>
-
- Tells the debugger to replay a reproducer from <filename>.
-
-.. option:: --version
-
- Prints out the current version number of the LLDB debugger.
-
-.. option:: -v
-
- Alias for --version
-
-.. option:: -X
-
- Alias for --no-use-color
-
-REPL
-----
-
-.. option:: -r=<flags>
-
- Alias for --repl=<flags>
-
-.. option:: --repl-language <language>
-
- Chooses the language for the REPL.
-
-.. option:: --repl=<flags>
-
- Runs lldb in REPL mode with a stub process with the given flags.
-
-.. option:: -R <value>
-
- Alias for --repl-language
-
-SCRIPTING
----------
-
-.. option:: -l <value>
-
- Alias for --script-language
-
-.. option:: --print-script-interpreter-info
-
- Prints out a json dictionary with information about the scripting language interpreter.
-
-.. option:: --python-path
-
- Prints out the path to the lldb.py file for this version of lldb.
-
-.. option:: -P
-
- Alias for --python-path
-
-.. option:: --script-language <language>
-
- Tells the debugger to use the specified scripting language for user-defined scripts.
-
-EXAMPLES
---------
+## EXAMPLES
The debugger can be started in several modes.
@@ -260,42 +263,41 @@ executable. To disambiguate between arguments passed to lldb and arguments
passed to the debugged executable, arguments starting with a - must be passed
after --.
- lldb --arch x86_64 /path/to/program program argument -- --arch armv7
+> lldb --arch x86_64 /path/to/program program argument -- --arch armv7
For convenience, passing the executable after -- is also supported.
- lldb --arch x86_64 -- /path/to/program program argument --arch armv7
+> lldb --arch x86_64 -- /path/to/program program argument --arch armv7
-Passing one of the attach options causes :program:`lldb` to immediately attach
+Passing one of the attach options causes {program}`lldb` to immediately attach
to the given process.
- lldb -p <pid>
- lldb -n <process-name>
+> lldb -p \<pid>
+> lldb -n \<process-name>
-Passing --repl starts :program:`lldb` in REPL mode.
+Passing --repl starts {program}`lldb` in REPL mode.
- lldb -r
+> lldb -r
-Passing --core causes :program:`lldb` to debug the core file.
+Passing --core causes {program}`lldb` to debug the core file.
- lldb -c /path/to/core
+> lldb -c /path/to/core
-Command options can be combined with these modes and cause :program:`lldb` to
+Command options can be combined with these modes and cause {program}`lldb` to
run the specified commands before or after events, like loading the file or
crashing, in the order provided on the command line.
- lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt'
- lldb -S /source/before/file -s /source/after/file
- lldb -K /source/before/crash -k /source/after/crash
+> lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt'
+> lldb -S /source/before/file -s /source/after/file
+> lldb -K /source/before/crash -k /source/after/crash
Note: In REPL mode no file is loaded, so commands specified to run after
loading the file (via -o or -s) will be ignored.
-USING LLDB
-----------
+## USING LLDB
-In :program:`lldb` there is a help command which can be used to find
-descriptions and examples of all :program:`lldb` commands. To get help on
+In {program}`lldb` there is a help command which can be used to find
+descriptions and examples of all {program}`lldb` commands. To get help on
"breakpoint set" you would type "help breakpoint set".
There is also an apropos command which will search the help text of all
@@ -303,43 +305,42 @@ commands for a given term ‐‐ this is useful for locating a command by topic.
For instance, "apropos breakpoint" will list any command that has the word
"breakpoint" in its help text.
-CONFIGURATION FILES
--------------------
+## CONFIGURATION FILES
-:program:`lldb` reads things like settings, aliases and commands from the
+{program}`lldb` reads things like settings, aliases and commands from the
.lldbinit file.
-First, :program:`lldb` will try to read the application specific init file
+First, {program}`lldb` will try to read the application specific init file
whose name is ~/.lldbinit followed by a "-" and the name of the current
-program. This would be ~/.lldbinit-lldb for the command line :program:`lldb`
+program. This would be ~/.lldbinit-lldb for the command line {program}`lldb`
and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
-file, :program:`lldb` will look for an init file in the home directory.
-If launched with a `REPL`_ option, it will first look for a REPL configuration
+file, {program}`lldb` will look for an init file in the home directory.
+If launched with a [REPL] option, it will first look for a REPL configuration
file, specific to the REPL language. The init file should be named as follow:
-``.lldbinit-<language>-repl`` (i.e. ``.lldbinit-swift-repl``). If this file doesn't
-exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither
-a REPL init file nor an application specific init file, ``lldb`` will fallback to
+`.lldbinit-<language>-repl` (i.e. `.lldbinit-swift-repl`). If this file doesn't
+exist, or {program}`lldb` wasn't launch with [REPL], meaning there is neither
+a REPL init file nor an application specific init file, `lldb` will fallback to
the global ~/.lldbinit.
Secondly, it will look for an .lldbinit file in the current working directory.
-For security reasons, :program:`lldb` will print a warning and not source this
+For security reasons, {program}`lldb` will print a warning and not source this
file by default. This behavior can be changed by changing the
target.load-cwd-lldbinit setting.
To always load the .lldbinit file in the current working directory, add the
following command to ~/.lldbinit:
- settings set target.load-cwd-lldbinit true
+> settings set target.load-cwd-lldbinit true
To never load the .lldbinit file in the current working directory and silence
the warning, add the following command to ~/.lldbinit:
- settings set target.load-cwd-lldbinit false
+> settings set target.load-cwd-lldbinit false
-SEE ALSO
---------
+## SEE ALSO
-The :doc:`LLDB project page </index>` has many different resources
-for :program:`lldb` users ‐‐ the :doc:`gdb/lldb command equivalence page
+The {doc}`LLDB project page </index>` has many different resources
+for {program}`lldb` users ‐‐ the {doc}`gdb/lldb command equivalence page
</use/map>` can be especially helpful for users
coming from gdb.
+
diff --git a/llvm/docs/Proposals/VariableNames.md b/llvm/docs/Proposals/VariableNames.md
index 2212cb7f7bb1ad..dfe8516fe6cd82 100644
--- a/llvm/docs/Proposals/VariableNames.md
+++ b/llvm/docs/Proposals/VariableNames.md
@@ -1,7 +1,4 @@
-===================
-Variable Names Plan
-===================
-
+# Variable Names Plan
This plan is *provisional*. It is not agreed upon. It is written with the
intention of capturing the desires and concerns of the LLVM community, and
@@ -9,105 +6,104 @@ forming them into a plan that can be agreed upon.
The original author is somewhat naïve in the ways of LLVM so there will
inevitably be some details that are flawed. You can help - you can edit this
page by submitting a GitHub pull request or reply to the
-`Request For Comments thread
-<http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html>`_.
+[Request For Comments thread](http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html).
-Too Long; Didn't Read
-=====================
+## Too Long; Didn't Read
Improve the readability of LLVM code.
-Introduction
-============
+## Introduction
-The current `variable naming rule
-<../CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_
+The current [variable naming rule](../CodingStandards.html#name-types-functions-variables-and-enumerators-properly)
states:
- Variable names should be nouns (as they represent state). The name should be
- camel case, and start with an upper case letter (e.g. Leader or Boats).
+> Variable names should be nouns (as they represent state). The name should be
+> camel case, and start with an upper case letter (e.g. Leader or Boats).
This rule is the same as that for type names. This is a problem because the
-type name cannot be reused for a variable name [*]_. LLVM developers tend to
-work around this by either prepending ``The`` to the type name::
+type name cannot be reused for a variable name [^footnote-1]. LLVM developers tend to
+work around this by either prepending `The` to the type name:
- Triple TheTriple;
+```
+Triple TheTriple;
+```
... or more commonly use an acronym, despite the coding standard stating "Avoid
-abbreviations unless they are well known"::
+abbreviations unless they are well known":
- Triple T;
+```
+Triple T;
+```
-The proliferation of acronyms leads to hard-to-read code such as `this
-<https://github.com/llvm/llvm-project/blob/0a8bc14ad7f3209fe702d18e250194cd90188596/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7445>`_::
+The proliferation of acronyms leads to hard-to-read code such as [this](https://github.com/llvm/llvm-project/blob/0a8bc14ad7f3209fe702d18e250194cd90188596/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7445):
- InnerLoopVectorizer LB(L, PSE, LI, DT, TLI, TTI, AC, ORE, VF.Width, IC,
- &LVL, &CM);
+```
+InnerLoopVectorizer LB(L, PSE, LI, DT, TLI, TTI, AC, ORE, VF.Width, IC,
+ &LVL, &CM);
+```
-Many other coding guidelines [LLDB]_ [Google]_ [WebKit]_ [Qt]_ [Rust]_ [Swift]_
-[Python]_ require that variable names begin with a lower case letter in contrast
+Many other coding guidelines [^cite_lldb] [^cite_google] [^cite_webkit] [^cite_qt] [^cite_rust] [^cite_swift]
+[^cite_python] require that variable names begin with a lower case letter in contrast
to class names which begin with a capital letter. This convention means that the
-most readable variable name also requires the least thought::
+most readable variable name also requires the least thought:
- Triple triple;
+```
+Triple triple;
+```
-There is some agreement that the current rule is broken [LattnerAgree]_
-[ArsenaultAgree]_ [RobinsonAgree]_ and that acronyms are an obstacle to reading
-new code [MalyutinDistinguish]_ [CarruthAcronym]_ [PicusAcronym]_. There are
-some opposing views [ParzyszekAcronym2]_ [RicciAcronyms]_.
+There is some agreement that the current rule is broken [^cite_lattneragree]
+[^cite_arsenaultagree] [^cite_robinsonagree] and that acronyms are an obstacle to reading
+new code [^cite_malyutindistinguish] [^cite_carruthacronym] [^cite_picusacronym]. There are
+some opposing views [^cite_parzyszekacronym2] [^cite_ricciacronyms].
This work-in-progress proposal is to change the coding standard for variable
names to require that they start with a lower case letter.
-.. [*] In `some cases
- <https://github.com/llvm/llvm-project/blob/8b72080d4d7b13072f371712eed333f987b7a18e/llvm/lib/CodeGen/SelectionDAG/SelectionDAG.cpp#L2727>`_
- the type name *is* reused as a variable name, but this shadows the type name
- and confuses many debuggers [DenisovCamelBack]_.
+[^footnote-1]: In [some cases](https://github.com/llvm/llvm-project/blob/8b72080d4d7b13072f371712eed333f987b7a18e/llvm/lib/CodeGen/SelectionDAG/SelectionDAG.cpp#L2727)
+ the type name *is* reused as a variable name, but this shadows the type name
+ and confuses many debuggers [^cite_denisovcamelback].
-Variable Names Coding Standard Options
-======================================
+## Variable Names Coding Standard Options
There are two main options for variable names that begin with a lower case
-letter: ``camelBack`` and ``lower_case``. (These are also known by other names
+letter: `camelBack` and `lower_case`. (These are also known by other names
but here we use the terminology from clang-tidy).
-``camelBack`` is consistent with [WebKit]_, [Qt]_ and [Swift]_ while
-``lower_case`` is consistent with [LLDB]_, [Google]_, [Rust]_ and [Python]_.
+`camelBack` is consistent with [^cite_webkit], [^cite_qt] and [^cite_swift] while
+`lower_case` is consistent with [^cite_lldb], [^cite_google], [^cite_rust] and [^cite_python].
-``camelBack`` is already used for function names, which may be considered an
-advantage [LattnerFunction]_ or a disadvantage [CarruthFunction]_.
+`camelBack` is already used for function names, which may be considered an
+advantage [^cite_lattnerfunction] or a disadvantage [^cite_carruthfunction].
-Approval for ``camelBack`` was expressed by [DenisovCamelBack]_
-[LattnerFunction]_ [IvanovicDistinguish]_.
-Opposition to ``camelBack`` was expressed by [CarruthCamelBack]_
-[TurnerCamelBack]_.
-Approval for ``lower_case`` was expressed by [CarruthLower]_
-[CarruthCamelBack]_ [TurnerLLDB]_.
-Opposition to ``lower_case`` was expressed by [LattnerLower]_.
+Approval for `camelBack` was expressed by [^cite_denisovcamelback]
+[^cite_lattnerfunction] [^cite_ivanovicdistinguish].
+Opposition to `camelBack` was expressed by [^cite_carruthcamelback]
+[^cite_turnercamelback].
+Approval for `lower_case` was expressed by [^cite_carruthlower]
+[^cite_carruthcamelback] [^cite_turnerlldb].
+Opposition to `lower_case` was expressed by [^cite_lattnerlower].
-Differentiating variable kinds
-------------------------------
+### Differentiating variable kinds
An additional requested change is to distinguish between different kinds of
-variables [RobinsonDistinguish]_ [RobinsonDistinguish2]_ [JonesDistinguish]_
-[IvanovicDistinguish]_ [CarruthDistinguish]_ [MalyutinDistinguish]_.
+variables [^cite_robinsondistinguish] [^cite_robinsondistinguish2] [^cite_jonesdistinguish]
+[^cite_ivanovicdistinguish] [^cite_carruthdistinguish] [^cite_malyutindistinguish].
-Others oppose this idea [HähnleDistinguish]_ [GreeneDistinguish]_
-[HendersonPrefix]_.
+Others oppose this idea [^cite_hahnledistinguish] [^cite_greenedistinguish]
+[^cite_hendersonprefix].
-A possibility is for member variables to be prefixed with ``m_`` and for global
-variables to be prefixed with ``g_`` to distinguish them from local variables.
-This is consistent with [LLDB]_. The ``m_`` prefix is consistent with [WebKit]_.
+A possibility is for member variables to be prefixed with `m_` and for global
+variables to be prefixed with `g_` to distinguish them from local variables.
+This is consistent with [^cite_lldb]. The `m_` prefix is consistent with [^cite_webkit].
-A variation is for member variables to be prefixed with ``m``
-[IvanovicDistinguish]_ [BeylsDistinguish]_. This is consistent with [Mozilla]_.
+A variation is for member variables to be prefixed with `m`
+[^cite_ivanovicdistinguish] [^cite_beylsdistinguish]. This is consistent with [^cite_mozilla].
-Another option is for member variables to be suffixed with ``_`` which is
-consistent with [Google]_ and similar to [Python]_. Opposed by
-[ParzyszekDistinguish]_.
+Another option is for member variables to be suffixed with `_` which is
+consistent with [^cite_google] and similar to [^cite_python]. Opposed by
+[^cite_parzyszekdistinguish].
-Reducing the number of acronyms
-===============================
+## Reducing the number of acronyms
While switching coding standard will make it easier to use non-acronym names for
new code, it doesn't improve the existing large body of code that uses acronyms
@@ -117,64 +113,59 @@ code. Therefore it is likely that much newly written code will also use
acronyms despite what the coding standard says, much as it is today.
As well as changing the case of variable names, they could also be expanded to
-their non-acronym form e.g. ``Triple T`` → ``Triple triple``.
+their non-acronym form e.g. `Triple T` → `Triple triple`.
-There is support for expanding many acronyms [CarruthAcronym]_ [PicusAcronym]_
+There is support for expanding many acronyms [^cite_carruthacronym] [^cite_picusacronym]
but there is a preference that expanding acronyms be deferred
-[ParzyszekAcronym]_ [CarruthAcronym]_.
+[^cite_parzyszekacronym] [^cite_carruthacronym].
The consensus within the community seems to be that at least some acronyms are
-valuable [ParzyszekAcronym]_ [LattnerAcronym]_. The most commonly cited acronym
-is ``TLI`` however that is used to refer to both ``TargetLowering`` and
-``TargetLibraryInfo`` [GreeneDistinguish]_.
+valuable [^cite_parzyszekacronym] [^cite_lattneracronym]. The most commonly cited acronym
+is `TLI` however that is used to refer to both `TargetLowering` and
+`TargetLibraryInfo` [^cite_greenedistinguish].
The following is a list of acronyms considered sufficiently useful that the
benefit of using them outweighs the cost of learning them. Acronyms that are
either not on the list or are used to refer to a different type should be
expanded.
-============================ =============
-Class name Variable name
-============================ =============
-DeterministicFiniteAutomaton dfa
-DominatorTree dt
-LoopInfo li
-MachineFunction mf
-MachineInstr mi
-MachineRegisterInfo mri
-ScalarEvolution se
-TargetInstrInfo tii
-TargetLibraryInfo tli
-TargetRegisterInfo tri
-============================ =============
+| Class name | Variable name |
+| ---------------------------- | ------------- |
+| DeterministicFiniteAutomaton | dfa |
+| DominatorTree | dt |
+| LoopInfo | li |
+| MachineFunction | mf |
+| MachineInstr | mi |
+| MachineRegisterInfo | mri |
+| ScalarEvolution | se |
+| TargetInstrInfo | tii |
+| TargetLibraryInfo | tli |
+| TargetRegisterInfo | tri |
In some cases renaming acronyms to the full type name will result in overly
verbose code. Unlike most classes, a variable's scope is limited and therefore
some of its purpose can implied from that scope, meaning that fewer words are
necessary to give it a clear name. For example, in an optimization pass the reader
can assume that a variable's purpose relates to optimization and therefore an
-``OptimizationRemarkEmitter`` variable could be given the name ``remarkEmitter``
-or even ``remarker``.
+`OptimizationRemarkEmitter` variable could be given the name `remarkEmitter`
+or even `remarker`.
The following is a list of longer class names and the associated shorter
variable name.
-========================= =============
-Class name Variable name
-========================= =============
-BasicBlock block
-ConstantExpr expr
-ExecutionEngine engine
-MachineOperand operand
-OptimizationRemarkEmitter remarker
-PreservedAnalyses analyses
-PreservedAnalysesChecker checker
-TargetLowering lowering
-TargetMachine machine
-========================= =============
-
-Transition Options
-==================
+| Class name | Variable name |
+| ------------------------- | ------------- |
+| BasicBlock | block |
+| ConstantExpr | expr |
+| ExecutionEngine | engine |
+| MachineOperand | operand |
+| OptimizationRemarkEmitter | remarker |
+| PreservedAnalyses | analyses |
+| PreservedAnalysesChecker | checker |
+| TargetLowering | lowering |
+| TargetMachine | machine |
+
+## Transition Options
There are three main options for transitioning:
@@ -182,73 +173,64 @@ There are three main options for transitioning:
2. Laissez faire
3. Big bang
-Keep the current coding standard
---------------------------------
+### Keep the current coding standard
Proponents of keeping the current coding standard (i.e. not transitioning at
all) question whether the cost of transition outweighs the benefit
-[EmersonConcern]_ [ReamesConcern]_ [BradburyConcern]_.
-The costs are that ``git blame`` will become less usable; and that merging the
-changes will be costly for downstream maintainers. See `Big bang`_ for potential
+[^cite_emersonconcern] [^cite_reamesconcern] [^cite_bradburyconcern].
+The costs are that `git blame` will become less usable; and that merging the
+changes will be costly for downstream maintainers. See [Big bang] for potential
mitigations.
-Laissez faire
--------------
+### Laissez faire
-The coding standard could allow both ``CamelCase`` and ``camelBack`` styles for
-variable names [LattnerTransition]_.
+The coding standard could allow both `CamelCase` and `camelBack` styles for
+variable names [^cite_lattnertransition].
-A code review to implement this is at https://reviews.llvm.org/D57896.
+A code review to implement this is at <https://reviews.llvm.org/D57896>.
-Advantages
-**********
+#### Advantages
- * Very easy to implement initially.
+> - Very easy to implement initially.
-Disadvantages
-*************
+#### Disadvantages
- * Leads to inconsistency [BradburyConcern]_ [AminiInconsistent]_.
- * Inconsistency means it will be hard to know at a guess what name a variable
- will have [DasInconsistent]_ [CarruthInconsistent]_.
- * Some large-scale renaming may happen anyway, leading to its disadvantages
- without any mitigations.
+> - Leads to inconsistency [^cite_bradburyconcern] [^cite_aminiinconsistent].
+> - Inconsistency means it will be hard to know at a guess what name a variable
+> will have [^cite_dasinconsistent] [^cite_carruthinconsistent].
+> - Some large-scale renaming may happen anyway, leading to its disadvantages
+> without any mitigations.
-Big bang
---------
+### Big bang
With this approach, variables will be renamed by an automated script in a series
of large commits.
The principle advantage of this approach is that it minimises the cost of
-inconsistency [BradburyTransition]_ [RobinsonTransition]_.
+inconsistency [^cite_bradburytransition] [^cite_robinsontransition].
It goes against a policy of avoiding large-scale reformatting of existing code
-[GreeneDistinguish]_.
+[^cite_greenedistinguish].
It has been suggested that LLD would be a good starter project for the renaming
-[Ueyama]_.
+[^cite_ueyama].
-Keeping git blame usable
-************************
+#### Keeping git blame usable
-``git blame`` (or ``git annotate``) permits quickly identifying the commit that
+`git blame` (or `git annotate`) permits quickly identifying the commit that
changed a given line in a file. After renaming variables, many lines will show
-as being changed by that one commit, requiring a further invocation of ``git
-blame`` to identify prior, more interesting commits [GreeneGitBlame]_
-[RicciAcronyms]_.
+as being changed by that one commit, requiring a further invocation of `git
+blame` to identify prior, more interesting commits [^cite_greenegitblame]
+[^cite_ricciacronyms].
-**Mitigation**: `git-hyper-blame
-<https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-hyper-blame.html>`_
+**Mitigation**: [git-hyper-blame](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-hyper-blame.html)
can ignore or "look through" a given set of commits.
-A ``.git-blame-ignore-revs`` file identifying the variable renaming commits
+A `.git-blame-ignore-revs` file identifying the variable renaming commits
could be added to the LLVM git repository root directory.
-It is being `investigated
-<https://public-inbox.org/git/20190324235020.49706-1-michael@platin.gs/>`_
-whether similar functionality could be added to ``git blame`` itself.
+It is being [investigated](https://public-inbox.org/git/20190324235020.49706-1-michael@platin.gs/)
+whether similar functionality could be added to `git blame` itself.
-Minimising cost of downstream merges
-************************************
+#### Minimising cost of downstream merges
There are many forks of LLVM with downstream changes. Merging a large-scale
renaming change could be difficult for the fork maintainers.
@@ -257,141 +239,187 @@ renaming change could be difficult for the fork maintainers.
merge from the commit immediately before the renaming, then apply the renaming
script to their own branch. They can then merge again from the renaming commit,
resolving all conflicts by choosing their own version. This could be tested on
-the [SVE]_ fork.
-
-Provisional Plan
-================
-
-This is a provisional plan for the `Big bang`_ approach. It has not been agreed.
-
-#. Investigate improving ``git blame``. The extent to which it can be made to
- "look through" commits may impact how big a change can be made.
-
-#. Write a script to expand acronyms.
-
-#. Experiment and perform dry runs of the various refactoring options.
- Results can be published in forks of the LLVM Git repository.
-
-#. Consider the evidence and agree on the new policy.
-
-#. Agree & announce a date for the renaming of the starter project (LLD).
-
-#. Update the `policy page <../CodingStandards.html>`_. This will explain the
- old and new rules and which projects each applies to.
-
-#. Refactor the starter project in two commits:
-
- 1. Add or change the project's .clang-tidy to reflect the agreed rules.
- (This is in a separate commit to enable the merging process described in
- `Minimising cost of downstream merges`_).
- Also update the project list on the policy page.
- 2. Apply ``clang-tidy`` to the project's files, with only the
- ``readability-identifier-naming`` rules enabled. ``clang-tidy`` will also
- reformat the affected lines according to the rules in ``.clang-format``.
- It is anticipated that this will be a good dog-fooding opportunity for
- clang-tidy, and bugs should be fixed in the process, likely including:
-
- * `readability-identifier-naming incorrectly fixes lambda capture
- <https://bugs.llvm.org/show_bug.cgi?id=41119>`_.
- * `readability-identifier-naming incorrectly fixes variables which
- become keywords <https://bugs.llvm.org/show_bug.cgi?id=41120>`_.
- * `readability-identifier-naming misses fixing member variables in
- destructor <https://bugs.llvm.org/show_bug.cgi?id=41122>`_.
-
-#. Gather feedback and refine the process as appropriate.
-
-#. Apply the process to the following projects, with a suitable delay between
- each (at least 4 weeks after the first change, at least 2 weeks subsequently)
- to allow gathering further feedback.
- This list should exclude projects that must adhere to an externally defined
- standard e.g. libcxx.
- The list is roughly in chronological order of renaming.
- Some items may not make sense to rename individually - it is expected that
- this list will change following experimentation:
-
- * TableGen
- * llvm/tools
- * clang-tools-extra
- * clang
- * ARM backend
- * AArch64 backend
- * AMDGPU backend
- * ARC backend
- * AVR backend
- * BPF backend
- * Hexagon backend
- * Lanai backend
- * MIPS backend
- * NVPTX backend
- * PowerPC backend
- * RISC-V backend
- * Sparc backend
- * SystemZ backend
- * WebAssembly backend
- * X86 backend
- * XCore backend
- * libLTO
- * Debug Information
- * Remainder of llvm
- * compiler-rt
- * libunwind
- * openmp
- * parallel-libs
- * polly
- * lldb
-
-#. Remove the old variable name rule from the policy page.
-
-#. Repeat many of the steps in the sequence, using a script to expand acronyms.
-
-References
-==========
-
-.. [LLDB] LLDB Coding Conventions https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html
-.. [Google] Google C++ Style Guide https://google.github.io/styleguide/cppguide.html#Variable_Names
-.. [WebKit] WebKit Code Style Guidelines https://webkit.org/code-style-guidelines/#names
-.. [Qt] Qt Coding Style https://wiki.qt.io/Qt_Coding_Style#Declaring_variables
-.. [Rust] Rust naming conventions https://doc.rust-lang.org/1.0.0/style/style/naming/README.html
-.. [Swift] Swift API Design Guidelines https://swift.org/documentation/api-design-guidelines/#general-conventions
-.. [Python] Style Guide for Python Code https://www.python.org/dev/peps/pep-0008/#function-and-variable-names
-.. [Mozilla] Mozilla Coding style: Prefixes https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html#prefixes
-.. [SVE] LLVM with support for SVE https://github.com/ARM-software/LLVM-SVE
-.. [AminiInconsistent] Mehdi Amini, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html
-.. [ArsenaultAgree] Matt Arsenault, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html
-.. [BeylsDistinguish] Kristof Beyls, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html
-.. [BradburyConcern] Alex Bradbury, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html
-.. [BradburyTransition] Alex Bradbury, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html
-.. [CarruthAcronym] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html
-.. [CarruthCamelBack] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html
-.. [CarruthDistinguish] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html
-.. [CarruthFunction] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html
-.. [CarruthInconsistent] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html
-.. [CarruthLower] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html
-.. [DasInconsistent] Sanjoy Das, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html
-.. [DenisovCamelBack] Alex Denisov, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html
-.. [EmersonConcern] Amara Emerson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html
-.. [GreeneDistinguish] David Greene, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html
-.. [GreeneGitBlame] David Greene, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html
-.. [HendersonPrefix] James Henderson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html
-.. [HähnleDistinguish] Nicolai Hähnle, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html
-.. [IvanovicDistinguish] Nemanja Ivanovic, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html
-.. [JonesDistinguish] JD Jones, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html
-.. [LattnerAcronym] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html
-.. [LattnerAgree] Chris Latter, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html
-.. [LattnerFunction] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html
-.. [LattnerLower] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html
-.. [LattnerTransition] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html
-.. [MalyutinDistinguish] Danila Malyutin, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html
-.. [ParzyszekAcronym] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html
-.. [ParzyszekAcronym2] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html
-.. [ParzyszekDistinguish] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html
-.. [PicusAcronym] Diana Picus, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html
-.. [ReamesConcern] Philip Reames, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html
-.. [RicciAcronyms] Bruno Ricci, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html
-.. [RobinsonAgree] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html
-.. [RobinsonDistinguish] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html
-.. [RobinsonDistinguish2] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html
-.. [RobinsonTransition] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html
-.. [TurnerCamelBack] Zachary Turner, https://reviews.llvm.org/D57896#1402264
-.. [TurnerLLDB] Zachary Turner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html
-.. [Ueyama] Rui Ueyama, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html
+the [^cite_sve] fork.
+
+## Provisional Plan
+
+This is a provisional plan for the [Big bang] approach. It has not been agreed.
+
+01. Investigate improving `git blame`. The extent to which it can be made to
+ "look through" commits may impact how big a change can be made.
+
+02. Write a script to expand acronyms.
+
+03. Experiment and perform dry runs of the various refactoring options.
+ Results can be published in forks of the LLVM Git repository.
+
+04. Consider the evidence and agree on the new policy.
+
+05. Agree & announce a date for the renaming of the starter project (LLD).
+
+06. Update the [policy page](../CodingStandards.html). This will explain the
+ old and new rules and which projects each applies to.
+
+07. Refactor the starter project in two commits:
+
+ 1. Add or change the project's .clang-tidy to reflect the agreed rules.
+ (This is in a separate commit to enable the merging process described in
+ [Minimising cost of downstream merges]).
+ Also update the project list on the policy page.
+
+ 2. Apply `clang-tidy` to the project's files, with only the
+ `readability-identifier-naming` rules enabled. `clang-tidy` will also
+ reformat the affected lines according to the rules in `.clang-format`.
+ It is anticipated that this will be a good dog-fooding opportunity for
+ clang-tidy, and bugs should be fixed in the process, likely including:
+
+ > - [readability-identifier-naming incorrectly fixes lambda capture](https://bugs.llvm.org/show_bug.cgi?id=41119).
+ > - [readability-identifier-naming incorrectly fixes variables which
+ > become keywords](https://bugs.llvm.org/show_bug.cgi?id=41120).
+ > - [readability-identifier-naming misses fixing member variables in
+ > destructor](https://bugs.llvm.org/show_bug.cgi?id=41122).
+
+08. Gather feedback and refine the process as appropriate.
+
+09. Apply the process to the following projects, with a suitable delay between
+ each (at least 4 weeks after the first change, at least 2 weeks subsequently)
+ to allow gathering further feedback.
+ This list should exclude projects that must adhere to an externally defined
+ standard e.g. libcxx.
+ The list is roughly in chronological order of renaming.
+ Some items may not make sense to rename individually - it is expected that
+ this list will change following experimentation:
+
+ - TableGen
+ - llvm/tools
+ - clang-tools-extra
+ - clang
+ - ARM backend
+ - AArch64 backend
+ - AMDGPU backend
+ - ARC backend
+ - AVR backend
+ - BPF backend
+ - Hexagon backend
+ - Lanai backend
+ - MIPS backend
+ - NVPTX backend
+ - PowerPC backend
+ - RISC-V backend
+ - Sparc backend
+ - SystemZ backend
+ - WebAssembly backend
+ - X86 backend
+ - XCore backend
+ - libLTO
+ - Debug Information
+ - Remainder of llvm
+ - compiler-rt
+ - libunwind
+ - openmp
+ - parallel-libs
+ - polly
+ - lldb
+
+10. Remove the old variable name rule from the policy page.
+
+11. Repeat many of the steps in the sequence, using a script to expand acronyms.
+
+## References
+
+[^cite_lldb]: LLDB Coding Conventions <https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html>
+
+[^cite_google]: Google C++ Style Guide <https://google.github.io/styleguide/cppguide.html#Variable_Names>
+
+[^cite_webkit]: WebKit Code Style Guidelines <https://webkit.org/code-style-guidelines/#names>
+
+[^cite_qt]: Qt Coding Style <https://wiki.qt.io/Qt_Coding_Style#Declaring_variables>
+
+[^cite_rust]: Rust naming conventions <https://doc.rust-lang.org/1.0.0/style/style/naming/README.html>
+
+[^cite_swift]: Swift API Design Guidelines <https://swift.org/documentation/api-design-guidelines/#general-conventions>
+
+[^cite_python]: Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/#function-and-variable-names>
+
+[^cite_mozilla]: Mozilla Coding style: Prefixes <https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html#prefixes>
+
+[^cite_sve]: LLVM with support for SVE <https://github.com/ARM-software/LLVM-SVE>
+
+[^cite_aminiinconsistent]: Mehdi Amini, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html>
+
+[^cite_arsenaultagree]: Matt Arsenault, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html>
+
+[^cite_beylsdistinguish]: Kristof Beyls, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html>
+
+[^cite_bradburyconcern]: Alex Bradbury, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html>
+
+[^cite_bradburytransition]: Alex Bradbury, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html>
+
+[^cite_carruthacronym]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html>
+
+[^cite_carruthcamelback]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html>
+
+[^cite_carruthdistinguish]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html>
+
+[^cite_carruthfunction]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html>
+
+[^cite_carruthinconsistent]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html>
+
+[^cite_carruthlower]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html>
+
+[^cite_dasinconsistent]: Sanjoy Das, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html>
+
+[^cite_denisovcamelback]: Alex Denisov, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html>
+
+[^cite_emersonconcern]: Amara Emerson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html>
+
+[^cite_greenedistinguish]: David Greene, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html>
+
+[^cite_greenegitblame]: David Greene, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html>
+
+[^cite_hendersonprefix]: James Henderson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html>
+
+[^cite_hähnledistinguish]: Nicolai Hähnle, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html>
+
+[^cite_ivanovicdistinguish]: Nemanja Ivanovic, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html>
+
+[^cite_jonesdistinguish]: JD Jones, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html>
+
+[^cite_lattneracronym]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html>
+
+[^cite_lattneragree]: Chris Latter, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html>
+
+[^cite_lattnerfunction]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html>
+
+[^cite_lattnerlower]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html>
+
+[^cite_lattnertransition]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html>
+
+[^cite_malyutindistinguish]: Danila Malyutin, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html>
+
+[^cite_parzyszekacronym]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html>
+
+[^cite_parzyszekacronym2]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html>
+
+[^cite_parzyszekdistinguish]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html>
+
+[^cite_picusacronym]: Diana Picus, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html>
+
+[^cite_reamesconcern]: Philip Reames, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html>
+
+[^cite_ricciacronyms]: Bruno Ricci, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html>
+
+[^cite_robinsonagree]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html>
+
+[^cite_robinsondistinguish]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html>
+
+[^cite_robinsondistinguish2]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html>
+
+[^cite_robinsontransition]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html>
+
+[^cite_turnercamelback]: Zachary Turner, <https://reviews.llvm.org/D57896#1402264>
+
+[^cite_turnerlldb]: Zachary Turner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html>
+
+[^cite_ueyama]: Rui Ueyama, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html>
+
diff --git a/llvm/utils/gn/README.md b/llvm/utils/gn/README.md
index 6b2a2f75fe8e9d..d0a3f13234be16 100644
--- a/llvm/utils/gn/README.md
+++ b/llvm/utils/gn/README.md
@@ -1,14 +1,12 @@
-=====================
-Building LLVM with GN
-=====================
+# Building LLVM with GN
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-.. _Introduction:
+(introduction)=
-Introduction
-============
+## Introduction
*Warning* The GN build is experimental and best-effort. It might not work,
and if you use it you're expected to feel comfortable to unbreak it if
@@ -18,7 +16,7 @@ to update GN build files. Reviewers should not ask authors to update GN build
files. Keeping the GN build files up-to-date is on the people who use the GN
build.
-`GN <https://gn.googlesource.com/gn/>`_ is a metabuild system. It always
+[GN](https://gn.googlesource.com/gn/) is a metabuild system. It always
creates ninja files, but it can create some IDE projects (MSVC, Xcode, ...)
which then shell out to ninja for the actual build.
@@ -27,72 +25,65 @@ convenient for day-to-day hacking on LLVM than CMake. Distribution, building
just parts of LLVM, and embedding the LLVM GN build from other builds are
non-goals for the GN build.
-This is a `good overview of GN <https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12>`_.
+This is a [good overview of GN](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12).
-.. _Quick start:
+(quick-start)=
-Quick start
-===========
+## Quick start
-#. ``git clone https://github.com/llvm/llvm-project.git; cd llvm-project`` if
+1. `git clone https://github.com/llvm/llvm-project.git; cd llvm-project` if
you don't have a checkout yet.
-
-#. ``llvm/utils/gn/get.py`` to download a prebuilt gn binary if you're on a
- 64-bit X86 system running Linux, macOS, or Windows. `Build gn yourself
- <https://gn.googlesource.com/gn/#getting-started>`_ if you're on a different
+2. `llvm/utils/gn/get.py` to download a prebuilt gn binary if you're on a
+ 64-bit X86 system running Linux, macOS, or Windows. [Build gn yourself](https://gn.googlesource.com/gn/#getting-started) if you're on a different
platform or don't want to trust prebuilt binaries.
-
-#. ``llvm/utils/gn/gn.py gen out/gn`` to run GN and create build files.
- ``out/gn`` is the build directory, it can have any name, and you can have as
- many as you want, each with different build settings. (The ``gn.py`` script
- adds ``--dotfile=llvm/utils/gn/.gn --root=.`` and just runs regular ``gn``;
+3. `llvm/utils/gn/gn.py gen out/gn` to run GN and create build files.
+ `out/gn` is the build directory, it can have any name, and you can have as
+ many as you want, each with different build settings. (The `gn.py` script
+ adds `--dotfile=llvm/utils/gn/.gn --root=.` and just runs regular `gn`;
you can manually pass these parameters and not use the wrapper if you
prefer.)
-
-#. ``ninja -C out/gn check-lld`` to build all prerequisites for and run the LLD
+4. `ninja -C out/gn check-lld` to build all prerequisites for and run the LLD
tests.
By default, you get a release build with assertions enabled that targets
-the host arch. You can set build options by editing ``out/gn/args.gn``, for
-example putting ``is_debug = true`` in there gives you a debug build. Run
-``llvm/utils/gn/gn.py args --list out/gn`` to see a list of all possible
-options. After touching ``out/gn/args.gn`` just run ninja: it will re-invoke gn
+the host arch. You can set build options by editing `out/gn/args.gn`, for
+example putting `is_debug = true` in there gives you a debug build. Run
+`llvm/utils/gn/gn.py args --list out/gn` to see a list of all possible
+options. After touching `out/gn/args.gn` just run ninja: it will re-invoke gn
before starting the build.
-GN has extensive built-in help; try e.g. ``llvm/utils/gn/gn.py help gen`` to see
-the help for the ``gen`` command. The full GN reference is also `available
-online <https://gn.googlesource.com/gn/+/refs/heads/main/docs/reference.md>`_.
+GN has extensive built-in help; try e.g. `llvm/utils/gn/gn.py help gen` to see
+the help for the `gen` command. The full GN reference is also [available
+online](https://gn.googlesource.com/gn/+/refs/heads/main/docs/reference.md).
GN has an autoformatter:
-``git ls-files '*.gn' '*.gni' | xargs llvm/utils/gn/gn.py format``
+`git ls-files '*.gn' '*.gni' | xargs llvm/utils/gn/gn.py format`
after making GN build changes is your friend.
-To not put ``BUILD.gn`` files into the main tree, they are all below
-``utils/gn/secondary``. For example, the build file for ``llvm/lib/Support``
-is in ``utils/gn/secondary/llvm/lib/Support``.
+To not put `BUILD.gn` files into the main tree, they are all below
+`utils/gn/secondary`. For example, the build file for `llvm/lib/Support`
+is in `utils/gn/secondary/llvm/lib/Support`.
-.. _Syncing GN files from CMake files:
+(syncing-gn-files-from-cmake-files)=
-Syncing GN files from CMake files
-=================================
+## Syncing GN files from CMake files
Sometimes after pulling in the latest changes, the GN build doesn't work.
Most of the time this is due to someone adding a file to CMakeLists.txt file.
-Run ``llvm/utils/gn/build/sync_source_lists_from_cmake.py`` to print a report
-of which files need to be added to or removed from ``BUILD.gn`` files to
-match the corresponding ``CMakeLists.txt``. You have to manually read the output
+Run `llvm/utils/gn/build/sync_source_lists_from_cmake.py` to print a report
+of which files need to be added to or removed from `BUILD.gn` files to
+match the corresponding `CMakeLists.txt`. You have to manually read the output
of the script and implement its suggestions.
-If new ``CMakeLists.txt`` files have been added, you have to manually create
-a new corresponding ``BUILD.gn`` file below ``llvm/utils/gn/secondary/``.
+If new `CMakeLists.txt` files have been added, you have to manually create
+a new corresponding `BUILD.gn` file below `llvm/utils/gn/secondary/`.
-If the dependencies in a ``CMakeLists.txt`` file have been changed, you have to
+If the dependencies in a `CMakeLists.txt` file have been changed, you have to
manually analyze and fix.
-.. _Philosophy:
+(philosophy)=
-Philosophy
-==========
+## Philosophy
GN believes in using GN arguments to configure the build explicitly, instead
of implicitly figuring out what to do based on what's available on the current
@@ -103,7 +94,7 @@ configure is used for three classes of feature checks:
- compiler checks. In GN, these could use exec_script to identify the host
compiler at GN time. For now the build has explicit toggles for compiler
features. (Maybe there could be a script that writes args.gn based on the
- host compiler). It's possible we'll use exec_script() for this going forward,
+ host compiler). It's possible we'll use exec_script() for this going forward,
but we'd have one exec_script call to identify compiler id and version,
and then base GN arg default values of compiler id and version instead of
doing one exec_script per feature check.
@@ -111,26 +102,24 @@ configure is used for three classes of feature checks:
the checks and not the code, but in practice a) new os's / compilers are rare
b) they will require code changes anyhow, so the configure tradeoff seems
not worth it.)
-
- library checks. For e.g. like zlib, GN thinks it's better to say "we require
zlib, else we error at build time" than silently omitting features. People
who really don't want to install zlib can explicitly set the GN arg to turn
off zlib.
-
- header checks (does system header X exist). These are generally not needed
(just keying this off the host OS works fine), but if they should become
necessary in the future, they should be done at build time and the few
targets that need to know if header X exists then depend on that build-time
check while everything else can build parallel with it.
-
- LLVM-specific build toggles (assertions on/off, debug on/off, targets to
build, ...). These map cleanly to GN args (which then get copied into
config.h in a build step).
For the last two points, it would be nice if LLVM didn't have a single
-``config.h`` header, but one header per toggle. That way, when e.g.
-``llvm_enable_zlib`` is toggled, only the 3 files caring about that setting
-would need to be rebuilt, instead of everything including ``config.h``.
+`config.h` header, but one header per toggle. That way, when e.g.
+`llvm_enable_zlib` is toggled, only the 3 files caring about that setting
+would need to be rebuilt, instead of everything including `config.h`.
GN doesn't believe in users setting arbitrary cflags from an environment
variable, it wants the build to be controlled by .gn files.
+
diff --git a/llvm/utils/lit/README.md b/llvm/utils/lit/README.md
index 3a1457057ac79b..cb0e837b7cb75e 100644
--- a/llvm/utils/lit/README.md
+++ b/llvm/utils/lit/README.md
@@ -1,69 +1,60 @@
-===============================
- lit - A Software Testing Tool
-===============================
+# lit - A Software Testing Tool
-About
-=====
+## About
*lit* is a portable tool for executing LLVM and Clang style test suites,
summarizing their results, and providing indication of failures. *lit* is
designed to be a lightweight testing tool with as simple a user interface as
possible.
+## Features
-Features
-========
+> - Portable!
+> - Flexible test discovery.
+> - Parallel test execution.
+> - Support for multiple test formats and test suite designs.
- * Portable!
- * Flexible test discovery.
- * Parallel test execution.
- * Support for multiple test formats and test suite designs.
-
-
-Documentation
-=============
+## Documentation
The official *lit* documentation is in the man page, available online at the LLVM
-Command Guide: http://llvm.org/cmds/lit.html.
+Command Guide: <http://llvm.org/cmds/lit.html>.
-
-Source
-======
+## Source
The *lit* source is available as part of LLVM, in the LLVM source repository:
-https://github.com/llvm/llvm-project/tree/main/llvm/utils/lit
-
+<https://github.com/llvm/llvm-project/tree/main/llvm/utils/lit>
-Contributing to lit
-===================
+## Contributing to lit
Please browse the issues labeled *tools:llvm-lit* in LLVM's issue tracker for
ideas on what to work on:
-https://github.com/llvm/llvm-project/labels/tools%3Allvm-lit
+<https://github.com/llvm/llvm-project/labels/tools%3Allvm-lit>
-Before submitting patches, run the test suite to ensure nothing has regressed::
+Before submitting patches, run the test suite to ensure nothing has regressed:
- # From within your LLVM source directory.
- utils/lit/lit.py \
- --path /path/to/your/llvm/build/bin \
- utils/lit/tests
+```
+# From within your LLVM source directory.
+utils/lit/lit.py \
+ --path /path/to/your/llvm/build/bin \
+ utils/lit/tests
+```
-Note that lit's tests depend on ``not`` and ``FileCheck``, LLVM utilities.
+Note that lit's tests depend on `not` and `FileCheck`, LLVM utilities.
You will need to have built LLVM tools in order to run lit's test suite
successfully.
You'll also want to confirm that lit continues to work when testing LLVM.
-Follow the instructions in http://llvm.org/docs/TestingGuide.html to run the
+Follow the instructions in <http://llvm.org/docs/TestingGuide.html> to run the
regression test suite:
- make check-llvm
+> make check-llvm
And be sure to run the llvm-lit wrapper script as well:
- /path/to/your/llvm/build/bin/llvm-lit utils/lit/tests
+> /path/to/your/llvm/build/bin/llvm-lit utils/lit/tests
Finally, make sure lit works when installed via setuptools:
- python utils/lit/setup.py install
- lit --path /path/to/your/llvm/build/bin utils/lit/tests
+> python utils/lit/setup.py install
+> lit --path /path/to/your/llvm/build/bin utils/lit/tests
diff --git a/openmp/tools/Modules/README.md b/openmp/tools/Modules/README.md
index b8cc5f08b390b0..fd67b8c35d3780 100644
--- a/openmp/tools/Modules/README.md
+++ b/openmp/tools/Modules/README.md
@@ -1,44 +1,43 @@
-=========================
-LLVM OpenMP CMake Modules
-=========================
+# LLVM OpenMP CMake Modules
This directory contains CMake modules for OpenMP. These can be included into a
project to include different OpenMP features.
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Find OpenMP Target Support
-==========================
+## Find OpenMP Target Support
This module will attempt to find OpenMP target offloading support for a given
device. The module will attempt to compile a test program using known compiler
flags for each requested architecture. If successful, the flags required for
-offloading will be loaded into the ``OpenMPTarget::OpenMPTarget_<device>``
-target or the ``OpenMPTarget_<device>_FLAGS`` variable. Currently supported target
-devices are ``NVPTX`` and ``AMDGPU``. This module is still under development so
+offloading will be loaded into the `OpenMPTarget::OpenMPTarget_<device>`
+target or the `OpenMPTarget_<device>_FLAGS` variable. Currently supported target
+devices are `NVPTX` and `AMDGPU`. This module is still under development so
some features may be missing.
To use this module, simply add the path to CMake's current module path and call
-``find_package``. The module will be installed with your OpenMP installation by
+`find_package`. The module will be installed with your OpenMP installation by
default. Including OpenMP offloading support in an application should now only
require a few additions.
-.. code-block:: cmake
+```cmake
+cmake_minimum_required(VERSION 3.20.0)
+project(offloadTest VERSION 1.0 LANGUAGES CXX)
- cmake_minimum_required(VERSION 3.20.0)
- project(offloadTest VERSION 1.0 LANGUAGES CXX)
+list(APPEND CMAKE_MODULE_PATH "${PATH_TO_OPENMP_INSTALL}/lib/cmake/openmp")
- list(APPEND CMAKE_MODULE_PATH "${PATH_TO_OPENMP_INSTALL}/lib/cmake/openmp")
+find_package(OpenMPTarget REQUIRED NVPTX)
- find_package(OpenMPTarget REQUIRED NVPTX)
-
- add_executable(offload)
- target_link_libraries(offload PRIVATE OpenMPTarget::OpenMPTarget_NVPTX)
- target_sources(offload PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/Main.cpp)
+add_executable(offload)
+target_link_libraries(offload PRIVATE OpenMPTarget::OpenMPTarget_NVPTX)
+target_sources(offload PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/Main.cpp)
+```
Using this module requires at least CMake version 3.20.0. Supported languages
are C and C++ with Fortran support planned in the future. If your application
requires building for a specific device architecture you can set the
-``OpenMPTarget_<device>_ARCH=<flag>`` variable. Compiler support is best for
+`OpenMPTarget_<device>_ARCH=<flag>` variable. Compiler support is best for
Clang but this module should work for other compiler vendors such as IBM or GNU.
+
>From 74265ec0a4d1adbd64d1ef66c08b17f0ffdf34f1 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Thu, 22 Oct 2026 20:40:11 +0000
Subject: [PATCH 2/2] [docs] Finish MyST migration for leftover docs
Clean up the rst2myst output for the lldb man pages, the VariableNames
proposal, and the lit, gn, cmake and OpenMP Modules READMEs. The man
pages keep generating byte-identical roff, and the READMEs use plain
GitHub-flavored Markdown because they are viewed on GitHub and are not
part of a Sphinx build. Declare Markdown as lit's long_description
content type now that its README is Markdown.
LLM-aided
---
cmake/README.md | 1 -
lldb/docs/man/lldb-server.md | 75 ++---------
lldb/docs/man/lldb.md | 21 +--
llvm/docs/Proposals/VariableNames.md | 189 ++++++++++++++-------------
llvm/utils/gn/README.md | 15 +--
llvm/utils/lit/README.md | 24 ++--
llvm/utils/lit/setup.py | 1 +
openmp/tools/Modules/README.md | 4 -
8 files changed, 136 insertions(+), 194 deletions(-)
diff --git a/cmake/README.md b/cmake/README.md
index b3b1f67544fcab..51e3899743de0b 100644
--- a/cmake/README.md
+++ b/cmake/README.md
@@ -51,4 +51,3 @@ set(LLVM_COMMON_CMAKE_UTILS ${CMAKE_CURRENT_SOURCE_DIR}/../cmake)
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 c0cd4d26ba560d..c20b3023586c6e 100644
--- a/lldb/docs/man/lldb-server.md
+++ b/lldb/docs/man/lldb-server.md
@@ -4,31 +4,16 @@ orphan: true
# lldb-server -- Server for LLDB Debugging Sessions
-```{eval-rst}
-.. program:: lldb-server
+```{program} lldb-server
```
## 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
@@ -59,35 +44,15 @@ Runs the platform server. LLDB can afterwards connect to the server using
## GDBSERVER COMMAND
-{program}`lldb-server`
-
- g[dbserver] \[
-
-*options*
-
-\] \[\[
-
-*host*
-
-\]:
-
-*port*
-
-\] \[[--]
-
-*program*
-
-
-
-*args*
-
-...\]
+:::{line-block}
+{program}`lldb-server` g[dbserver] [*options*] [[*host*]:*port*] [[--] *program* *args*...]
+:::
### CONNECTION
:::{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
+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.
:::
@@ -106,7 +71,7 @@ Write the listening port number to the specified pipe (fd).
:::{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.
+case, [host]:port denotes the remote address to connect to.
:::
### GENERAL OPTIONS
@@ -144,21 +109,9 @@ to launch or attach.
## PLATFORM COMMAND
-{program}`lldb-server`
-
- p[latform] \[
-
-*options*
-
-\] --server --listen \[\[
-
-*host*
-
-\]:
-
-*port*
-
-\]
+:::{line-block}
+{program}`lldb-server` p[latform] [*options*] --server --listen [[*host*]:*port*]
+:::
### CONNECTION
diff --git a/lldb/docs/man/lldb.md b/lldb/docs/man/lldb.md
index 0a9f2b96a58603..dab6fbdc8843b5 100644
--- a/lldb/docs/man/lldb.md
+++ b/lldb/docs/man/lldb.md
@@ -4,21 +4,14 @@ orphan: true
# lldb -- The Debugger
-```{eval-rst}
-.. program:: lldb
+```{program} lldb
```
## SYNOPSIS
-{program}`lldb`
-
- \[
-
-*options*
-
-\]
-
-*executable*
+:::{line-block}
+{program}`lldb` [*options*] *executable*
+:::
## DESCRIPTION
@@ -297,7 +290,7 @@ loading the file (via -o or -s) will be ignored.
## USING LLDB
In {program}`lldb` there is a help command which can be used to find
-descriptions and examples of all {program}`lldb` commands. To get help on
+descriptions and examples of all {program}`lldb` commands. To get help on
"breakpoint set" you would type "help breakpoint set".
There is also an apropos command which will search the help text of all
@@ -315,10 +308,10 @@ whose name is ~/.lldbinit followed by a "-" and the name of the current
program. This would be ~/.lldbinit-lldb for the command line {program}`lldb`
and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
file, {program}`lldb` will look for an init file in the home directory.
-If launched with a [REPL] option, it will first look for a REPL configuration
+If launched with a [REPL](#repl) option, it will first look for a REPL configuration
file, specific to the REPL language. The init file should be named as follow:
`.lldbinit-<language>-repl` (i.e. `.lldbinit-swift-repl`). If this file doesn't
-exist, or {program}`lldb` wasn't launch with [REPL], meaning there is neither
+exist, or {program}`lldb` wasn't launch with [REPL](#repl), meaning there is neither
a REPL init file nor an application specific init file, `lldb` will fallback to
the global ~/.lldbinit.
diff --git a/llvm/docs/Proposals/VariableNames.md b/llvm/docs/Proposals/VariableNames.md
index dfe8516fe6cd82..1a4caf1d76f2ea 100644
--- a/llvm/docs/Proposals/VariableNames.md
+++ b/llvm/docs/Proposals/VariableNames.md
@@ -1,3 +1,8 @@
+---
+myst:
+ footnote_transition: false
+---
+
# Variable Names Plan
This plan is *provisional*. It is not agreed upon. It is written with the
@@ -14,7 +19,7 @@ Improve the readability of LLVM code.
## Introduction
-The current [variable naming rule](../CodingStandards.html#name-types-functions-variables-and-enumerators-properly)
+The current [variable naming rule](../CodingStandards.md#name-types-functions-variables-and-enumerators-properly)
states:
> Variable names should be nouns (as they represent state). The name should be
@@ -42,8 +47,8 @@ InnerLoopVectorizer LB(L, PSE, LI, DT, TLI, TTI, AC, ORE, VF.Width, IC,
&LVL, &CM);
```
-Many other coding guidelines [^cite_lldb] [^cite_google] [^cite_webkit] [^cite_qt] [^cite_rust] [^cite_swift]
-[^cite_python] require that variable names begin with a lower case letter in contrast
+Many other coding guidelines [^lldb] [^google] [^webkit] [^qt] [^rust] [^swift]
+[^python] require that variable names begin with a lower case letter in contrast
to class names which begin with a capital letter. This convention means that the
most readable variable name also requires the least thought:
@@ -51,17 +56,17 @@ most readable variable name also requires the least thought:
Triple triple;
```
-There is some agreement that the current rule is broken [^cite_lattneragree]
-[^cite_arsenaultagree] [^cite_robinsonagree] and that acronyms are an obstacle to reading
-new code [^cite_malyutindistinguish] [^cite_carruthacronym] [^cite_picusacronym]. There are
-some opposing views [^cite_parzyszekacronym2] [^cite_ricciacronyms].
+There is some agreement that the current rule is broken [^lattneragree]
+[^arsenaultagree] [^robinsonagree] and that acronyms are an obstacle to reading
+new code [^malyutindistinguish] [^carruthacronym] [^picusacronym]. There are
+some opposing views [^parzyszekacronym2] [^ricciacronyms].
This work-in-progress proposal is to change the coding standard for variable
names to require that they start with a lower case letter.
[^footnote-1]: In [some cases](https://github.com/llvm/llvm-project/blob/8b72080d4d7b13072f371712eed333f987b7a18e/llvm/lib/CodeGen/SelectionDAG/SelectionDAG.cpp#L2727)
the type name *is* reused as a variable name, but this shadows the type name
- and confuses many debuggers [^cite_denisovcamelback].
+ and confuses many debuggers [^denisovcamelback].
## Variable Names Coding Standard Options
@@ -69,39 +74,39 @@ There are two main options for variable names that begin with a lower case
letter: `camelBack` and `lower_case`. (These are also known by other names
but here we use the terminology from clang-tidy).
-`camelBack` is consistent with [^cite_webkit], [^cite_qt] and [^cite_swift] while
-`lower_case` is consistent with [^cite_lldb], [^cite_google], [^cite_rust] and [^cite_python].
+`camelBack` is consistent with [^webkit], [^qt] and [^swift] while
+`lower_case` is consistent with [^lldb], [^google], [^rust] and [^python].
`camelBack` is already used for function names, which may be considered an
-advantage [^cite_lattnerfunction] or a disadvantage [^cite_carruthfunction].
+advantage [^lattnerfunction] or a disadvantage [^carruthfunction].
-Approval for `camelBack` was expressed by [^cite_denisovcamelback]
-[^cite_lattnerfunction] [^cite_ivanovicdistinguish].
-Opposition to `camelBack` was expressed by [^cite_carruthcamelback]
-[^cite_turnercamelback].
-Approval for `lower_case` was expressed by [^cite_carruthlower]
-[^cite_carruthcamelback] [^cite_turnerlldb].
-Opposition to `lower_case` was expressed by [^cite_lattnerlower].
+Approval for `camelBack` was expressed by [^denisovcamelback]
+[^lattnerfunction] [^ivanovicdistinguish].
+Opposition to `camelBack` was expressed by [^carruthcamelback]
+[^turnercamelback].
+Approval for `lower_case` was expressed by [^carruthlower]
+[^carruthcamelback] [^turnerlldb].
+Opposition to `lower_case` was expressed by [^lattnerlower].
### Differentiating variable kinds
An additional requested change is to distinguish between different kinds of
-variables [^cite_robinsondistinguish] [^cite_robinsondistinguish2] [^cite_jonesdistinguish]
-[^cite_ivanovicdistinguish] [^cite_carruthdistinguish] [^cite_malyutindistinguish].
+variables [^robinsondistinguish] [^robinsondistinguish2] [^jonesdistinguish]
+[^ivanovicdistinguish] [^carruthdistinguish] [^malyutindistinguish].
-Others oppose this idea [^cite_hahnledistinguish] [^cite_greenedistinguish]
-[^cite_hendersonprefix].
+Others oppose this idea [^hahnledistinguish] [^greenedistinguish]
+[^hendersonprefix].
A possibility is for member variables to be prefixed with `m_` and for global
variables to be prefixed with `g_` to distinguish them from local variables.
-This is consistent with [^cite_lldb]. The `m_` prefix is consistent with [^cite_webkit].
+This is consistent with [^lldb]. The `m_` prefix is consistent with [^webkit].
A variation is for member variables to be prefixed with `m`
-[^cite_ivanovicdistinguish] [^cite_beylsdistinguish]. This is consistent with [^cite_mozilla].
+[^ivanovicdistinguish] [^beylsdistinguish]. This is consistent with [^mozilla].
Another option is for member variables to be suffixed with `_` which is
-consistent with [^cite_google] and similar to [^cite_python]. Opposed by
-[^cite_parzyszekdistinguish].
+consistent with [^google] and similar to [^python]. Opposed by
+[^parzyszekdistinguish].
## Reducing the number of acronyms
@@ -115,14 +120,14 @@ acronyms despite what the coding standard says, much as it is today.
As well as changing the case of variable names, they could also be expanded to
their non-acronym form e.g. `Triple T` → `Triple triple`.
-There is support for expanding many acronyms [^cite_carruthacronym] [^cite_picusacronym]
+There is support for expanding many acronyms [^carruthacronym] [^picusacronym]
but there is a preference that expanding acronyms be deferred
-[^cite_parzyszekacronym] [^cite_carruthacronym].
+[^parzyszekacronym] [^carruthacronym].
The consensus within the community seems to be that at least some acronyms are
-valuable [^cite_parzyszekacronym] [^cite_lattneracronym]. The most commonly cited acronym
+valuable [^parzyszekacronym] [^lattneracronym]. The most commonly cited acronym
is `TLI` however that is used to refer to both `TargetLowering` and
-`TargetLibraryInfo` [^cite_greenedistinguish].
+`TargetLibraryInfo` [^greenedistinguish].
The following is a list of acronyms considered sufficiently useful that the
benefit of using them outweighs the cost of learning them. Acronyms that are
@@ -177,15 +182,15 @@ There are three main options for transitioning:
Proponents of keeping the current coding standard (i.e. not transitioning at
all) question whether the cost of transition outweighs the benefit
-[^cite_emersonconcern] [^cite_reamesconcern] [^cite_bradburyconcern].
+[^emersonconcern] [^reamesconcern] [^bradburyconcern].
The costs are that `git blame` will become less usable; and that merging the
-changes will be costly for downstream maintainers. See [Big bang] for potential
+changes will be costly for downstream maintainers. See [Big bang](#big-bang) for potential
mitigations.
### Laissez faire
The coding standard could allow both `CamelCase` and `camelBack` styles for
-variable names [^cite_lattnertransition].
+variable names [^lattnertransition].
A code review to implement this is at <https://reviews.llvm.org/D57896>.
@@ -195,9 +200,9 @@ A code review to implement this is at <https://reviews.llvm.org/D57896>.
#### Disadvantages
-> - Leads to inconsistency [^cite_bradburyconcern] [^cite_aminiinconsistent].
+> - Leads to inconsistency [^bradburyconcern] [^aminiinconsistent].
> - Inconsistency means it will be hard to know at a guess what name a variable
-> will have [^cite_dasinconsistent] [^cite_carruthinconsistent].
+> will have [^dasinconsistent] [^carruthinconsistent].
> - Some large-scale renaming may happen anyway, leading to its disadvantages
> without any mitigations.
@@ -207,21 +212,21 @@ With this approach, variables will be renamed by an automated script in a series
of large commits.
The principle advantage of this approach is that it minimises the cost of
-inconsistency [^cite_bradburytransition] [^cite_robinsontransition].
+inconsistency [^bradburytransition] [^robinsontransition].
It goes against a policy of avoiding large-scale reformatting of existing code
-[^cite_greenedistinguish].
+[^greenedistinguish].
It has been suggested that LLD would be a good starter project for the renaming
-[^cite_ueyama].
+[^ueyama].
#### Keeping git blame usable
`git blame` (or `git annotate`) permits quickly identifying the commit that
changed a given line in a file. After renaming variables, many lines will show
as being changed by that one commit, requiring a further invocation of `git
-blame` to identify prior, more interesting commits [^cite_greenegitblame]
-[^cite_ricciacronyms].
+blame` to identify prior, more interesting commits [^greenegitblame]
+[^ricciacronyms].
**Mitigation**: [git-hyper-blame](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-hyper-blame.html)
can ignore or "look through" a given set of commits.
@@ -239,11 +244,11 @@ renaming change could be difficult for the fork maintainers.
merge from the commit immediately before the renaming, then apply the renaming
script to their own branch. They can then merge again from the renaming commit,
resolving all conflicts by choosing their own version. This could be tested on
-the [^cite_sve] fork.
+the [^sve] fork.
## Provisional Plan
-This is a provisional plan for the [Big bang] approach. It has not been agreed.
+This is a provisional plan for the [Big bang](#big-bang) approach. It has not been agreed.
01. Investigate improving `git blame`. The extent to which it can be made to
"look through" commits may impact how big a change can be made.
@@ -257,14 +262,14 @@ This is a provisional plan for the [Big bang] approach. It has not been agreed.
05. Agree & announce a date for the renaming of the starter project (LLD).
-06. Update the [policy page](../CodingStandards.html). This will explain the
+06. Update the [policy page](../CodingStandards.md). This will explain the
old and new rules and which projects each applies to.
07. Refactor the starter project in two commits:
1. Add or change the project's .clang-tidy to reflect the agreed rules.
(This is in a separate commit to enable the merging process described in
- [Minimising cost of downstream merges]).
+ [Minimising cost of downstream merges](#minimising-cost-of-downstream-merges)).
Also update the project list on the policy page.
2. Apply `clang-tidy` to the project's files, with only the
@@ -327,99 +332,99 @@ This is a provisional plan for the [Big bang] approach. It has not been agreed.
## References
-[^cite_lldb]: LLDB Coding Conventions <https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html>
+[^lldb]: LLDB Coding Conventions <https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html>
-[^cite_google]: Google C++ Style Guide <https://google.github.io/styleguide/cppguide.html#Variable_Names>
+[^google]: Google C++ Style Guide <https://google.github.io/styleguide/cppguide.html#Variable_Names>
-[^cite_webkit]: WebKit Code Style Guidelines <https://webkit.org/code-style-guidelines/#names>
+[^webkit]: WebKit Code Style Guidelines <https://webkit.org/code-style-guidelines/#names>
-[^cite_qt]: Qt Coding Style <https://wiki.qt.io/Qt_Coding_Style#Declaring_variables>
+[^qt]: Qt Coding Style <https://wiki.qt.io/Qt_Coding_Style#Declaring_variables>
-[^cite_rust]: Rust naming conventions <https://doc.rust-lang.org/1.0.0/style/style/naming/README.html>
+[^rust]: Rust naming conventions <https://doc.rust-lang.org/1.0.0/style/style/naming/README.html>
-[^cite_swift]: Swift API Design Guidelines <https://swift.org/documentation/api-design-guidelines/#general-conventions>
+[^swift]: Swift API Design Guidelines <https://swift.org/documentation/api-design-guidelines/#general-conventions>
-[^cite_python]: Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/#function-and-variable-names>
+[^python]: Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/#function-and-variable-names>
-[^cite_mozilla]: Mozilla Coding style: Prefixes <https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html#prefixes>
+[^mozilla]: Mozilla Coding style: Prefixes <https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html#prefixes>
-[^cite_sve]: LLVM with support for SVE <https://github.com/ARM-software/LLVM-SVE>
+[^sve]: LLVM with support for SVE <https://github.com/ARM-software/LLVM-SVE>
-[^cite_aminiinconsistent]: Mehdi Amini, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html>
+[^aminiinconsistent]: Mehdi Amini, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html>
-[^cite_arsenaultagree]: Matt Arsenault, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html>
+[^arsenaultagree]: Matt Arsenault, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html>
-[^cite_beylsdistinguish]: Kristof Beyls, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html>
+[^beylsdistinguish]: Kristof Beyls, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html>
-[^cite_bradburyconcern]: Alex Bradbury, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html>
+[^bradburyconcern]: Alex Bradbury, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html>
-[^cite_bradburytransition]: Alex Bradbury, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html>
+[^bradburytransition]: Alex Bradbury, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html>
-[^cite_carruthacronym]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html>
+[^carruthacronym]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html>
-[^cite_carruthcamelback]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html>
+[^carruthcamelback]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html>
-[^cite_carruthdistinguish]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html>
+[^carruthdistinguish]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html>
-[^cite_carruthfunction]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html>
+[^carruthfunction]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html>
-[^cite_carruthinconsistent]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html>
+[^carruthinconsistent]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html>
-[^cite_carruthlower]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html>
+[^carruthlower]: Chandler Carruth, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html>
-[^cite_dasinconsistent]: Sanjoy Das, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html>
+[^dasinconsistent]: Sanjoy Das, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html>
-[^cite_denisovcamelback]: Alex Denisov, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html>
+[^denisovcamelback]: Alex Denisov, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html>
-[^cite_emersonconcern]: Amara Emerson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html>
+[^emersonconcern]: Amara Emerson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html>
-[^cite_greenedistinguish]: David Greene, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html>
+[^greenedistinguish]: David Greene, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html>
-[^cite_greenegitblame]: David Greene, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html>
+[^greenegitblame]: David Greene, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html>
-[^cite_hendersonprefix]: James Henderson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html>
+[^hendersonprefix]: James Henderson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html>
-[^cite_hähnledistinguish]: Nicolai Hähnle, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html>
+[^hahnledistinguish]: Nicolai Hähnle, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html>
-[^cite_ivanovicdistinguish]: Nemanja Ivanovic, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html>
+[^ivanovicdistinguish]: Nemanja Ivanovic, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html>
-[^cite_jonesdistinguish]: JD Jones, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html>
+[^jonesdistinguish]: JD Jones, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html>
-[^cite_lattneracronym]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html>
+[^lattneracronym]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html>
-[^cite_lattneragree]: Chris Latter, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html>
+[^lattneragree]: Chris Latter, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html>
-[^cite_lattnerfunction]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html>
+[^lattnerfunction]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html>
-[^cite_lattnerlower]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html>
+[^lattnerlower]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html>
-[^cite_lattnertransition]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html>
+[^lattnertransition]: Chris Lattner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html>
-[^cite_malyutindistinguish]: Danila Malyutin, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html>
+[^malyutindistinguish]: Danila Malyutin, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html>
-[^cite_parzyszekacronym]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html>
+[^parzyszekacronym]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html>
-[^cite_parzyszekacronym2]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html>
+[^parzyszekacronym2]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html>
-[^cite_parzyszekdistinguish]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html>
+[^parzyszekdistinguish]: Krzysztof Parzyszek, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html>
-[^cite_picusacronym]: Diana Picus, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html>
+[^picusacronym]: Diana Picus, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html>
-[^cite_reamesconcern]: Philip Reames, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html>
+[^reamesconcern]: Philip Reames, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html>
-[^cite_ricciacronyms]: Bruno Ricci, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html>
+[^ricciacronyms]: Bruno Ricci, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html>
-[^cite_robinsonagree]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html>
+[^robinsonagree]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html>
-[^cite_robinsondistinguish]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html>
+[^robinsondistinguish]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html>
-[^cite_robinsondistinguish2]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html>
+[^robinsondistinguish2]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html>
-[^cite_robinsontransition]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html>
+[^robinsontransition]: Paul Robinson, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html>
-[^cite_turnercamelback]: Zachary Turner, <https://reviews.llvm.org/D57896#1402264>
+[^turnercamelback]: Zachary Turner, <https://reviews.llvm.org/D57896#1402264>
-[^cite_turnerlldb]: Zachary Turner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html>
+[^turnerlldb]: Zachary Turner, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html>
-[^cite_ueyama]: Rui Ueyama, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html>
+[^ueyama]: Rui Ueyama, <http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html>
diff --git a/llvm/utils/gn/README.md b/llvm/utils/gn/README.md
index d0a3f13234be16..c47deaf4e6e6ef 100644
--- a/llvm/utils/gn/README.md
+++ b/llvm/utils/gn/README.md
@@ -1,11 +1,5 @@
# Building LLVM with GN
-```{contents}
-:local: true
-```
-
-(introduction)=
-
## Introduction
*Warning* The GN build is experimental and best-effort. It might not work,
@@ -27,14 +21,13 @@ non-goals for the GN build.
This is a [good overview of GN](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12).
-(quick-start)=
-
## Quick start
1. `git clone https://github.com/llvm/llvm-project.git; cd llvm-project` if
you don't have a checkout yet.
2. `llvm/utils/gn/get.py` to download a prebuilt gn binary if you're on a
- 64-bit X86 system running Linux, macOS, or Windows. [Build gn yourself](https://gn.googlesource.com/gn/#getting-started) if you're on a different
+ 64-bit X86 system running Linux, macOS, or Windows. [Build gn yourself
+ ](https://gn.googlesource.com/gn/#getting-started) if you're on a different
platform or don't want to trust prebuilt binaries.
3. `llvm/utils/gn/gn.py gen out/gn` to run GN and create build files.
`out/gn` is the build directory, it can have any name, and you can have as
@@ -64,8 +57,6 @@ To not put `BUILD.gn` files into the main tree, they are all below
`utils/gn/secondary`. For example, the build file for `llvm/lib/Support`
is in `utils/gn/secondary/llvm/lib/Support`.
-(syncing-gn-files-from-cmake-files)=
-
## Syncing GN files from CMake files
Sometimes after pulling in the latest changes, the GN build doesn't work.
@@ -81,8 +72,6 @@ a new corresponding `BUILD.gn` file below `llvm/utils/gn/secondary/`.
If the dependencies in a `CMakeLists.txt` file have been changed, you have to
manually analyze and fix.
-(philosophy)=
-
## Philosophy
GN believes in using GN arguments to configure the build explicitly, instead
diff --git a/llvm/utils/lit/README.md b/llvm/utils/lit/README.md
index cb0e837b7cb75e..f8a4a10244ec9b 100644
--- a/llvm/utils/lit/README.md
+++ b/llvm/utils/lit/README.md
@@ -9,10 +9,10 @@ possible.
## Features
-> - Portable!
-> - Flexible test discovery.
-> - Parallel test execution.
-> - Support for multiple test formats and test suite designs.
+- Portable!
+- Flexible test discovery.
+- Parallel test execution.
+- Support for multiple test formats and test suite designs.
## Documentation
@@ -32,7 +32,7 @@ ideas on what to work on:
Before submitting patches, run the test suite to ensure nothing has regressed:
-```
+```sh
# From within your LLVM source directory.
utils/lit/lit.py \
--path /path/to/your/llvm/build/bin \
@@ -47,14 +47,20 @@ You'll also want to confirm that lit continues to work when testing LLVM.
Follow the instructions in <http://llvm.org/docs/TestingGuide.html> to run the
regression test suite:
-> make check-llvm
+```sh
+make check-llvm
+```
And be sure to run the llvm-lit wrapper script as well:
-> /path/to/your/llvm/build/bin/llvm-lit utils/lit/tests
+```sh
+/path/to/your/llvm/build/bin/llvm-lit utils/lit/tests
+```
Finally, make sure lit works when installed via setuptools:
-> python utils/lit/setup.py install
-> lit --path /path/to/your/llvm/build/bin utils/lit/tests
+```sh
+python utils/lit/setup.py install
+lit --path /path/to/your/llvm/build/bin utils/lit/tests
+```
diff --git a/llvm/utils/lit/setup.py b/llvm/utils/lit/setup.py
index 51b705e3cd7e69..61dad30ac36daf 100644
--- a/llvm/utils/lit/setup.py
+++ b/llvm/utils/lit/setup.py
@@ -26,6 +26,7 @@
description="A Software Testing Tool",
keywords="test C++ automatic discovery",
long_description=long_description,
+ long_description_content_type="text/markdown",
classifiers=[
"Development Status :: 3 - Alpha",
"Environment :: Console",
diff --git a/openmp/tools/Modules/README.md b/openmp/tools/Modules/README.md
index fd67b8c35d3780..437fd2fb2e3f32 100644
--- a/openmp/tools/Modules/README.md
+++ b/openmp/tools/Modules/README.md
@@ -3,10 +3,6 @@
This directory contains CMake modules for OpenMP. These can be included into a
project to include different OpenMP features.
-```{contents}
-:local: true
-```
-
## Find OpenMP Target Support
This module will attempt to find OpenMP target offloading support for a given
More information about the llvm-branch-commits
mailing list