blob: 4bf86a2bd9c5f7fe6ad5c152397848d58f207b6f [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
Sean Silva12159ff2013-01-20 02:19:36 +000025
Sean Silva9d0eb942013-01-20 02:19:42 +000026:doc:`LangRef`
Sean Silva12159ff2013-01-20 02:19:36 +000027 Defines the LLVM intermediate representation.
28
Sean Silva9d0eb942013-01-20 02:19:42 +000029`Introduction to the LLVM Compiler`__
Sean Silva12159ff2013-01-20 02:19:36 +000030 Presentation providing a users introduction to LLVM.
31
Sean Silva9d0eb942013-01-20 02:19:42 +000032 .. __: http://llvm.org/pubs/2008-10-04-ACAT-LLVM-Intro.html
Sean Silva12159ff2013-01-20 02:19:36 +000033
Sean Silva9d0eb942013-01-20 02:19:42 +000034`Intro to LLVM`__
Sean Silva12159ff2013-01-20 02:19:36 +000035 Book chapter providing a compiler hacker's introduction to LLVM.
36
Sean Silva9d0eb942013-01-20 02:19:42 +000037 .. __: http://www.aosabook.org/en/llvm.html
Sean Silva12159ff2013-01-20 02:19:36 +000038
Sean Silva9d0eb942013-01-20 02:19:42 +000039
40`LLVM: A Compilation Framework for Lifelong Program Analysis & Transformation`__
Sean Silva12159ff2013-01-20 02:19:36 +000041 Design overview.
42
Sean Silva9d0eb942013-01-20 02:19:42 +000043 .. __: http://llvm.org/pubs/2004-01-30-CGO-LLVM.html
Sean Silva12159ff2013-01-20 02:19:36 +000044
Sean Silva9d0eb942013-01-20 02:19:42 +000045`LLVM: An Infrastructure for Multi-Stage Optimization`__
Sean Silva12159ff2013-01-20 02:19:36 +000046 More details (quite old now).
47
Sean Silva9d0eb942013-01-20 02:19:42 +000048 .. __: http://llvm.org/pubs/2002-12-LattnerMSThesis.html
Sean Silva12159ff2013-01-20 02:19:36 +000049
Sean Silva9d0eb942013-01-20 02:19:42 +000050`Publications mentioning LLVM <http://llvm.org/pubs>`_
51 ..
Sean Silva12159ff2013-01-20 02:19:36 +000052
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 CommandGuide/index
Sean Silva12159ff2013-01-20 02:19:36 +000070 GettingStarted
71 GettingStartedVS
72 FAQ
73 Lexicon
Sean Silva12159ff2013-01-20 02:19:36 +000074 HowToAddABuilder
75 yaml2obj
76 HowToSubmitABug
77 SphinxQuickstartTemplate
78 Phabricator
79 TestingGuide
80 tutorial/index
81 ReleaseNotes
82 Passes
83 YamlIO
Sean Silva163b5c42013-03-30 15:32:50 +000084 GetElementPtr
Sean Silva12159ff2013-01-20 02:19:36 +000085
Sean Silva9d0eb942013-01-20 02:19:42 +000086:doc:`GettingStarted`
Sean Silva12159ff2013-01-20 02:19:36 +000087 Discusses how to get up and running quickly with the LLVM infrastructure.
88 Everything from unpacking and compilation of the distribution to execution
89 of some tools.
90
Sean Silva9d0eb942013-01-20 02:19:42 +000091:doc:`CMake`
Sean Silva12159ff2013-01-20 02:19:36 +000092 An addendum to the main Getting Started guide for those using the `CMake
93 build system <http://www.cmake.org>`_.
94
Sean Silva9d0eb942013-01-20 02:19:42 +000095:doc:`HowToBuildOnARM`
Sean Silva12159ff2013-01-20 02:19:36 +000096 Notes on building and testing LLVM/Clang on ARM.
97
Sean Silva9d0eb942013-01-20 02:19:42 +000098:doc:`GettingStartedVS`
Sean Silva12159ff2013-01-20 02:19:36 +000099 An addendum to the main Getting Started guide for those using Visual Studio
100 on Windows.
101
Sean Silva9d0eb942013-01-20 02:19:42 +0000102:doc:`tutorial/index`
Sean Silva12159ff2013-01-20 02:19:36 +0000103 Tutorials about using LLVM. Includes a tutorial about making a custom
104 language with LLVM.
105
Sean Silva9d0eb942013-01-20 02:19:42 +0000106:doc:`LLVM Command Guide <CommandGuide/index>`
Sean Silva12159ff2013-01-20 02:19:36 +0000107 A reference manual for the LLVM command line utilities ("man" pages for LLVM
108 tools).
109
Sean Silva9d0eb942013-01-20 02:19:42 +0000110:doc:`Passes`
Sean Silva12159ff2013-01-20 02:19:36 +0000111 A list of optimizations and analyses implemented in LLVM.
112
Sean Silva9d0eb942013-01-20 02:19:42 +0000113:doc:`FAQ`
Sean Silva12159ff2013-01-20 02:19:36 +0000114 A list of common questions and problems and their solutions.
115
Sean Silva9d0eb942013-01-20 02:19:42 +0000116:doc:`Release notes for the current release <ReleaseNotes>`
Sean Silva12159ff2013-01-20 02:19:36 +0000117 This describes new features, known bugs, and other limitations.
118
Sean Silva9d0eb942013-01-20 02:19:42 +0000119:doc:`HowToSubmitABug`
Sean Silva12159ff2013-01-20 02:19:36 +0000120 Instructions for properly submitting information about any bugs you run into
121 in the LLVM system.
Sean Silva12159ff2013-01-20 02:19:36 +0000122
Sean Silva9d0eb942013-01-20 02:19:42 +0000123:doc:`SphinxQuickstartTemplate`
Sean Silva12159ff2013-01-20 02:19:36 +0000124 A template + tutorial for writing new Sphinx documentation. It is meant
125 to be read in source form.
126
Sean Silva9d0eb942013-01-20 02:19:42 +0000127:doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
Sean Silva12159ff2013-01-20 02:19:36 +0000128 A reference manual for using the LLVM testing infrastructure.
129
Sean Silva9d0eb942013-01-20 02:19:42 +0000130`How to build the C, C++, ObjC, and ObjC++ front end`__
Sean Silva12159ff2013-01-20 02:19:36 +0000131 Instructions for building the clang front-end from source.
132
Sean Silva9d0eb942013-01-20 02:19:42 +0000133 .. __: http://clang.llvm.org/get_started.html
Sean Silva12159ff2013-01-20 02:19:36 +0000134
Sean Silva9d0eb942013-01-20 02:19:42 +0000135:doc:`Lexicon`
Sean Silva12159ff2013-01-20 02:19:36 +0000136 Definition of acronyms, terms and concepts used in LLVM.
137
Sean Silva9d0eb942013-01-20 02:19:42 +0000138:doc:`HowToAddABuilder`
Sean Silva12159ff2013-01-20 02:19:36 +0000139 Instructions for adding new builder to LLVM buildbot master.
140
Sean Silva9d0eb942013-01-20 02:19:42 +0000141:doc:`YamlIO`
Sean Silva12159ff2013-01-20 02:19:36 +0000142 A reference guide for using LLVM's YAML I/O library.
143
Sean Silva163b5c42013-03-30 15:32:50 +0000144:doc:`GetElementPtr`
145 Answers to some very frequent questions about LLVM's most frequently
146 misunderstood instruction.
147
Sean Silva12159ff2013-01-20 02:19:36 +0000148Programming Documentation
149=========================
150
151For developers of applications which use LLVM as a library.
152
153.. toctree::
154 :hidden:
155
156 Atomics
157 CodingStandards
158 CommandLine
159 CompilerWriterInfo
160 ExtendingLLVM
161 HowToSetUpLLVMStyleRTTI
162 ProgrammersManual
Nico Rieck1da45292013-04-10 23:28:17 +0000163 Extensions
Sean Silva12159ff2013-01-20 02:19:36 +0000164
Sean Silva9d0eb942013-01-20 02:19:42 +0000165:doc:`LLVM Language Reference Manual <LangRef>`
Sean Silva12159ff2013-01-20 02:19:36 +0000166 Defines the LLVM intermediate representation and the assembly form of the
167 different nodes.
168
Sean Silva9d0eb942013-01-20 02:19:42 +0000169:doc:`Atomics`
Sean Silva12159ff2013-01-20 02:19:36 +0000170 Information about LLVM's concurrency model.
171
Sean Silva9d0eb942013-01-20 02:19:42 +0000172:doc:`ProgrammersManual`
Sean Silva12159ff2013-01-20 02:19:36 +0000173 Introduction to the general layout of the LLVM sourcebase, important classes
174 and APIs, and some tips & tricks.
175
Nico Rieck1da45292013-04-10 23:28:17 +0000176:doc:`Extensions`
177 LLVM-specific extensions to tools and formats LLVM seeks compatibility with.
178
Sean Silva9d0eb942013-01-20 02:19:42 +0000179:doc:`CommandLine`
Sean Silva12159ff2013-01-20 02:19:36 +0000180 Provides information on using the command line parsing library.
181
Sean Silva9d0eb942013-01-20 02:19:42 +0000182:doc:`CodingStandards`
Sean Silva12159ff2013-01-20 02:19:36 +0000183 Details the LLVM coding standards and provides useful information on writing
184 efficient C++ code.
185
Sean Silva9d0eb942013-01-20 02:19:42 +0000186:doc:`HowToSetUpLLVMStyleRTTI`
Sean Silva12159ff2013-01-20 02:19:36 +0000187 How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
188 class hierarchy.
189
Sean Silva9d0eb942013-01-20 02:19:42 +0000190:doc:`ExtendingLLVM`
Sean Silva12159ff2013-01-20 02:19:36 +0000191 Look here to see how to add instructions and intrinsics to LLVM.
192
Sean Silva9d0eb942013-01-20 02:19:42 +0000193`Doxygen generated documentation <http://llvm.org/doxygen/>`_
Sean Silva12159ff2013-01-20 02:19:36 +0000194 (`classes <http://llvm.org/doxygen/inherits.html>`_)
195 (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
196
Sean Silva9d0eb942013-01-20 02:19:42 +0000197`ViewVC Repository Browser <http://llvm.org/viewvc/>`_
198 ..
Sean Silva12159ff2013-01-20 02:19:36 +0000199
Sean Silva9d0eb942013-01-20 02:19:42 +0000200:doc:`CompilerWriterInfo`
Sean Silva12159ff2013-01-20 02:19:36 +0000201 A list of helpful links for compiler writers.
202
203Subsystem Documentation
204=======================
205
206For API clients and LLVM developers.
207
208.. toctree::
209 :hidden:
210
211 AliasAnalysis
212 BitCodeFormat
213 BranchWeightMetadata
214 Bugpoint
215 CodeGenerator
216 ExceptionHandling
217 LinkTimeOptimization
218 SegmentedStacks
219 TableGenFundamentals
220 DebuggingJITedCode
221 GoldPlugin
222 MarkedUpDisassembly
223 SystemLibrary
224 SourceLevelDebugging
225 Vectorizers
226 WritingAnLLVMBackend
227 GarbageCollection
228 WritingAnLLVMPass
229 TableGen/LangRef
Joe Abbeyba3e9012013-02-12 11:45:22 +0000230 HowToUseAttributes
Justin Holewinski45df8822013-03-30 16:41:14 +0000231 NVPTXUsage
Sean Silva12159ff2013-01-20 02:19:36 +0000232
Sean Silva9d0eb942013-01-20 02:19:42 +0000233:doc:`WritingAnLLVMPass`
Sean Silva12159ff2013-01-20 02:19:36 +0000234 Information on how to write LLVM transformations and analyses.
235
Sean Silva9d0eb942013-01-20 02:19:42 +0000236:doc:`WritingAnLLVMBackend`
Sean Silva12159ff2013-01-20 02:19:36 +0000237 Information on how to write LLVM backends for machine targets.
238
Sean Silva9d0eb942013-01-20 02:19:42 +0000239:doc:`CodeGenerator`
Sean Silva12159ff2013-01-20 02:19:36 +0000240 The design and implementation of the LLVM code generator. Useful if you are
241 working on retargetting LLVM to a new architecture, designing a new codegen
242 pass, or enhancing existing components.
243
Sean Silva9d0eb942013-01-20 02:19:42 +0000244:doc:`TableGenFundamentals`
Sean Silva12159ff2013-01-20 02:19:36 +0000245 Describes the TableGen tool, which is used heavily by the LLVM code
246 generator.
247
Sean Silva9d0eb942013-01-20 02:19:42 +0000248:doc:`AliasAnalysis`
Sean Silva12159ff2013-01-20 02:19:36 +0000249 Information on how to write a new alias analysis implementation or how to
250 use existing analyses.
251
Sean Silva9d0eb942013-01-20 02:19:42 +0000252:doc:`GarbageCollection`
Sean Silva12159ff2013-01-20 02:19:36 +0000253 The interfaces source-language compilers should use for compiling GC'd
254 programs.
255
Sean Silva9d0eb942013-01-20 02:19:42 +0000256:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
Sean Silva12159ff2013-01-20 02:19:36 +0000257 This document describes the design and philosophy behind the LLVM
258 source-level debugger.
259
Sean Silva9d0eb942013-01-20 02:19:42 +0000260:doc:`Vectorizers`
Sean Silva12159ff2013-01-20 02:19:36 +0000261 This document describes the current status of vectorization in LLVM.
262
Sean Silva9d0eb942013-01-20 02:19:42 +0000263:doc:`ExceptionHandling`
Sean Silva12159ff2013-01-20 02:19:36 +0000264 This document describes the design and implementation of exception handling
265 in LLVM.
266
Sean Silva9d0eb942013-01-20 02:19:42 +0000267:doc:`Bugpoint`
Sean Silva12159ff2013-01-20 02:19:36 +0000268 Automatic bug finder and test-case reducer description and usage
269 information.
270
Sean Silva9d0eb942013-01-20 02:19:42 +0000271:doc:`BitCodeFormat`
Sean Silva12159ff2013-01-20 02:19:36 +0000272 This describes the file format and encoding used for LLVM "bc" files.
273
Sean Silva9d0eb942013-01-20 02:19:42 +0000274:doc:`System Library <SystemLibrary>`
Sean Silva12159ff2013-01-20 02:19:36 +0000275 This document describes the LLVM System Library (``lib/System``) and
276 how to keep LLVM source code portable
277
Sean Silva9d0eb942013-01-20 02:19:42 +0000278:doc:`LinkTimeOptimization`
Sean Silva12159ff2013-01-20 02:19:36 +0000279 This document describes the interface between LLVM intermodular optimizer
280 and the linker and its design
281
Sean Silva9d0eb942013-01-20 02:19:42 +0000282:doc:`GoldPlugin`
Sean Silva12159ff2013-01-20 02:19:36 +0000283 How to build your programs with link-time optimization on Linux.
284
Sean Silva9d0eb942013-01-20 02:19:42 +0000285:doc:`DebuggingJITedCode`
Sean Silva12159ff2013-01-20 02:19:36 +0000286 How to debug JITed code with GDB.
287
Andrew Kaylor27299c32013-08-21 22:15:09 +0000288:doc:`MCJITDesignAndImplementation`
289 Describes the inner workings of MCJIT execution engine.
290
Sean Silva9d0eb942013-01-20 02:19:42 +0000291:doc:`BranchWeightMetadata`
Sean Silva12159ff2013-01-20 02:19:36 +0000292 Provides information about Branch Prediction Information.
293
Sean Silva9d0eb942013-01-20 02:19:42 +0000294:doc:`SegmentedStacks`
Sean Silva12159ff2013-01-20 02:19:36 +0000295 This document describes segmented stacks and how they are used in LLVM.
296
Sean Silva9d0eb942013-01-20 02:19:42 +0000297:doc:`MarkedUpDisassembly`
Sean Silva12159ff2013-01-20 02:19:36 +0000298 This document describes the optional rich disassembly output syntax.
299
Joe Abbeyba3e9012013-02-12 11:45:22 +0000300:doc:`HowToUseAttributes`
301 Answers some questions about the new Attributes infrastructure.
Sean Silva12159ff2013-01-20 02:19:36 +0000302
Justin Holewinski45df8822013-03-30 16:41:14 +0000303:doc:`NVPTXUsage`
304 This document describes using the NVPTX back-end to compile GPU kernels.
305
306
Sean Silva12159ff2013-01-20 02:19:36 +0000307Development Process Documentation
308=================================
309
Sean Silva12159ff2013-01-20 02:19:36 +0000310Information about LLVM's development process.
311
312.. toctree::
313 :hidden:
314
Sean Silva9d205c82013-03-30 15:32:47 +0000315 DeveloperPolicy
Sean Silva12159ff2013-01-20 02:19:36 +0000316 MakefileGuide
317 Projects
318 LLVMBuild
319 HowToReleaseLLVM
Sean Silvabdb940f2013-01-28 21:28:10 +0000320 Packaging
Sean Silva12159ff2013-01-20 02:19:36 +0000321
Sean Silva9d205c82013-03-30 15:32:47 +0000322:doc:`DeveloperPolicy`
323 The LLVM project's policy towards developers and their contributions.
324
Sean Silva9d0eb942013-01-20 02:19:42 +0000325:doc:`Projects`
Sean Silva12159ff2013-01-20 02:19:36 +0000326 How-to guide and templates for new projects that *use* the LLVM
327 infrastructure. The templates (directory organization, Makefiles, and test
328 tree) allow the project code to be located outside (or inside) the ``llvm/``
329 tree, while using LLVM header files and libraries.
330
Sean Silva9d0eb942013-01-20 02:19:42 +0000331:doc:`LLVMBuild`
Sean Silva12159ff2013-01-20 02:19:36 +0000332 Describes the LLVMBuild organization and files used by LLVM to specify
333 component descriptions.
334
Sean Silva9d0eb942013-01-20 02:19:42 +0000335:doc:`MakefileGuide`
Sean Silva12159ff2013-01-20 02:19:36 +0000336 Describes how the LLVM makefiles work and how to use them.
337
Sean Silva9d0eb942013-01-20 02:19:42 +0000338:doc:`HowToReleaseLLVM`
Sean Silva12159ff2013-01-20 02:19:36 +0000339 This is a guide to preparing LLVM releases. Most developers can ignore it.
340
Renato Golinc08f2182013-05-28 10:32:55 +0000341:doc:`ReleaseProcess`
342 This is a validate a new release, during the release process. Most developers can ignore it.
343
Sean Silvabdb940f2013-01-28 21:28:10 +0000344:doc:`Packaging`
345 Advice on packaging LLVM into a distribution.
346
Sean Silva01299242013-03-30 15:32:51 +0000347Community
348=========
349
350LLVM has a thriving community of friendly and helpful developers.
351The two primary communication mechanisms in the LLVM community are mailing
352lists and IRC.
353
Sean Silva12159ff2013-01-20 02:19:36 +0000354Mailing Lists
Sean Silva01299242013-03-30 15:32:51 +0000355-------------
Sean Silva12159ff2013-01-20 02:19:36 +0000356
357If you can't find what you need in these docs, try consulting the mailing
358lists.
359
Sean Silvaab4997d2013-03-30 15:33:01 +0000360`Developer's List (llvmdev)`__
Sean Silva12159ff2013-01-20 02:19:36 +0000361 This list is for people who want to be included in technical discussions of
362 LLVM. People post to this list when they have questions about writing code
363 for or using the LLVM tools. It is relatively low volume.
364
Sean Silva9d0eb942013-01-20 02:19:42 +0000365 .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
Sean Silva12159ff2013-01-20 02:19:36 +0000366
Sean Silvaab4997d2013-03-30 15:33:01 +0000367`Commits Archive (llvm-commits)`__
Sean Silva12159ff2013-01-20 02:19:36 +0000368 This list contains all commit messages that are made when LLVM developers
Sean Silva2a746992013-03-30 15:33:02 +0000369 commit code changes to the repository. It also serves as a forum for
370 patch review (i.e. send patches here). It is useful for those who want to
371 stay on the bleeding edge of LLVM development. This list is very high
372 volume.
Sean Silva12159ff2013-01-20 02:19:36 +0000373
Sean Silva9d0eb942013-01-20 02:19:42 +0000374 .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/
Sean Silva12159ff2013-01-20 02:19:36 +0000375
Sean Silvaab4997d2013-03-30 15:33:01 +0000376`Bugs & Patches Archive (llvmbugs)`__
Sean Silva2a746992013-03-30 15:33:02 +0000377 This list gets emailed every time a bug is opened and closed. It is
378 higher volume than the LLVMdev list.
Sean Silva84b296c2013-03-30 15:32:54 +0000379
380 .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/
381
Sean Silvaab4997d2013-03-30 15:33:01 +0000382`Test Results Archive (llvm-testresults)`__
Sean Silva12159ff2013-01-20 02:19:36 +0000383 A message is automatically sent to this list by every active nightly tester
384 when it completes. As such, this list gets email several times each day,
385 making it a high volume list.
386
Sean Silva9d0eb942013-01-20 02:19:42 +0000387 .. __: http://lists.cs.uiuc.edu/pipermail/llvm-testresults/
388
Sean Silvaab4997d2013-03-30 15:33:01 +0000389`LLVM Announcements List (llvm-announce)`__
Sean Silva84b296c2013-03-30 15:32:54 +0000390 This is a low volume list that provides important announcements regarding
391 LLVM. It gets email about once a month.
392
393 .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce
394
Sean Silva01299242013-03-30 15:32:51 +0000395IRC
396---
397
398Users and developers of the LLVM project (including subprojects such as Clang)
399can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
400
401This channel has several bots.
402
403* Buildbot reporters
404
405 * llvmbb - Bot for the main LLVM buildbot master.
406 http://lab.llvm.org:8011/console
407 * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
408 * smooshlab - Apple's internal buildbot master.
409
410* robot - Bugzilla linker. %bug <number>
411
412* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
413 near-trunk clang instead of gcc.
414
415
Daniel Dunbarfbb80412012-04-19 16:31:37 +0000416Indices and tables
417==================
418
419* :ref:`genindex`
420* :ref:`search`