1Overview
2========
3
4.. warning::
5
6   If you are using a released version of LLVM, see `the download page
7   <http://llvm.org/releases/>`_ to find your documentation.
8
9The LLVM compiler infrastructure supports a wide range of projects, from
10industrial strength compilers to specialized JIT applications to small
11research projects.
12
13Similarly, documentation is broken down into several high-level groupings
14targeted at different audiences:
15
16LLVM Design & Overview
17======================
18
19Several introductory papers and presentations.
20
21.. toctree::
22   :hidden:
23
24   LangRef
25
26:doc:`LangRef`
27  Defines the LLVM intermediate representation.
28
29`Introduction to the LLVM Compiler`__
30  Presentation providing a users introduction to LLVM.
31
32  .. __: http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html
33
34`Intro to LLVM`__
35  Book chapter providing a compiler hacker's introduction to LLVM.
36
37  .. __: http://www.aosabook.org/en/llvm.html
38
39
40`LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation`__
41  Design overview.
42
43  .. __: http://llvm.org/pubs/2004-01-30-CGO-LLVM.html
44
45`LLVM: An Infrastructure for Multi-Stage Optimization`__
46  More details (quite old now).
47
48  .. __: http://llvm.org/pubs/2002-12-LattnerMSThesis.html
49
50`Publications mentioning LLVM <http://llvm.org/pubs>`_
51   ..
52
53User Guides
54===========
55
56For those new to the LLVM system.
57
58NOTE: If you are a user who is only interested in using LLVM-based
59compilers, you should look into `Clang <http://clang.llvm.org>`_ or
60`DragonEgg <http://dragonegg.llvm.org>`_ instead. The documentation here is
61intended for users who have a need to work with the intermediate LLVM
62representation.
63
64.. toctree::
65   :hidden:
66
67   CMake
68   CMakePrimer
69   AdvancedBuilds
70   HowToBuildOnARM
71   HowToCrossCompileLLVM
72   CommandGuide/index
73   GettingStarted
74   GettingStartedVS
75   FAQ
76   Lexicon
77   HowToAddABuilder
78   yaml2obj
79   HowToSubmitABug
80   SphinxQuickstartTemplate
81   Phabricator
82   TestingGuide
83   tutorial/index
84   ReleaseNotes
85   Passes
86   YamlIO
87   GetElementPtr
88   Frontend/PerformanceTips
89   MCJITDesignAndImplementation
90   CodeOfConduct
91   CompileCudaWithLLVM
92   ReportingGuide
93
94:doc:`GettingStarted`
95   Discusses how to get up and running quickly with the LLVM infrastructure.
96   Everything from unpacking and compilation of the distribution to execution
97   of some tools.
98
99:doc:`CMake`
100   An addendum to the main Getting Started guide for those using the `CMake
101   build system <http://www.cmake.org>`_.
102
103:doc:`HowToBuildOnARM`
104   Notes on building and testing LLVM/Clang on ARM.
105
106:doc:`HowToCrossCompileLLVM`
107   Notes on cross-building and testing LLVM/Clang.
108
109:doc:`GettingStartedVS`
110   An addendum to the main Getting Started guide for those using Visual Studio
111   on Windows.
112
113:doc:`tutorial/index`
114   Tutorials about using LLVM. Includes a tutorial about making a custom
115   language with LLVM.
116
117:doc:`LLVM Command Guide <CommandGuide/index>`
118   A reference manual for the LLVM command line utilities ("man" pages for LLVM
119   tools).
120
121:doc:`Passes`
122   A list of optimizations and analyses implemented in LLVM.
123
124:doc:`FAQ`
125   A list of common questions and problems and their solutions.
126
127:doc:`Release notes for the current release <ReleaseNotes>`
128   This describes new features, known bugs, and other limitations.
129
130:doc:`HowToSubmitABug`
131   Instructions for properly submitting information about any bugs you run into
132   in the LLVM system.
133
134:doc:`SphinxQuickstartTemplate`
135  A template + tutorial for writing new Sphinx documentation. It is meant
136  to be read in source form.
137
138:doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
139   A reference manual for using the LLVM testing infrastructure.
140
141`How to build the C, C++, ObjC, and ObjC++ front end`__
142   Instructions for building the clang front-end from source.
143
144   .. __: http://clang.llvm.org/get_started.html
145
146:doc:`Lexicon`
147   Definition of acronyms, terms and concepts used in LLVM.
148
149:doc:`HowToAddABuilder`
150   Instructions for adding new builder to LLVM buildbot master.
151
152:doc:`YamlIO`
153   A reference guide for using LLVM's YAML I/O library.
154
155:doc:`GetElementPtr`
156  Answers to some very frequent questions about LLVM's most frequently
157  misunderstood instruction.
158
159:doc:`Frontend/PerformanceTips`
160   A collection of tips for frontend authors on how to generate IR
161   which LLVM is able to effectively optimize.
162
163
164Programming Documentation
165=========================
166
167For developers of applications which use LLVM as a library.
168
169.. toctree::
170   :hidden:
171
172   Atomics
173   CodingStandards
174   CommandLine
175   CompilerWriterInfo
176   ExtendingLLVM
177   HowToSetUpLLVMStyleRTTI
178   ProgrammersManual
179   Extensions
180   LibFuzzer
181   ScudoHardenedAllocator
182
183:doc:`LLVM Language Reference Manual <LangRef>`
184  Defines the LLVM intermediate representation and the assembly form of the
185  different nodes.
186
187:doc:`Atomics`
188  Information about LLVM's concurrency model.
189
190:doc:`ProgrammersManual`
191  Introduction to the general layout of the LLVM sourcebase, important classes
192  and APIs, and some tips & tricks.
193
194:doc:`Extensions`
195  LLVM-specific extensions to tools and formats LLVM seeks compatibility with.
196
197:doc:`CommandLine`
198  Provides information on using the command line parsing library.
199
200:doc:`CodingStandards`
201  Details the LLVM coding standards and provides useful information on writing
202  efficient C++ code.
203
204:doc:`HowToSetUpLLVMStyleRTTI`
205  How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
206  class hierarchy.
207
208:doc:`ExtendingLLVM`
209  Look here to see how to add instructions and intrinsics to LLVM.
210
211`Doxygen generated documentation <http://llvm.org/doxygen/>`_
212  (`classes <http://llvm.org/doxygen/inherits.html>`_)
213  (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
214
215`Documentation for Go bindings <http://godoc.org/llvm.org/llvm/bindings/go/llvm>`_
216
217`ViewVC Repository Browser <http://llvm.org/viewvc/>`_
218   ..
219
220:doc:`CompilerWriterInfo`
221  A list of helpful links for compiler writers.
222
223:doc:`LibFuzzer`
224  A library for writing in-process guided fuzzers.
225
226:doc:`ScudoHardenedAllocator`
227  A library that implements a security-hardened `malloc()`.
228
229Subsystem Documentation
230=======================
231
232For API clients and LLVM developers.
233
234.. toctree::
235   :hidden:
236
237   AliasAnalysis
238   BitCodeFormat
239   BlockFrequencyTerminology
240   BranchWeightMetadata
241   Bugpoint
242   CodeGenerator
243   ExceptionHandling
244   LinkTimeOptimization
245   SegmentedStacks
246   TableGenFundamentals
247   TableGen/index
248   DebuggingJITedCode
249   GoldPlugin
250   MarkedUpDisassembly
251   SystemLibrary
252   SourceLevelDebugging
253   Vectorizers
254   WritingAnLLVMBackend
255   GarbageCollection
256   WritingAnLLVMPass
257   HowToUseAttributes
258   NVPTXUsage
259   AMDGPUUsage
260   StackMaps
261   InAlloca
262   BigEndianNEON
263   CoverageMappingFormat
264   Statepoints
265   MergeFunctions
266   TypeMetadata
267   FaultMaps
268   MIRLangRef
269
270:doc:`WritingAnLLVMPass`
271   Information on how to write LLVM transformations and analyses.
272
273:doc:`WritingAnLLVMBackend`
274   Information on how to write LLVM backends for machine targets.
275
276:doc:`CodeGenerator`
277   The design and implementation of the LLVM code generator.  Useful if you are
278   working on retargetting LLVM to a new architecture, designing a new codegen
279   pass, or enhancing existing components.
280
281:doc:`Machine IR (MIR) Format Reference Manual <MIRLangRef>`
282   A reference manual for the MIR serialization format, which is used to test
283   LLVM's code generation passes.
284
285:doc:`TableGen <TableGen/index>`
286   Describes the TableGen tool, which is used heavily by the LLVM code
287   generator.
288
289:doc:`AliasAnalysis`
290   Information on how to write a new alias analysis implementation or how to
291   use existing analyses.
292
293:doc:`GarbageCollection`
294   The interfaces source-language compilers should use for compiling GC'd
295   programs.
296
297:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
298   This document describes the design and philosophy behind the LLVM
299   source-level debugger.
300
301:doc:`Vectorizers`
302   This document describes the current status of vectorization in LLVM.
303
304:doc:`ExceptionHandling`
305   This document describes the design and implementation of exception handling
306   in LLVM.
307
308:doc:`Bugpoint`
309   Automatic bug finder and test-case reducer description and usage
310   information.
311
312:doc:`BitCodeFormat`
313   This describes the file format and encoding used for LLVM "bc" files.
314
315:doc:`System Library <SystemLibrary>`
316   This document describes the LLVM System Library (``lib/System``) and
317   how to keep LLVM source code portable
318
319:doc:`LinkTimeOptimization`
320   This document describes the interface between LLVM intermodular optimizer
321   and the linker and its design
322
323:doc:`GoldPlugin`
324   How to build your programs with link-time optimization on Linux.
325
326:doc:`DebuggingJITedCode`
327   How to debug JITed code with GDB.
328
329:doc:`MCJITDesignAndImplementation`
330   Describes the inner workings of MCJIT execution engine.
331
332:doc:`BranchWeightMetadata`
333   Provides information about Branch Prediction Information.
334
335:doc:`BlockFrequencyTerminology`
336   Provides information about terminology used in the ``BlockFrequencyInfo``
337   analysis pass.
338
339:doc:`SegmentedStacks`
340   This document describes segmented stacks and how they are used in LLVM.
341
342:doc:`MarkedUpDisassembly`
343   This document describes the optional rich disassembly output syntax.
344
345:doc:`HowToUseAttributes`
346  Answers some questions about the new Attributes infrastructure.
347
348:doc:`NVPTXUsage`
349   This document describes using the NVPTX back-end to compile GPU kernels.
350
351:doc:`AMDGPUUsage`
352   This document describes how to use the AMDGPU back-end.
353
354:doc:`StackMaps`
355  LLVM support for mapping instruction addresses to the location of
356  values and allowing code to be patched.
357
358:doc:`BigEndianNEON`
359  LLVM's support for generating NEON instructions on big endian ARM targets is
360  somewhat nonintuitive. This document explains the implementation and rationale.
361
362:doc:`CoverageMappingFormat`
363  This describes the format and encoding used for LLVM’s code coverage mapping.
364
365:doc:`Statepoints`
366  This describes a set of experimental extensions for garbage
367  collection support.
368
369:doc:`MergeFunctions`
370  Describes functions merging optimization.
371
372:doc:`InAlloca`
373  Description of the ``inalloca`` argument attribute.
374
375:doc:`FaultMaps`
376  LLVM support for folding control flow into faulting machine instructions.
377
378:doc:`CompileCudaWithLLVM`
379  LLVM support for CUDA.
380
381Development Process Documentation
382=================================
383
384Information about LLVM's development process.
385
386.. toctree::
387   :hidden:
388
389   DeveloperPolicy
390   Projects
391   LLVMBuild
392   HowToReleaseLLVM
393   Packaging
394   ReleaseProcess
395   Phabricator
396
397:doc:`DeveloperPolicy`
398   The LLVM project's policy towards developers and their contributions.
399
400:doc:`Projects`
401  How-to guide and templates for new projects that *use* the LLVM
402  infrastructure.  The templates (directory organization, Makefiles, and test
403  tree) allow the project code to be located outside (or inside) the ``llvm/``
404  tree, while using LLVM header files and libraries.
405
406:doc:`LLVMBuild`
407  Describes the LLVMBuild organization and files used by LLVM to specify
408  component descriptions.
409
410:doc:`HowToReleaseLLVM`
411  This is a guide to preparing LLVM releases. Most developers can ignore it.
412
413:doc:`ReleaseProcess`
414  This is a guide to validate a new release, during the release process. Most developers can ignore it.
415
416:doc:`Packaging`
417   Advice on packaging LLVM into a distribution.
418
419:doc:`Phabricator`
420   Describes how to use the Phabricator code review tool hosted on
421   http://reviews.llvm.org/ and its command line interface, Arcanist.
422
423Community
424=========
425
426LLVM has a thriving community of friendly and helpful developers.
427The two primary communication mechanisms in the LLVM community are mailing
428lists and IRC.
429
430Mailing Lists
431-------------
432
433If you can't find what you need in these docs, try consulting the mailing
434lists.
435
436`Developer's List (llvm-dev)`__
437  This list is for people who want to be included in technical discussions of
438  LLVM. People post to this list when they have questions about writing code
439  for or using the LLVM tools. It is relatively low volume.
440
441  .. __: http://lists.llvm.org/mailman/listinfo/llvm-dev
442
443`Commits Archive (llvm-commits)`__
444  This list contains all commit messages that are made when LLVM developers
445  commit code changes to the repository. It also serves as a forum for
446  patch review (i.e. send patches here). It is useful for those who want to
447  stay on the bleeding edge of LLVM development. This list is very high
448  volume.
449
450  .. __: http://lists.llvm.org/pipermail/llvm-commits/
451
452`Bugs & Patches Archive (llvm-bugs)`__
453  This list gets emailed every time a bug is opened and closed. It is
454  higher volume than the LLVM-dev list.
455
456  .. __: http://lists.llvm.org/pipermail/llvm-bugs/
457
458`Test Results Archive (llvm-testresults)`__
459  A message is automatically sent to this list by every active nightly tester
460  when it completes.  As such, this list gets email several times each day,
461  making it a high volume list.
462
463  .. __: http://lists.llvm.org/pipermail/llvm-testresults/
464
465`LLVM Announcements List (llvm-announce)`__
466  This is a low volume list that provides important announcements regarding
467  LLVM.  It gets email about once a month.
468
469  .. __: http://lists.llvm.org/mailman/listinfo/llvm-announce
470
471IRC
472---
473
474Users and developers of the LLVM project (including subprojects such as Clang)
475can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
476
477This channel has several bots.
478
479* Buildbot reporters
480
481  * llvmbb - Bot for the main LLVM buildbot master.
482    http://lab.llvm.org:8011/console
483  * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
484  * smooshlab - Apple's internal buildbot master.
485
486* robot - Bugzilla linker. %bug <number>
487
488* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
489  near-trunk clang instead of gcc.
490
491
492Indices and tables
493==================
494
495* :ref:`genindex`
496* :ref:`search`
497