User Guides
===========

NOTE: If you are a user who is only interested in using an LLVM-based compiler,
you should look into `Clang <https://clang.llvm.org>`_ instead. The
documentation here is intended for users who have a need to work with the
intermediate LLVM representation.

.. contents::
   :local:

.. toctree::
   :hidden:

   AArch64SME
   AddingConstrainedIntrinsics
   AdminTasks
   AdvancedBuilds
   AliasAnalysis
   AMDGPUUsage
   Benchmarking
   BigEndianNEON
   BuildingADistribution
   CFIVerify
   CMake
   CMakePrimer
   CodeGenerator
   CodeOfConduct
   CommandLine
   CompileCudaWithLLVM
   CoverageMappingFormat
   CycleTerminology
   DebuggingJITedCode
   DirectXUsage
   Docker
   DTLTO
   FatLTO
   ExtendingLLVM
   GitHub
   GoldPlugin
   GlobalISel/MIRPatterns
   HowToBuildOnARM
   HowToBuildWithPGO
   HowToBuildWindowsItaniumPrograms
   HowToCrossCompileBuiltinsOnArm
   HowToCrossCompileLLVM
   HowToUpdateDebugInfo
   InstCombineContributorGuide
   InstrProfileFormat
   InstrRefDebugInfo
   KeyInstructionsDebugInfo
   LinkTimeOptimization
   LoopTerminology
   MarkdownQuickstartTemplate
   MemorySSA
   MergeFunctions
   MCJITDesignAndImplementation
   MisExpect
   ORCv2
   OpaquePointers
   JITLink
   NewPassManager
   NVPTXUsage
   Passes
   ReportingGuide
   ResponseGuide
   Remarks
   RemoveDIsDebugInfo
   RISCVUsage
   RISCV/RISCVVectorExtension
   SourceLevelDebugging
   SPIRVUsage
   SandboxIR
   StackSafetyAnalysis
   SupportLibrary
   TableGen/index
   TableGenFundamentals
   Telemetry
   Vectorizers
   WritingAnLLVMPass
   WritingAnLLVMNewPMPass
   WritingAnLLVMBackend
   yaml2obj

Clang
-----

:doc:`HowToBuildOnARM`
   Notes on building and testing LLVM/Clang on ARM.

:doc:`HowToBuildWithPGO`
    Notes on building LLVM/Clang with PGO.

:doc:`HowToCrossCompileLLVM`
   Notes on cross-building and testing LLVM/Clang.

`How to build the C, C++, ObjC, and ObjC++ front end`__
   Instructions for building the clang front-end from source.

   .. __: https://clang.llvm.org/get_started.html

:doc:`CoverageMappingFormat`
  This describes the format and encoding used for LLVM’s code coverage mapping.

:doc:`CFIVerify`
  A description of the verification tool for Control Flow Integrity.

LLVM Builds and Distributions
-----------------------------

:doc:`BuildingADistribution`
  A best-practices guide for using LLVM's CMake build system to package and
  distribute LLVM-based tools.

:doc:`CMake`
   An addendum to the main Getting Started guide for those using the `CMake
   build system <http://www.cmake.org>`_.

:doc:`Docker`
   A reference for using Dockerfiles provided with LLVM.

:doc:`Support Library <SupportLibrary>`
   This document describes the LLVM Support Library (``lib/Support``) and
   how to keep LLVM source code portable.

:doc:`AdvancedBuilds`
   This document describes more advanced build configurations.

Optimizations
-------------

:doc:`WritingAnLLVMNewPMPass`
   Information on how to write LLVM transformations under the new pass
   manager.

:doc:`WritingAnLLVMPass`
   Information on how to write LLVM transformations and analyses under the
   legacy pass manager.

:doc:`Passes`
   A list of optimizations and analyses implemented in LLVM.

:doc:`StackSafetyAnalysis`
  This document describes the design of the stack safety analysis of local
  variables.

:doc:`MergeFunctions`
  Describes functions merging optimization.

:doc:`AliasAnalysis`
   Information on how to write a new alias analysis implementation or how to
   use existing analyses.

:doc:`MemorySSA`
   Information about the MemorySSA utility in LLVM, as well as how to use it.

:doc:`LoopTerminology`
  A document describing Loops and associated terms as used in LLVM.

:doc:`CycleTerminology`
  A document describing cycles as a generalization of loops.

:doc:`Vectorizers`
   This document describes the current status of vectorization in LLVM.

:doc:`LinkTimeOptimization`
   This document describes the interface between LLVM intermodular optimizer
   and the linker and its design

:doc:`DTLTO`
   This document describes the DTLTO implementation, which allows for
   distributing ThinLTO backend compilations without requiring support from
   the build system.

:doc:`GoldPlugin`
   How to build your programs with link-time optimization on Linux.

:doc:`Remarks`
   A reference on the implementation of remarks in LLVM.

:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
   This document describes the design and philosophy behind the LLVM
   source-level debugger.

:doc:`How to Update Debug Info <HowToUpdateDebugInfo>`
   This document specifies how to correctly update debug info in various kinds
   of code transformations.

:doc:`InstrRefDebugInfo`
   This document explains how LLVM uses value tracking, or instruction
   referencing, to determine variable locations for debug info in the final
   stages of compilation.

:doc:`RemoveDIsDebugInfo`
   This is a migration guide describing how to move from debug info using
   intrinsics such as dbg.value to using the non-instruction DbgRecord object.

:doc:`KeyInstructionsDebugInfo`
   This document explains how the debug info feature Key Instructions is
   implemented in LLVM.

:doc:`InstrProfileFormat`
   This document explains two binary formats of instrumentation-based profiles.

:doc:`InstCombineContributorGuide`
   This document specifies guidelines for contributions for InstCombine and
   related passes.


Code Generation
---------------

:doc:`WritingAnLLVMBackend`
   Information on how to write LLVM backends for machine targets.

:doc:`CodeGenerator`
   The design and implementation of the LLVM code generator.  Useful if you are
   working on retargetting LLVM to a new architecture, designing a new codegen
   pass, or enhancing existing components.

:doc:`TableGen <TableGen/index>`
   Describes the TableGen tool, which is used heavily by the LLVM code
   generator.

==========
GlobalISel
==========

:doc:`MIRPatterns <GlobalISel/MIRPatterns>`
   Describes the design of MIR Patterns and how to use them.

===
JIT
===

:doc:`MCJITDesignAndImplementation`
   Describes the inner workings of MCJIT execution engine.

:doc:`ORCv2`
   Describes the design and implementation of the ORC APIs, including some
   usage examples, and a guide for users transitioning from ORCv1 to ORCv2.

:doc:`JITLink`
   Describes the design and APIs for the JITLink library, ORC's new JIT
   linker.

:doc:`DebuggingJITedCode`
   How to debug JITed code with GDB.

Additional Topics
-----------------

:doc:`CommandLine`
  Provides information on using the command line parsing library.

:doc:`ExtendingLLVM`
  Look here to see how to add instructions and intrinsics to LLVM.

:doc:`AddingConstrainedIntrinsics`
   Gives the steps necessary when adding a new constrained math intrinsic
   to LLVM.

:doc:`HowToBuildWindowsItaniumPrograms`
   Notes on assembling a Windows Itanium environment.

:doc:`HowToCrossCompileBuiltinsOnArm`
   Notes on cross-building and testing the compiler-rt builtins for Arm.

:doc:`BigEndianNEON`
  LLVM's support for generating NEON instructions on big endian ARM targets is
  somewhat nonintuitive. This document explains the implementation and rationale.

:doc:`AArch64SME`
  LLVM's support for AArch64 SME ACLE and ABI.

:doc:`CompileCudaWithLLVM`
  LLVM support for CUDA.

:doc:`NVPTXUsage`
   This document describes using the NVPTX backend to compile GPU kernels.

:doc:`AMDGPUUsage`
   This document describes using the AMDGPU backend to compile GPU kernels.

:doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`
   This document describes DWARF extensions to support heterogeneous debugging
   for targets such as the AMDGPU backend.

:doc:`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack`
   This document describes a DWARF extension to allow location descriptions on
   the DWARF expression stack. It is part of
   :doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`.

:doc:`SPIRVUsage`
   This document describes using the SPIR-V target to compile GPU kernels.

:doc:`DirectXUsage`
   This document describes using the DirectX target to compile GPU code for the
   DirectX runtime.

:doc:`RISCVUsage`
   This document describes using the RISC-V target.

:doc:`RISCV/RISCVVectorExtension`
   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.

:doc:`Sandbox IR <SandboxIR>`
   This document describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.

:doc:`Telemetry`
   This document describes the Telemetry framework in LLVM.