llvm/docs/UserGuides.rst

   1 User Guides
   2 ===========
   3
   4 NOTE: If you are a user who is only interested in using an LLVM-based compiler,
   5 you should look into `Clang <https://clang.llvm.org>`_ instead. The
   6 documentation here is intended for users who have a need to work with the
   7 intermediate LLVM representation.
   8
   9 .. contents::
  10    :local:
  11
  12 .. toctree::
  13    :hidden:
  14
  15    AArch64SME
  16    AddingConstrainedIntrinsics
  17    AdvancedBuilds
  18    AliasAnalysis
  19    AMDGPUUsage
  20    Benchmarking
  21    BigEndianNEON
  22    BuildingADistribution
  23    CFIVerify
  24    CMake
  25    CMakePrimer
  26    CodeGenerator
  27    CodeOfConduct
  28    CommandLine
  29    CompileCudaWithLLVM
  30    CoverageMappingFormat
  31    CycleTerminology
  32    DebuggingJITedCode
  33    DirectXUsage
  34    Docker
  35    FatLTO
  36    ExtendingLLVM
  37    GitHub
  38    GoldPlugin
  39    GlobalISel/MIRPatterns
  40    HowToBuildOnARM
  41    HowToBuildWithPGO
  42    HowToBuildWindowsItaniumPrograms
  43    HowToCrossCompileBuiltinsOnArm
  44    HowToCrossCompileLLVM
  45    HowToUpdateDebugInfo
  46    InstCombineContributorGuide
  47    InstrProfileFormat
  48    InstrRefDebugInfo
  49    LinkTimeOptimization
  50    LoopTerminology
  51    MarkdownQuickstartTemplate
  52    MemorySSA
  53    MergeFunctions
  54    MCJITDesignAndImplementation
  55    MisExpect
  56    ORCv2
  57    OpaquePointers
  58    JITLink
  59    NewPassManager
  60    NVPTXUsage
  61    Passes
  62    ReportingGuide
  63    ResponseGuide
  64    Remarks
  65    RemoveDIsDebugInfo
  66    RISCVUsage
  67    RISCV/RISCVVectorExtension
  68    SourceLevelDebugging
  69    SPIRVUsage
  70    SandboxIR
  71    StackSafetyAnalysis
  72    SupportLibrary
  73    TableGen/index
  74    TableGenFundamentals
  75    Vectorizers
  76    WritingAnLLVMPass
  77    WritingAnLLVMNewPMPass
  78    WritingAnLLVMBackend
  79    yaml2obj
  80
  81 Clang
  82 -----
  83
  84 :doc:`HowToBuildOnARM`
  85    Notes on building and testing LLVM/Clang on ARM.
  86
  87 :doc:`HowToBuildWithPGO`
  88     Notes on building LLVM/Clang with PGO.
  89
  90 :doc:`HowToCrossCompileLLVM`
  91    Notes on cross-building and testing LLVM/Clang.
  92
  93 `How to build the C, C++, ObjC, and ObjC++ front end`__
  94    Instructions for building the clang front-end from source.
  95
  96    .. __: https://clang.llvm.org/get_started.html
  97
  98 :doc:`CoverageMappingFormat`
  99   This describes the format and encoding used for LLVM’s code coverage mapping.
 100
 101 :doc:`CFIVerify`
 102   A description of the verification tool for Control Flow Integrity.
 103
 104 LLVM Builds and Distributions
 105 -----------------------------
 106
 107 :doc:`BuildingADistribution`
 108   A best-practices guide for using LLVM's CMake build system to package and
 109   distribute LLVM-based tools.
 110
 111 :doc:`CMake`
 112    An addendum to the main Getting Started guide for those using the `CMake
 113    build system <http://www.cmake.org>`_.
 114
 115 :doc:`Docker`
 116    A reference for using Dockerfiles provided with LLVM.
 117
 118 :doc:`Support Library <SupportLibrary>`
 119    This document describes the LLVM Support Library (``lib/Support``) and
 120    how to keep LLVM source code portable.
 121
 122 :doc:`AdvancedBuilds`
 123    This document describes more advanced build configurations.
 124
 125 Optimizations
 126 -------------
 127
 128 :doc:`WritingAnLLVMNewPMPass`
 129    Information on how to write LLVM transformations under the new pass
 130    manager.
 131
 132 :doc:`WritingAnLLVMPass`
 133    Information on how to write LLVM transformations and analyses under the
 134    legacy pass manager.
 135
 136 :doc:`Passes`
 137    A list of optimizations and analyses implemented in LLVM.
 138
 139 :doc:`StackSafetyAnalysis`
 140   This document describes the design of the stack safety analysis of local
 141   variables.
 142
 143 :doc:`MergeFunctions`
 144   Describes functions merging optimization.
 145
 146 :doc:`AliasAnalysis`
 147    Information on how to write a new alias analysis implementation or how to
 148    use existing analyses.
 149
 150 :doc:`MemorySSA`
 151    Information about the MemorySSA utility in LLVM, as well as how to use it.
 152
 153 :doc:`LoopTerminology`
 154   A document describing Loops and associated terms as used in LLVM.
 155
 156 :doc:`CycleTerminology`
 157   A document describing cycles as a generalization of loops.
 158
 159 :doc:`Vectorizers`
 160    This document describes the current status of vectorization in LLVM.
 161
 162 :doc:`LinkTimeOptimization`
 163    This document describes the interface between LLVM intermodular optimizer
 164    and the linker and its design
 165
 166 :doc:`GoldPlugin`
 167    How to build your programs with link-time optimization on Linux.
 168
 169 :doc:`Remarks`
 170    A reference on the implementation of remarks in LLVM.
 171
 172 :doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
 173    This document describes the design and philosophy behind the LLVM
 174    source-level debugger.
 175
 176 :doc:`How to Update Debug Info <HowToUpdateDebugInfo>`
 177    This document specifies how to correctly update debug info in various kinds
 178    of code transformations.
 179
 180 :doc:`InstrRefDebugInfo`
 181    This document explains how LLVM uses value tracking, or instruction
 182    referencing, to determine variable locations for debug info in the final
 183    stages of compilation.
 184
 185 :doc:`RemoveDIsDebugInfo`
 186    This is a migration guide describing how to move from debug info using
 187    intrinsics such as dbg.value to using the non-instruction DbgRecord object.
 188
 189 :doc:`InstrProfileFormat`
 190    This document explains two binary formats of instrumentation-based profiles.
 191
 192 :doc:`InstCombineContributorGuide`
 193    This document specifies guidelines for contributions for InstCombine and
 194    related passes.
 195
 196
 197 Code Generation
 198 ---------------
 199
 200 :doc:`WritingAnLLVMBackend`
 201    Information on how to write LLVM backends for machine targets.
 202
 203 :doc:`CodeGenerator`
 204    The design and implementation of the LLVM code generator.  Useful if you are
 205    working on retargetting LLVM to a new architecture, designing a new codegen
 206    pass, or enhancing existing components.
 207
 208 :doc:`TableGen <TableGen/index>`
 209    Describes the TableGen tool, which is used heavily by the LLVM code
 210    generator.
 211
 212 ==========
 213 GlobalISel
 214 ==========
 215
 216 :doc:`MIRPatterns <GlobalISel/MIRPatterns>`
 217    Describes the design of MIR Patterns and how to use them.
 218
 219 ===
 220 JIT
 221 ===
 222
 223 :doc:`MCJITDesignAndImplementation`
 224    Describes the inner workings of MCJIT execution engine.
 225
 226 :doc:`ORCv2`
 227    Describes the design and implementation of the ORC APIs, including some
 228    usage examples, and a guide for users transitioning from ORCv1 to ORCv2.
 229
 230 :doc:`JITLink`
 231    Describes the design and APIs for the JITLink library, ORC's new JIT
 232    linker.
 233
 234 :doc:`DebuggingJITedCode`
 235    How to debug JITed code with GDB.
 236
 237 Additional Topics
 238 -----------------
 239
 240 :doc:`CommandLine`
 241   Provides information on using the command line parsing library.
 242
 243 :doc:`ExtendingLLVM`
 244   Look here to see how to add instructions and intrinsics to LLVM.
 245
 246 :doc:`AddingConstrainedIntrinsics`
 247    Gives the steps necessary when adding a new constrained math intrinsic
 248    to LLVM.
 249
 250 :doc:`HowToBuildWindowsItaniumPrograms`
 251    Notes on assembling a Windows Itanium environment.
 252
 253 :doc:`HowToCrossCompileBuiltinsOnArm`
 254    Notes on cross-building and testing the compiler-rt builtins for Arm.
 255
 256 :doc:`BigEndianNEON`
 257   LLVM's support for generating NEON instructions on big endian ARM targets is
 258   somewhat nonintuitive. This document explains the implementation and rationale.
 259
 260 :doc:`AArch64SME`
 261   LLVM's support for AArch64 SME ACLE and ABI.
 262
 263 :doc:`CompileCudaWithLLVM`
 264   LLVM support for CUDA.
 265
 266 :doc:`NVPTXUsage`
 267    This document describes using the NVPTX backend to compile GPU kernels.
 268
 269 :doc:`AMDGPUUsage`
 270    This document describes using the AMDGPU backend to compile GPU kernels.
 271
 272 :doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`
 273    This document describes DWARF extensions to support heterogeneous debugging
 274    for targets such as the AMDGPU backend.
 275
 276 :doc:`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack`
 277    This document describes a DWARF extension to allow location descriptions on
 278    the DWARF expression stack. It is part of
 279    :doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`.
 280
 281 :doc:`SPIRVUsage`
 282    This document describes using the SPIR-V target to compile GPU kernels.
 283
 284 :doc:`DirectXUsage`
 285    This document describes using the DirectX target to compile GPU code for the
 286    DirectX runtime.
 287
 288 :doc:`RISCVUsage`
 289    This document describes using the RISCV-V target.
 290
 291 :doc:`RISCV/RISCVVectorExtension`
 292    This document describes how the RISC-V Vector extension can be expressed in LLVM IR and how code is generated for it in the backend.
 293
 294 :doc:`Sandbox IR <SandboxIR>`
 295    This document describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.