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   HowToBuildOnARM
69   HowToCrossCompileLLVM
70   CommandGuide/index
71   GettingStarted
72   GettingStartedVS
73   BuildingLLVMWithAutotools
74   FAQ
75   Lexicon
76   HowToAddABuilder
77   yaml2obj
78   HowToSubmitABug
79   SphinxQuickstartTemplate
80   Phabricator
81   TestingGuide
82   tutorial/index
83   ReleaseNotes
84   Passes
85   YamlIO
86   GetElementPtr
87   Frontend/PerformanceTips
88   MCJITDesignAndImplementation
89   CompileCudaWithLLVM
90
91:doc:`GettingStarted`
92   Discusses how to get up and running quickly with the LLVM infrastructure.
93   Everything from unpacking and compilation of the distribution to execution
94   of some tools.
95
96:doc:`CMake`
97   An addendum to the main Getting Started guide for those using the `CMake
98   build system <http://www.cmake.org>`_.
99
100:doc:`HowToBuildOnARM`
101   Notes on building and testing LLVM/Clang on ARM.
102
103:doc:`HowToCrossCompileLLVM`
104   Notes on cross-building and testing LLVM/Clang.
105
106:doc:`GettingStartedVS`
107   An addendum to the main Getting Started guide for those using Visual Studio
108   on Windows.
109
110:doc:`BuildingLLVMWithAutotools`
111   An addendum to the Getting Started guide with instructions for building LLVM
112   with the Autotools build system.
113
114:doc:`tutorial/index`
115   Tutorials about using LLVM. Includes a tutorial about making a custom
116   language with LLVM.
117
118:doc:`LLVM Command Guide <CommandGuide/index>`
119   A reference manual for the LLVM command line utilities ("man" pages for LLVM
120   tools).
121
122:doc:`Passes`
123   A list of optimizations and analyses implemented in LLVM.
124
125:doc:`FAQ`
126   A list of common questions and problems and their solutions.
127
128:doc:`Release notes for the current release <ReleaseNotes>`
129   This describes new features, known bugs, and other limitations.
130
131:doc:`HowToSubmitABug`
132   Instructions for properly submitting information about any bugs you run into
133   in the LLVM system.
134
135:doc:`SphinxQuickstartTemplate`
136  A template + tutorial for writing new Sphinx documentation. It is meant
137  to be read in source form.
138
139:doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
140   A reference manual for using the LLVM testing infrastructure.
141
142`How to build the C, C++, ObjC, and ObjC++ front end`__
143   Instructions for building the clang front-end from source.
144
145   .. __: http://clang.llvm.org/get_started.html
146
147:doc:`Lexicon`
148   Definition of acronyms, terms and concepts used in LLVM.
149
150:doc:`HowToAddABuilder`
151   Instructions for adding new builder to LLVM buildbot master.
152
153:doc:`YamlIO`
154   A reference guide for using LLVM's YAML I/O library.
155
156:doc:`GetElementPtr`
157  Answers to some very frequent questions about LLVM's most frequently
158  misunderstood instruction.
159
160:doc:`Frontend/PerformanceTips`
161   A collection of tips for frontend authors on how to generate IR
162   which LLVM is able to effectively optimize.
163
164
165Programming Documentation
166=========================
167
168For developers of applications which use LLVM as a library.
169
170.. toctree::
171   :hidden:
172
173   Atomics
174   CodingStandards
175   CommandLine
176   CompilerWriterInfo
177   ExtendingLLVM
178   HowToSetUpLLVMStyleRTTI
179   ProgrammersManual
180   Extensions
181   LibFuzzer
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
226Subsystem Documentation
227=======================
228
229For API clients and LLVM developers.
230
231.. toctree::
232   :hidden:
233
234   AliasAnalysis
235   BitCodeFormat
236   BlockFrequencyTerminology
237   BranchWeightMetadata
238   Bugpoint
239   CodeGenerator
240   ExceptionHandling
241   LinkTimeOptimization
242   SegmentedStacks
243   TableGenFundamentals
244   TableGen/index
245   DebuggingJITedCode
246   GoldPlugin
247   MarkedUpDisassembly
248   SystemLibrary
249   SourceLevelDebugging
250   Vectorizers
251   WritingAnLLVMBackend
252   GarbageCollection
253   WritingAnLLVMPass
254   HowToUseAttributes
255   NVPTXUsage
256   AMDGPUUsage
257   StackMaps
258   InAlloca
259   BigEndianNEON
260   CoverageMappingFormat
261   Statepoints
262   MergeFunctions
263   BitSets
264   FaultMaps
265   MIRLangRef
266
267:doc:`WritingAnLLVMPass`
268   Information on how to write LLVM transformations and analyses.
269
270:doc:`WritingAnLLVMBackend`
271   Information on how to write LLVM backends for machine targets.
272
273:doc:`CodeGenerator`
274   The design and implementation of the LLVM code generator.  Useful if you are
275   working on retargetting LLVM to a new architecture, designing a new codegen
276   pass, or enhancing existing components.
277
278:doc:`Machine IR (MIR) Format Reference Manual <MIRLangRef>`
279   A reference manual for the MIR serialization format, which is used to test
280   LLVM's code generation passes.
281
282:doc:`TableGen <TableGen/index>`
283   Describes the TableGen tool, which is used heavily by the LLVM code
284   generator.
285
286:doc:`AliasAnalysis`
287   Information on how to write a new alias analysis implementation or how to
288   use existing analyses.
289
290:doc:`GarbageCollection`
291   The interfaces source-language compilers should use for compiling GC'd
292   programs.
293
294:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
295   This document describes the design and philosophy behind the LLVM
296   source-level debugger.
297
298:doc:`Vectorizers`
299   This document describes the current status of vectorization in LLVM.
300
301:doc:`ExceptionHandling`
302   This document describes the design and implementation of exception handling
303   in LLVM.
304
305:doc:`Bugpoint`
306   Automatic bug finder and test-case reducer description and usage
307   information.
308
309:doc:`BitCodeFormat`
310   This describes the file format and encoding used for LLVM "bc" files.
311
312:doc:`System Library <SystemLibrary>`
313   This document describes the LLVM System Library (``lib/System``) and
314   how to keep LLVM source code portable
315
316:doc:`LinkTimeOptimization`
317   This document describes the interface between LLVM intermodular optimizer
318   and the linker and its design
319
320:doc:`GoldPlugin`
321   How to build your programs with link-time optimization on Linux.
322
323:doc:`DebuggingJITedCode`
324   How to debug JITed code with GDB.
325
326:doc:`MCJITDesignAndImplementation`
327   Describes the inner workings of MCJIT execution engine.
328
329:doc:`BranchWeightMetadata`
330   Provides information about Branch Prediction Information.
331
332:doc:`BlockFrequencyTerminology`
333   Provides information about terminology used in the ``BlockFrequencyInfo``
334   analysis pass.
335
336:doc:`SegmentedStacks`
337   This document describes segmented stacks and how they are used in LLVM.
338
339:doc:`MarkedUpDisassembly`
340   This document describes the optional rich disassembly output syntax.
341
342:doc:`HowToUseAttributes`
343  Answers some questions about the new Attributes infrastructure.
344
345:doc:`NVPTXUsage`
346   This document describes using the NVPTX back-end to compile GPU kernels.
347
348:doc:`AMDGPUUsage`
349   This document describes how to use the AMDGPU back-end.
350
351:doc:`StackMaps`
352  LLVM support for mapping instruction addresses to the location of
353  values and allowing code to be patched.
354
355:doc:`BigEndianNEON`
356  LLVM's support for generating NEON instructions on big endian ARM targets is
357  somewhat nonintuitive. This document explains the implementation and rationale.
358
359:doc:`CoverageMappingFormat`
360  This describes the format and encoding used for LLVM’s code coverage mapping.
361
362:doc:`Statepoints`
363  This describes a set of experimental extensions for garbage
364  collection support.
365
366:doc:`MergeFunctions`
367  Describes functions merging optimization.
368
369:doc:`InAlloca`
370  Description of the ``inalloca`` argument attribute.
371
372:doc:`FaultMaps`
373  LLVM support for folding control flow into faulting machine instructions.
374
375:doc:`CompileCudaWithLLVM`
376  LLVM support for CUDA.
377
378Development Process Documentation
379=================================
380
381Information about LLVM's development process.
382
383.. toctree::
384   :hidden:
385
386   DeveloperPolicy
387   MakefileGuide
388   Projects
389   LLVMBuild
390   HowToReleaseLLVM
391   Packaging
392   ReleaseProcess
393   Phabricator
394
395:doc:`DeveloperPolicy`
396   The LLVM project's policy towards developers and their contributions.
397
398:doc:`Projects`
399  How-to guide and templates for new projects that *use* the LLVM
400  infrastructure.  The templates (directory organization, Makefiles, and test
401  tree) allow the project code to be located outside (or inside) the ``llvm/``
402  tree, while using LLVM header files and libraries.
403
404:doc:`LLVMBuild`
405  Describes the LLVMBuild organization and files used by LLVM to specify
406  component descriptions.
407
408:doc:`MakefileGuide`
409  Describes how the LLVM makefiles work and how to use them.
410
411:doc:`HowToReleaseLLVM`
412  This is a guide to preparing LLVM releases. Most developers can ignore it.
413
414:doc:`ReleaseProcess`
415  This is a guide to validate a new release, during the release process. Most developers can ignore it.
416
417:doc:`Packaging`
418   Advice on packaging LLVM into a distribution.
419
420:doc:`Phabricator`
421   Describes how to use the Phabricator code review tool hosted on
422   http://reviews.llvm.org/ and its command line interface, Arcanist.
423
424Community
425=========
426
427LLVM has a thriving community of friendly and helpful developers.
428The two primary communication mechanisms in the LLVM community are mailing
429lists and IRC.
430
431Mailing Lists
432-------------
433
434If you can't find what you need in these docs, try consulting the mailing
435lists.
436
437`Developer's List (llvm-dev)`__
438  This list is for people who want to be included in technical discussions of
439  LLVM. People post to this list when they have questions about writing code
440  for or using the LLVM tools. It is relatively low volume.
441
442  .. __: http://lists.llvm.org/mailman/listinfo/llvm-dev
443
444`Commits Archive (llvm-commits)`__
445  This list contains all commit messages that are made when LLVM developers
446  commit code changes to the repository. It also serves as a forum for
447  patch review (i.e. send patches here). It is useful for those who want to
448  stay on the bleeding edge of LLVM development. This list is very high
449  volume.
450
451  .. __: http://lists.llvm.org/pipermail/llvm-commits/
452
453`Bugs & Patches Archive (llvm-bugs)`__
454  This list gets emailed every time a bug is opened and closed. It is
455  higher volume than the LLVM-dev list.
456
457  .. __: http://lists.llvm.org/pipermail/llvm-bugs/
458
459`Test Results Archive (llvm-testresults)`__
460  A message is automatically sent to this list by every active nightly tester
461  when it completes.  As such, this list gets email several times each day,
462  making it a high volume list.
463
464  .. __: http://lists.llvm.org/pipermail/llvm-testresults/
465
466`LLVM Announcements List (llvm-announce)`__
467  This is a low volume list that provides important announcements regarding
468  LLVM.  It gets email about once a month.
469
470  .. __: http://lists.llvm.org/mailman/listinfo/llvm-announce
471
472IRC
473---
474
475Users and developers of the LLVM project (including subprojects such as Clang)
476can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
477
478This channel has several bots.
479
480* Buildbot reporters
481
482  * llvmbb - Bot for the main LLVM buildbot master.
483    http://lab.llvm.org:8011/console
484  * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
485  * smooshlab - Apple's internal buildbot master.
486
487* robot - Bugzilla linker. %bug <number>
488
489* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
490  near-trunk clang instead of gcc.
491
492
493Indices and tables
494==================
495
496* :ref:`genindex`
497* :ref:`search`
498