[llvm-branch-commits] [llvm] [docs] Migrate 22 popular LLVM docs to MyST (PR #201244)

[Antonio Frighetto via llvm-branch-commits]

================
@@ -1000,242 +1107,242 @@ variables that are already set unless the FORCE option is specified.
 A few notes about CMake Caches:
 
 - Order of command line arguments is important
-
-  - ``-D`` arguments specified before ``-C`` are set before the cache is processed and
-    can be read inside the cache file
-  - ``-D`` arguments specified after ``-C`` are set after the cache is processed and
-    are unset inside the cache file
-
-- All ``-D`` arguments will override cache file settings
+  - `-D` arguments specified before `-C` are set before the cache is processed and
+        can be read inside the cache file
+  - `-D` arguments specified after `-C` are set after the cache is processed and
+        are unset inside the cache file
+- All `-D` arguments will override cache file settings
 - CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command
-  line arguments
-- It is recommended that all ``-D`` options be specified *before* ``-C``
+    line arguments
+- It is recommended that all `-D` options be specified *before* `-C`
 
 For more information about some of the advanced build configurations supported
-via Cache files see :doc:`AdvancedBuilds`.
+via Cache files see {doc}`AdvancedBuilds`.
 
-Executing the Tests
-===================
+## Executing the Tests
 
 Testing is performed when the *check-all* target is built. For instance, if you are
 using Makefiles, execute this command in the root of your build directory:
 
-.. code-block:: console
+``` console
+$ make check-all
+```
 
-  $ make check-all
+On Visual Studio, you may run tests by building the project \"check-all\".
+For more information about testing, see the {doc}`TestingGuide`.
 
-On Visual Studio, you may run tests by building the project "check-all".
-For more information about testing, see the :doc:`TestingGuide`.
+## Cross compiling
 
-Cross compiling
-===============
+See [this wiki
+page](https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling)
+for generic instructions on how to cross-compile with CMake. It goes into
+detailed explanations and may seem daunting, but it is not. The wiki page has
+several examples including toolchain files. Go directly to the `Information how
+to set up various cross compiling toolchains` section for a quick solution.
 
-See `this wiki page <https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling>`_ for
-generic instructions on how to cross-compile with CMake. It goes into detailed
-explanations and may seem daunting, but it is not. The wiki page has
-several examples including toolchain files. Go directly to the
-``Information how to set up various cross compiling toolchains`` section
-for a quick solution.
+Also see the [LLVM-related variables](#llvm-related-variables) section for
+variables used when cross-compiling.
 
-Also see the `LLVM-related variables`_ section for variables used when
-cross-compiling.
-
-Embedding LLVM in your project
-==============================
+## Embedding LLVM in your project
 
 From LLVM 3.5 onward, the CMake build system exports LLVM libraries as
 importable CMake targets. This means that clients of LLVM can now reliably use
 CMake to develop their own LLVM-based projects against an installed version of
 LLVM regardless of how it was built.
 
-Here is a simple example of a ``CMakeLists.txt`` file that imports the LLVM libraries
-and uses them to build a simple application ``simple-tool``.
-
-.. code-block:: cmake
+Here is a simple example of a `CMakeLists.txt` file that imports the LLVM libraries
+and uses them to build a simple application `simple-tool`.
 
-  cmake_minimum_required(VERSION 3.20.0)
-  project(SimpleProject)
+``` cmake
+cmake_minimum_required(VERSION 3.20.0)
+project(SimpleProject)
 
-  find_package(LLVM REQUIRED CONFIG)
+find_package(LLVM REQUIRED CONFIG)
 
-  message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
-  message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
+message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
 
-  # Set your project compile flags.
-  # E.g. if using the C++ header files
-  # you will need to enable C++11 support
-  # for your compiler.
+# Set your project compile flags.
+# E.g. if using the C++ header files
+# you will need to enable C++11 support
+# for your compiler.
 
-  include_directories(${LLVM_INCLUDE_DIRS})
-  separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
-  add_definitions(${LLVM_DEFINITIONS_LIST})
+include_directories(${LLVM_INCLUDE_DIRS})
+separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
+add_definitions(${LLVM_DEFINITIONS_LIST})
 
-  # Now build our tools
-  add_executable(simple-tool tool.cpp)
+# Now build our tools
+add_executable(simple-tool tool.cpp)
 
-  # Find the libraries that correspond to the LLVM components
-  # that we wish to use
-  llvm_map_components_to_libnames(llvm_libs support core irreader)
+# Find the libraries that correspond to the LLVM components
+# that we wish to use
+llvm_map_components_to_libnames(llvm_libs support core irreader)
 
-  # Link against LLVM libraries
-  target_link_libraries(simple-tool ${llvm_libs})
+# Link against LLVM libraries
+target_link_libraries(simple-tool ${llvm_libs})
+```
 
-The ``find_package(...)`` directive when used in CONFIG mode (as in the above
-example) will look for the ``LLVMConfig.cmake`` file in various locations (see
-CMake manual for details).  It creates an ``LLVM_DIR`` cache entry to save the
-directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
-directory (e.g., by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to
-the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
+The `find_package(...)` directive when used in CONFIG mode (as in the above
+example) will look for the `LLVMConfig.cmake` file in various locations (see
+CMake manual for details). It creates an `LLVM_DIR` cache entry to save the
+directory where `LLVMConfig.cmake` is found or allows the user to specify the
+directory (e.g., by passing `-DLLVM_DIR=/usr/lib/cmake/llvm` to
+the `cmake` command or by setting it directly in `ccmake` or `cmake-gui`).
 
 This file is available in two different locations.
 
-* ``<LLVM_INSTALL_PACKAGE_DIR>/LLVMConfig.cmake`` where
-  ``<LLVM_INSTALL_PACKAGE_DIR>`` is the location where LLVM CMake modules are
-  installed as part of an installed version of LLVM. This is typically
-  ``cmake/llvm/`` within the lib directory. On Linux, this is typically
-  ``/usr/lib/cmake/llvm/LLVMConfig.cmake``.
-
-* ``<LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake`` where
-  ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only
-  available when building LLVM with CMake.**
+- `<LLVM_INSTALL_PACKAGE_DIR>/LLVMConfig.cmake` where
+    `<LLVM_INSTALL_PACKAGE_DIR>` is the location where LLVM CMake modules are
+    installed as part of an installed version of LLVM. This is typically
+    `cmake/llvm/` within the lib directory. On Linux, this is typically
+    `/usr/lib/cmake/llvm/LLVMConfig.cmake`.
+- `<LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake` where
+    `<LLVM_BUILD_ROOT>` is the root of the LLVM build tree. **Note: this is
+    only available when building LLVM with CMake.**
 
 If LLVM is installed in your operating system's normal installation prefix (e.g.
-on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
+on Linux this is usually `/usr/`) `find_package(LLVM ...)` will
 automatically find LLVM if it is installed correctly. If LLVM is not installed
 or you wish to build directly against the LLVM build tree you can use
-``LLVM_DIR`` as previously mentioned.
+`LLVM_DIR` as previously mentioned.
 
-The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
+The `LLVMConfig.cmake` file sets various useful variables. Notable variables
 include:
 
-``LLVM_CMAKE_DIR``
-  The path to the LLVM CMake directory (i.e., the directory containing
-  ``LLVMConfig.cmake``).
+`LLVM_CMAKE_DIR`
 
-``LLVM_DEFINITIONS``
-  A list of preprocessor defines that should be used when building against LLVM.
+:   The path to the LLVM CMake directory (i.e., the directory containing
+    `LLVMConfig.cmake`).
 
-``LLVM_ENABLE_ASSERTIONS``
-  This is set to ON if LLVM was built with assertions, otherwise OFF.
+`LLVM_DEFINITIONS`
 
-``LLVM_ENABLE_EH``
-  This is set to ON if LLVM was built with exception handling (EH) enabled,
-  otherwise OFF.
+:   A list of preprocessor defines that should be used when building against
+    LLVM.
 
-``LLVM_ENABLE_RTTI``
-  This is set to ON if LLVM was built with run time type information (RTTI),
-  otherwise OFF.
+`LLVM_ENABLE_ASSERTIONS`
 
-``LLVM_INCLUDE_DIRS``
-  A list of include paths to directories containing LLVM header files.
+:   This is set to ON if LLVM was built with assertions, otherwise OFF.
 
-``LLVM_PACKAGE_VERSION``
-  The LLVM version. This string can be used with CMake conditionals, e.g., ``if
-  (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
+`LLVM_ENABLE_EH`
 
-``LLVM_TOOLS_BINARY_DIR``
-  The path to the directory containing the LLVM tools (e.g., ``llvm-as``).
+:   This is set to ON if LLVM was built with exception handling (EH) enabled,
+    otherwise OFF.
 
-Notice that in the above example we link ``simple-tool`` against several LLVM
-libraries. The list of libraries is determined by using the
-``llvm_map_components_to_libnames()`` CMake function. For a list of available
-components look at the output of running ``llvm-config --components``.
+`LLVM_ENABLE_RTTI`
 
-Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
-used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
-and will be removed in a future version of LLVM.
+:   This is set to ON if LLVM was built with run time type information (RTTI),
+    otherwise OFF.
 
-.. _cmake-out-of-source-pass:
+`LLVM_INCLUDE_DIRS`
 
-Developing LLVM passes out of source
-------------------------------------
+:   A list of include paths to directories containing LLVM header files.
 
-You can develop LLVM passes out of LLVM's source tree (i.e., against an
-installed or built LLVM). An example of a project layout is provided below.
+`LLVM_PACKAGE_VERSION`
 
-.. code-block:: none
+:   The LLVM version. This string can be used with CMake conditionals, e.g.,
+    `if (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")`.
 
-  <project dir>/
-      |
-      CMakeLists.txt
-      <pass name>/
-          |
-          CMakeLists.txt
-          Pass.cpp
-          ...
+`LLVM_TOOLS_BINARY_DIR`
 
-Contents of ``<project dir>/CMakeLists.txt``:
+:   The path to the directory containing the LLVM tools (e.g., `llvm-as`).
 
-.. code-block:: cmake
+Notice that in the above example we link `simple-tool` against several LLVM
+libraries. The list of libraries is determined by using the
+`llvm_map_components_to_libnames()` CMake function. For a list of available
+components look at the output of running `llvm-config --components`.
+
+Note that for LLVM \< 3.5 `llvm_map_components_to_libraries()` was
+used instead of `llvm_map_components_to_libnames()`. This is now deprecated
+and will be removed in a future version of LLVM.
 
-  find_package(LLVM REQUIRED CONFIG)
+(cmake-out-of-source-pass)=
+### Developing LLVM passes out of source
 
-  separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
-  add_definitions(${LLVM_DEFINITIONS_LIST})
-  include_directories(${LLVM_INCLUDE_DIRS})
+You can develop LLVM passes out of LLVM's source tree (i.e., against an
+installed or built LLVM). An example of a project layout is provided below.
 
-  add_subdirectory(<pass name>)
+``` none
+<project dir>/
+    |
+    CMakeLists.txt
+    <pass name>/
+        |
+        CMakeLists.txt
+        Pass.cpp
+        ...
+```
 
-Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
+Contents of `<project dir>/CMakeLists.txt`:
 
-.. code-block:: cmake
+``` cmake
+find_package(LLVM REQUIRED CONFIG)
 
-  add_library(LLVMPassname MODULE Pass.cpp)
+separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
+add_definitions(${LLVM_DEFINITIONS_LIST})
+include_directories(${LLVM_INCLUDE_DIRS})
 
-Note if you intend for this pass to be merged into the LLVM source tree at some
-point in the future it might make more sense to use LLVM's internal
-``add_llvm_library`` function with the MODULE argument instead by...
+add_subdirectory(<pass name>)
+```
 
+Contents of `<project dir>/<pass name>/CMakeLists.txt`:
 
-Adding the following to ``<project dir>/CMakeLists.txt`` (after
-``find_package(LLVM ...)``)
+``` cmake
+add_library(LLVMPassname MODULE Pass.cpp)
+```
 
-.. code-block:: cmake
+Note if you intend for this pass to be merged into the LLVM source tree at some
+point in the future it might make more sense to use LLVM's internal
+`add_llvm_library` function with the MODULE argument instead by\...
 
-  list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
-  include(AddLLVM)
+Adding the following to `<project dir>/CMakeLists.txt` (after
+`find_package(LLVM ...)`)
 
-And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
+``` cmake
+list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+include(AddLLVM)
+```
 
-.. code-block:: cmake
+And then changing `<project dir>/<pass name>/CMakeLists.txt` to
 
-  add_llvm_library(LLVMPassname MODULE
-    Pass.cpp
-    )
+``` cmake
+add_llvm_library(LLVMPassname MODULE
+  Pass.cpp
+  )
+```
 
 When you are done developing your pass, you may wish to integrate it
 into the LLVM source tree. You can achieve it in two easy steps:
 
-#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transforms`` directory.
-
-#. Adding ``add_subdirectory(<pass name>)`` line into
-   ``<LLVM root>/lib/Transforms/CMakeLists.txt``.
+1. Copying `<pass name>` folder into `<LLVM root>/lib/Transforms` directory.
+2. Adding `add_subdirectory(<pass name>)` line into `<LLVM
+    root>/lib/Transforms/CMakeLists.txt`.
 
-Compiler/Platform-specific topics
-=================================
+## Compiler/Platform-specific topics
 
 Notes for specific compilers and/or platforms.
 
-Windows
--------
+### Windows
 
 **LLVM_COMPILER_JOBS**:STRING
-  Specifies the maximum number of parallel compiler jobs to use per project
-  when building with msbuild or Visual Studio. Only supported for the Visual
-  Studio 2010 CMake generator. 0 means use all processors. Default is 0.
+
+:   Specifies the maximum number of parallel compiler jobs to use per project
+    when building with msbuild or Visual Studio. Only supported for the Visual
+    Studio 2010 CMake generator. 0 means use all processors. Default is 0.
 
 **CMAKE_MT**:STRING
-  When compiling with clang-cl, CMake may use ``llvm-mt`` as the Manifest Tool
-  when available. ```llvm-mt``` is only present when libxml2 is found at build-time.
-  To ensure using Microsoft's Manifest Tool set `CMAKE_MT=mt`.
 
-Apple/OSX
----------
+:   When compiling with clang-cl, CMake may use `llvm-mt` as the Manifest Tool
+    when available. `llvm-mt` is only present when libxml2 is found at
+    build-time. To ensure using Microsoft's Manifest Tool set `CMAKE_MT=mt`.
+
+### Apple/OSX
 
 **CMAKE_OSX_SYSROOT**:STRING
-  When compiling for OSX, in order for the test suite to find libSystem to link
-  dylib tests you'll need to run CMake with ```xcrun --show-sdk-path``` as the
-  string to pass in so that the testsuite can find your os libraries.
 
-  This will show up as ```ld: library not found for -lSystem``` when running
-  tests.
+:   When compiling for OSX, in order for the test suite to find libSystem to
+    link dylib tests you'll need to run CMake with `` `xcrun --show-sdk-path
+    ``\` as the string to pass in so that the testsuite can find your os
----------------
antoniofrighetto wrote:

Stray `\`, below with `-lSystem` too.

https://github.com/llvm/llvm-project/pull/201244