blob: 9c5c11af57515a1e31e487e222e812cc4c61ca87 [file] [log] [blame]
Daniel Dunbarfbb80412012-04-19 16:31:37 +00001Overview
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
Benjamin Kramerbde91762012-06-02 10:20:22 +000014targeted at different audiences:
Daniel Dunbarfbb80412012-04-19 16:31:37 +000015
Sean Silva12159ff2013-01-20 02:19:36 +000016LLVM Design & Overview
17======================
Daniel Dunbarfbb80412012-04-19 16:31:37 +000018
Sean Silva12159ff2013-01-20 02:19:36 +000019Several introductory papers and presentations.
Daniel Dunbarfbb80412012-04-19 16:31:37 +000020
21.. toctree::
Sean Silva12159ff2013-01-20 02:19:36 +000022 :hidden:
Daniel Dunbarfbb80412012-04-19 16:31:37 +000023
Sean Silva12159ff2013-01-20 02:19:36 +000024 LangRef
25 GetElementPtr
26
Sean Silva9d0eb942013-01-20 02:19:42 +000027:doc:`LangRef`
Sean Silva12159ff2013-01-20 02:19:36 +000028 Defines the LLVM intermediate representation.
29
Sean Silva9d0eb942013-01-20 02:19:42 +000030`Introduction to the LLVM Compiler`__
Sean Silva12159ff2013-01-20 02:19:36 +000031 Presentation providing a users introduction to LLVM.
32
Sean Silva9d0eb942013-01-20 02:19:42 +000033 .. __: http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html
Sean Silva12159ff2013-01-20 02:19:36 +000034
Sean Silva9d0eb942013-01-20 02:19:42 +000035`Intro to LLVM`__
Sean Silva12159ff2013-01-20 02:19:36 +000036 Book chapter providing a compiler hacker's introduction to LLVM.
37
Sean Silva9d0eb942013-01-20 02:19:42 +000038 .. __: http://www.aosabook.org/en/llvm.html
Sean Silva12159ff2013-01-20 02:19:36 +000039
Sean Silva9d0eb942013-01-20 02:19:42 +000040
41`LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation`__
Sean Silva12159ff2013-01-20 02:19:36 +000042 Design overview.
43
Sean Silva9d0eb942013-01-20 02:19:42 +000044 .. __: http://llvm.org/pubs/2004-01-30-CGO-LLVM.html
Sean Silva12159ff2013-01-20 02:19:36 +000045
Sean Silva9d0eb942013-01-20 02:19:42 +000046`LLVM: An Infrastructure for Multi-Stage Optimization`__
Sean Silva12159ff2013-01-20 02:19:36 +000047 More details (quite old now).
48
Sean Silva9d0eb942013-01-20 02:19:42 +000049 .. __: http://llvm.org/pubs/2002-12-LattnerMSThesis.html
Sean Silva12159ff2013-01-20 02:19:36 +000050
Sean Silva9d0eb942013-01-20 02:19:42 +000051:doc:`GetElementPtr`
Sean Silva12159ff2013-01-20 02:19:36 +000052 Answers to some very frequent questions about LLVM's most frequently
53 misunderstood instruction.
54
Sean Silva9d0eb942013-01-20 02:19:42 +000055`Publications mentioning LLVM <http://llvm.org/pubs>`_
56 ..
Sean Silva12159ff2013-01-20 02:19:36 +000057
58User Guides
59===========
60
61For those new to the LLVM system.
62
63NOTE: If you are a user who is only interested in using LLVM-based
64compilers, you should look into `Clang <http://clang.llvm.org>`_ or
65`DragonEgg <http://dragonegg.llvm.org>`_ instead. The documentation here is
66intended for users who have a need to work with the intermediate LLVM
67representation.
68
69.. toctree::
70 :hidden:
71
72 CMake
73 HowToBuildOnARM
74 CommandGuide/index
Sean Silva12159ff2013-01-20 02:19:36 +000075 GettingStarted
76 GettingStartedVS
77 FAQ
78 Lexicon
Sean Silva12159ff2013-01-20 02:19:36 +000079 HowToAddABuilder
80 yaml2obj
81 HowToSubmitABug
82 SphinxQuickstartTemplate
83 Phabricator
84 TestingGuide
85 tutorial/index
86 ReleaseNotes
87 Passes
88 YamlIO
89
Sean Silva9d0eb942013-01-20 02:19:42 +000090:doc:`GettingStarted`
Sean Silva12159ff2013-01-20 02:19:36 +000091 Discusses how to get up and running quickly with the LLVM infrastructure.
92 Everything from unpacking and compilation of the distribution to execution
93 of some tools.
94
Sean Silva9d0eb942013-01-20 02:19:42 +000095:doc:`CMake`
Sean Silva12159ff2013-01-20 02:19:36 +000096 An addendum to the main Getting Started guide for those using the `CMake
97 build system <http://www.cmake.org>`_.
98
Sean Silva9d0eb942013-01-20 02:19:42 +000099:doc:`HowToBuildOnARM`
Sean Silva12159ff2013-01-20 02:19:36 +0000100 Notes on building and testing LLVM/Clang on ARM.
101
Sean Silva9d0eb942013-01-20 02:19:42 +0000102:doc:`GettingStartedVS`
Sean Silva12159ff2013-01-20 02:19:36 +0000103 An addendum to the main Getting Started guide for those using Visual Studio
104 on Windows.
105
Sean Silva9d0eb942013-01-20 02:19:42 +0000106:doc:`tutorial/index`
Sean Silva12159ff2013-01-20 02:19:36 +0000107 Tutorials about using LLVM. Includes a tutorial about making a custom
108 language with LLVM.
109
Sean Silva9d0eb942013-01-20 02:19:42 +0000110:doc:`LLVM Command Guide <CommandGuide/index>`
Sean Silva12159ff2013-01-20 02:19:36 +0000111 A reference manual for the LLVM command line utilities ("man" pages for LLVM
112 tools).
113
Sean Silva9d0eb942013-01-20 02:19:42 +0000114:doc:`Passes`
Sean Silva12159ff2013-01-20 02:19:36 +0000115 A list of optimizations and analyses implemented in LLVM.
116
Sean Silva9d0eb942013-01-20 02:19:42 +0000117:doc:`FAQ`
Sean Silva12159ff2013-01-20 02:19:36 +0000118 A list of common questions and problems and their solutions.
119
Sean Silva9d0eb942013-01-20 02:19:42 +0000120:doc:`Release notes for the current release <ReleaseNotes>`
Sean Silva12159ff2013-01-20 02:19:36 +0000121 This describes new features, known bugs, and other limitations.
122
Sean Silva9d0eb942013-01-20 02:19:42 +0000123:doc:`HowToSubmitABug`
Sean Silva12159ff2013-01-20 02:19:36 +0000124 Instructions for properly submitting information about any bugs you run into
125 in the LLVM system.
Sean Silva12159ff2013-01-20 02:19:36 +0000126
Sean Silva9d0eb942013-01-20 02:19:42 +0000127:doc:`SphinxQuickstartTemplate`
Sean Silva12159ff2013-01-20 02:19:36 +0000128 A template + tutorial for writing new Sphinx documentation. It is meant
129 to be read in source form.
130
Sean Silva9d0eb942013-01-20 02:19:42 +0000131:doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
Sean Silva12159ff2013-01-20 02:19:36 +0000132 A reference manual for using the LLVM testing infrastructure.
133
Sean Silva9d0eb942013-01-20 02:19:42 +0000134`How to build the C, C++, ObjC, and ObjC++ front end`__
Sean Silva12159ff2013-01-20 02:19:36 +0000135 Instructions for building the clang front-end from source.
136
Sean Silva9d0eb942013-01-20 02:19:42 +0000137 .. __: http://clang.llvm.org/get_started.html
Sean Silva12159ff2013-01-20 02:19:36 +0000138
Sean Silva9d0eb942013-01-20 02:19:42 +0000139:doc:`Lexicon`
Sean Silva12159ff2013-01-20 02:19:36 +0000140 Definition of acronyms, terms and concepts used in LLVM.
141
Sean Silva9d0eb942013-01-20 02:19:42 +0000142:doc:`HowToAddABuilder`
Sean Silva12159ff2013-01-20 02:19:36 +0000143 Instructions for adding new builder to LLVM buildbot master.
144
Sean Silva9d0eb942013-01-20 02:19:42 +0000145:doc:`YamlIO`
Sean Silva12159ff2013-01-20 02:19:36 +0000146 A reference guide for using LLVM's YAML I/O library.
147
148IRC
149===
150
Michael J. Spencer0ad0f5e2013-01-20 09:38:14 +0000151Users and developers of the LLVM project (including subprojects such as Clang)
152can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
Sean Silva12159ff2013-01-20 02:19:36 +0000153
Michael J. Spencer0ad0f5e2013-01-20 09:38:14 +0000154This channel has several bots.
155
156* Buildbot reporters
157
158 * llvmbb - Bot for the main LLVM buildbot master.
159 http://lab.llvm.org:8011/console
160 * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
161 * smooshlab - Apple's internal buildbot master.
162
163* robot - Bugzilla linker. %bug <number>
164
165* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
166 near-trunk clang instead of gcc.
Sean Silva12159ff2013-01-20 02:19:36 +0000167
168Programming Documentation
169=========================
170
171For developers of applications which use LLVM as a library.
172
173.. toctree::
174 :hidden:
175
176 Atomics
177 CodingStandards
178 CommandLine
179 CompilerWriterInfo
180 ExtendingLLVM
181 HowToSetUpLLVMStyleRTTI
182 ProgrammersManual
183
Sean Silva9d0eb942013-01-20 02:19:42 +0000184:doc:`LLVM Language Reference Manual <LangRef>`
Sean Silva12159ff2013-01-20 02:19:36 +0000185 Defines the LLVM intermediate representation and the assembly form of the
186 different nodes.
187
Sean Silva9d0eb942013-01-20 02:19:42 +0000188:doc:`Atomics`
Sean Silva12159ff2013-01-20 02:19:36 +0000189 Information about LLVM's concurrency model.
190
Sean Silva9d0eb942013-01-20 02:19:42 +0000191:doc:`ProgrammersManual`
Sean Silva12159ff2013-01-20 02:19:36 +0000192 Introduction to the general layout of the LLVM sourcebase, important classes
193 and APIs, and some tips & tricks.
194
Sean Silva9d0eb942013-01-20 02:19:42 +0000195:doc:`CommandLine`
Sean Silva12159ff2013-01-20 02:19:36 +0000196 Provides information on using the command line parsing library.
197
Sean Silva9d0eb942013-01-20 02:19:42 +0000198:doc:`CodingStandards`
Sean Silva12159ff2013-01-20 02:19:36 +0000199 Details the LLVM coding standards and provides useful information on writing
200 efficient C++ code.
201
Sean Silva9d0eb942013-01-20 02:19:42 +0000202:doc:`HowToSetUpLLVMStyleRTTI`
Sean Silva12159ff2013-01-20 02:19:36 +0000203 How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
204 class hierarchy.
205
Sean Silva9d0eb942013-01-20 02:19:42 +0000206:doc:`ExtendingLLVM`
Sean Silva12159ff2013-01-20 02:19:36 +0000207 Look here to see how to add instructions and intrinsics to LLVM.
208
Sean Silva9d0eb942013-01-20 02:19:42 +0000209`Doxygen generated documentation <http://llvm.org/doxygen/>`_
Sean Silva12159ff2013-01-20 02:19:36 +0000210 (`classes <http://llvm.org/doxygen/inherits.html>`_)
211 (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
212
Sean Silva9d0eb942013-01-20 02:19:42 +0000213`ViewVC Repository Browser <http://llvm.org/viewvc/>`_
214 ..
Sean Silva12159ff2013-01-20 02:19:36 +0000215
Sean Silva9d0eb942013-01-20 02:19:42 +0000216:doc:`CompilerWriterInfo`
Sean Silva12159ff2013-01-20 02:19:36 +0000217 A list of helpful links for compiler writers.
218
219Subsystem Documentation
220=======================
221
222For API clients and LLVM developers.
223
224.. toctree::
225 :hidden:
226
227 AliasAnalysis
228 BitCodeFormat
229 BranchWeightMetadata
230 Bugpoint
231 CodeGenerator
232 ExceptionHandling
233 LinkTimeOptimization
234 SegmentedStacks
235 TableGenFundamentals
236 DebuggingJITedCode
237 GoldPlugin
238 MarkedUpDisassembly
239 SystemLibrary
240 SourceLevelDebugging
241 Vectorizers
242 WritingAnLLVMBackend
243 GarbageCollection
244 WritingAnLLVMPass
245 TableGen/LangRef
Joe Abbeyba3e9012013-02-12 11:45:22 +0000246 HowToUseAttributes
Sean Silva12159ff2013-01-20 02:19:36 +0000247
Sean Silva9d0eb942013-01-20 02:19:42 +0000248:doc:`WritingAnLLVMPass`
Sean Silva12159ff2013-01-20 02:19:36 +0000249 Information on how to write LLVM transformations and analyses.
250
Sean Silva9d0eb942013-01-20 02:19:42 +0000251:doc:`WritingAnLLVMBackend`
Sean Silva12159ff2013-01-20 02:19:36 +0000252 Information on how to write LLVM backends for machine targets.
253
Sean Silva9d0eb942013-01-20 02:19:42 +0000254:doc:`CodeGenerator`
Sean Silva12159ff2013-01-20 02:19:36 +0000255 The design and implementation of the LLVM code generator. Useful if you are
256 working on retargetting LLVM to a new architecture, designing a new codegen
257 pass, or enhancing existing components.
258
Sean Silva9d0eb942013-01-20 02:19:42 +0000259:doc:`TableGenFundamentals`
Sean Silva12159ff2013-01-20 02:19:36 +0000260 Describes the TableGen tool, which is used heavily by the LLVM code
261 generator.
262
Sean Silva9d0eb942013-01-20 02:19:42 +0000263:doc:`AliasAnalysis`
Sean Silva12159ff2013-01-20 02:19:36 +0000264 Information on how to write a new alias analysis implementation or how to
265 use existing analyses.
266
Sean Silva9d0eb942013-01-20 02:19:42 +0000267:doc:`GarbageCollection`
Sean Silva12159ff2013-01-20 02:19:36 +0000268 The interfaces source-language compilers should use for compiling GC'd
269 programs.
270
Sean Silva9d0eb942013-01-20 02:19:42 +0000271:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
Sean Silva12159ff2013-01-20 02:19:36 +0000272 This document describes the design and philosophy behind the LLVM
273 source-level debugger.
274
Sean Silva9d0eb942013-01-20 02:19:42 +0000275:doc:`Vectorizers`
Sean Silva12159ff2013-01-20 02:19:36 +0000276 This document describes the current status of vectorization in LLVM.
277
Sean Silva9d0eb942013-01-20 02:19:42 +0000278:doc:`ExceptionHandling`
Sean Silva12159ff2013-01-20 02:19:36 +0000279 This document describes the design and implementation of exception handling
280 in LLVM.
281
Sean Silva9d0eb942013-01-20 02:19:42 +0000282:doc:`Bugpoint`
Sean Silva12159ff2013-01-20 02:19:36 +0000283 Automatic bug finder and test-case reducer description and usage
284 information.
285
Sean Silva9d0eb942013-01-20 02:19:42 +0000286:doc:`BitCodeFormat`
Sean Silva12159ff2013-01-20 02:19:36 +0000287 This describes the file format and encoding used for LLVM "bc" files.
288
Sean Silva9d0eb942013-01-20 02:19:42 +0000289:doc:`System Library <SystemLibrary>`
Sean Silva12159ff2013-01-20 02:19:36 +0000290 This document describes the LLVM System Library (``lib/System``) and
291 how to keep LLVM source code portable
292
Sean Silva9d0eb942013-01-20 02:19:42 +0000293:doc:`LinkTimeOptimization`
Sean Silva12159ff2013-01-20 02:19:36 +0000294 This document describes the interface between LLVM intermodular optimizer
295 and the linker and its design
296
Sean Silva9d0eb942013-01-20 02:19:42 +0000297:doc:`GoldPlugin`
Sean Silva12159ff2013-01-20 02:19:36 +0000298 How to build your programs with link-time optimization on Linux.
299
Sean Silva9d0eb942013-01-20 02:19:42 +0000300:doc:`DebuggingJITedCode`
Sean Silva12159ff2013-01-20 02:19:36 +0000301 How to debug JITed code with GDB.
302
Sean Silva9d0eb942013-01-20 02:19:42 +0000303:doc:`BranchWeightMetadata`
Sean Silva12159ff2013-01-20 02:19:36 +0000304 Provides information about Branch Prediction Information.
305
Sean Silva9d0eb942013-01-20 02:19:42 +0000306:doc:`SegmentedStacks`
Sean Silva12159ff2013-01-20 02:19:36 +0000307 This document describes segmented stacks and how they are used in LLVM.
308
Sean Silva9d0eb942013-01-20 02:19:42 +0000309:doc:`MarkedUpDisassembly`
Sean Silva12159ff2013-01-20 02:19:36 +0000310 This document describes the optional rich disassembly output syntax.
311
Joe Abbeyba3e9012013-02-12 11:45:22 +0000312:doc:`HowToUseAttributes`
313 Answers some questions about the new Attributes infrastructure.
Sean Silva12159ff2013-01-20 02:19:36 +0000314
315Development Process Documentation
316=================================
317
Sean Silva12159ff2013-01-20 02:19:36 +0000318Information about LLVM's development process.
319
320.. toctree::
321 :hidden:
322
Sean Silva9d205c82013-03-30 15:32:47 +0000323 DeveloperPolicy
Sean Silva12159ff2013-01-20 02:19:36 +0000324 MakefileGuide
325 Projects
326 LLVMBuild
327 HowToReleaseLLVM
Sean Silvabdb940f2013-01-28 21:28:10 +0000328 Packaging
Sean Silva12159ff2013-01-20 02:19:36 +0000329
Sean Silva9d205c82013-03-30 15:32:47 +0000330:doc:`DeveloperPolicy`
331 The LLVM project's policy towards developers and their contributions.
332
Sean Silva9d0eb942013-01-20 02:19:42 +0000333:doc:`Projects`
Sean Silva12159ff2013-01-20 02:19:36 +0000334 How-to guide and templates for new projects that *use* the LLVM
335 infrastructure. The templates (directory organization, Makefiles, and test
336 tree) allow the project code to be located outside (or inside) the ``llvm/``
337 tree, while using LLVM header files and libraries.
338
Sean Silva9d0eb942013-01-20 02:19:42 +0000339:doc:`LLVMBuild`
Sean Silva12159ff2013-01-20 02:19:36 +0000340 Describes the LLVMBuild organization and files used by LLVM to specify
341 component descriptions.
342
Sean Silva9d0eb942013-01-20 02:19:42 +0000343:doc:`MakefileGuide`
Sean Silva12159ff2013-01-20 02:19:36 +0000344 Describes how the LLVM makefiles work and how to use them.
345
Sean Silva9d0eb942013-01-20 02:19:42 +0000346:doc:`HowToReleaseLLVM`
Sean Silva12159ff2013-01-20 02:19:36 +0000347 This is a guide to preparing LLVM releases. Most developers can ignore it.
348
Sean Silvabdb940f2013-01-28 21:28:10 +0000349:doc:`Packaging`
350 Advice on packaging LLVM into a distribution.
351
Sean Silva12159ff2013-01-20 02:19:36 +0000352Mailing Lists
353=============
354
355If you can't find what you need in these docs, try consulting the mailing
356lists.
357
Sean Silva9d0eb942013-01-20 02:19:42 +0000358`LLVM Announcements List`__
Sean Silva12159ff2013-01-20 02:19:36 +0000359 This is a low volume list that provides important announcements regarding
360 LLVM. It gets email about once a month.
361
Sean Silva9d0eb942013-01-20 02:19:42 +0000362 .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce
Sean Silva12159ff2013-01-20 02:19:36 +0000363
Sean Silva9d0eb942013-01-20 02:19:42 +0000364`Developer's List`__
Sean Silva12159ff2013-01-20 02:19:36 +0000365 This list is for people who want to be included in technical discussions of
366 LLVM. People post to this list when they have questions about writing code
367 for or using the LLVM tools. It is relatively low volume.
368
Sean Silva9d0eb942013-01-20 02:19:42 +0000369 .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
Sean Silva12159ff2013-01-20 02:19:36 +0000370
Sean Silva9d0eb942013-01-20 02:19:42 +0000371`Bugs & Patches Archive`__
Sean Silva12159ff2013-01-20 02:19:36 +0000372 This list gets emailed every time a bug is opened and closed, and when people
373 submit patches to be included in LLVM. It is higher volume than the LLVMdev
374 list.
375
Sean Silva9d0eb942013-01-20 02:19:42 +0000376 .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/
Sean Silva12159ff2013-01-20 02:19:36 +0000377
Sean Silva9d0eb942013-01-20 02:19:42 +0000378`Commits Archive`__
Sean Silva12159ff2013-01-20 02:19:36 +0000379 This list contains all commit messages that are made when LLVM developers
380 commit code changes to the repository. It is useful for those who want to
381 stay on the bleeding edge of LLVM development. This list is very high volume.
382
Sean Silva9d0eb942013-01-20 02:19:42 +0000383 .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/
Sean Silva12159ff2013-01-20 02:19:36 +0000384
Sean Silva9d0eb942013-01-20 02:19:42 +0000385`Test Results Archive`__
Sean Silva12159ff2013-01-20 02:19:36 +0000386 A message is automatically sent to this list by every active nightly tester
387 when it completes. As such, this list gets email several times each day,
388 making it a high volume list.
389
Sean Silva9d0eb942013-01-20 02:19:42 +0000390 .. __: http://lists.cs.uiuc.edu/pipermail/llvm-testresults/
391
Daniel Dunbarfbb80412012-04-19 16:31:37 +0000392Indices and tables
393==================
394
395* :ref:`genindex`
396* :ref:`search`