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