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