blob: 4ea67dffce97bfe946f3948364b3dd82b7da47ae [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
75 DeveloperPolicy
76 GettingStarted
77 GettingStartedVS
78 FAQ
79 Lexicon
80 Packaging
81 HowToAddABuilder
82 yaml2obj
83 HowToSubmitABug
84 SphinxQuickstartTemplate
85 Phabricator
86 TestingGuide
87 tutorial/index
88 ReleaseNotes
89 Passes
90 YamlIO
91
Sean Silva9d0eb942013-01-20 02:19:42 +000092:doc:`GettingStarted`
Sean Silva12159ff2013-01-20 02:19:36 +000093 Discusses how to get up and running quickly with the LLVM infrastructure.
94 Everything from unpacking and compilation of the distribution to execution
95 of some tools.
96
Sean Silva9d0eb942013-01-20 02:19:42 +000097:doc:`CMake`
Sean Silva12159ff2013-01-20 02:19:36 +000098 An addendum to the main Getting Started guide for those using the `CMake
99 build system <http://www.cmake.org>`_.
100
Sean Silva9d0eb942013-01-20 02:19:42 +0000101:doc:`HowToBuildOnARM`
Sean Silva12159ff2013-01-20 02:19:36 +0000102 Notes on building and testing LLVM/Clang on ARM.
103
Sean Silva9d0eb942013-01-20 02:19:42 +0000104:doc:`GettingStartedVS`
Sean Silva12159ff2013-01-20 02:19:36 +0000105 An addendum to the main Getting Started guide for those using Visual Studio
106 on Windows.
107
Sean Silva9d0eb942013-01-20 02:19:42 +0000108:doc:`tutorial/index`
Sean Silva12159ff2013-01-20 02:19:36 +0000109 Tutorials about using LLVM. Includes a tutorial about making a custom
110 language with LLVM.
111
Sean Silva9d0eb942013-01-20 02:19:42 +0000112:doc:`DeveloperPolicy`
Sean Silva12159ff2013-01-20 02:19:36 +0000113 The LLVM project's policy towards developers and their contributions.
114
Sean Silva9d0eb942013-01-20 02:19:42 +0000115:doc:`LLVM Command Guide <CommandGuide/index>`
Sean Silva12159ff2013-01-20 02:19:36 +0000116 A reference manual for the LLVM command line utilities ("man" pages for LLVM
117 tools).
118
Sean Silva9d0eb942013-01-20 02:19:42 +0000119:doc:`Passes`
Sean Silva12159ff2013-01-20 02:19:36 +0000120 A list of optimizations and analyses implemented in LLVM.
121
Sean Silva9d0eb942013-01-20 02:19:42 +0000122:doc:`FAQ`
Sean Silva12159ff2013-01-20 02:19:36 +0000123 A list of common questions and problems and their solutions.
124
Sean Silva9d0eb942013-01-20 02:19:42 +0000125:doc:`Release notes for the current release <ReleaseNotes>`
Sean Silva12159ff2013-01-20 02:19:36 +0000126 This describes new features, known bugs, and other limitations.
127
Sean Silva9d0eb942013-01-20 02:19:42 +0000128:doc:`HowToSubmitABug`
Sean Silva12159ff2013-01-20 02:19:36 +0000129 Instructions for properly submitting information about any bugs you run into
130 in the LLVM system.
Sean Silva12159ff2013-01-20 02:19:36 +0000131
Sean Silva9d0eb942013-01-20 02:19:42 +0000132:doc:`SphinxQuickstartTemplate`
Sean Silva12159ff2013-01-20 02:19:36 +0000133 A template + tutorial for writing new Sphinx documentation. It is meant
134 to be read in source form.
135
Sean Silva9d0eb942013-01-20 02:19:42 +0000136:doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
Sean Silva12159ff2013-01-20 02:19:36 +0000137 A reference manual for using the LLVM testing infrastructure.
138
Sean Silva9d0eb942013-01-20 02:19:42 +0000139`How to build the C, C++, ObjC, and ObjC++ front end`__
Sean Silva12159ff2013-01-20 02:19:36 +0000140 Instructions for building the clang front-end from source.
141
Sean Silva9d0eb942013-01-20 02:19:42 +0000142 .. __: http://clang.llvm.org/get_started.html
Sean Silva12159ff2013-01-20 02:19:36 +0000143
Sean Silva9d0eb942013-01-20 02:19:42 +0000144:doc:`Packaging`
Sean Silva12159ff2013-01-20 02:19:36 +0000145 Advice on packaging LLVM into a distribution.
146
Sean Silva9d0eb942013-01-20 02:19:42 +0000147:doc:`Lexicon`
Sean Silva12159ff2013-01-20 02:19:36 +0000148 Definition of acronyms, terms and concepts used in LLVM.
149
Sean Silva9d0eb942013-01-20 02:19:42 +0000150:doc:`HowToAddABuilder`
Sean Silva12159ff2013-01-20 02:19:36 +0000151 Instructions for adding new builder to LLVM buildbot master.
152
Sean Silva9d0eb942013-01-20 02:19:42 +0000153:doc:`YamlIO`
Sean Silva12159ff2013-01-20 02:19:36 +0000154 A reference guide for using LLVM's YAML I/O library.
155
156IRC
157===
158
Michael J. Spencer0ad0f5e2013-01-20 09:38:14 +0000159Users and developers of the LLVM project (including subprojects such as Clang)
160can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
Sean Silva12159ff2013-01-20 02:19:36 +0000161
Michael J. Spencer0ad0f5e2013-01-20 09:38:14 +0000162This channel has several bots.
163
164* Buildbot reporters
165
166 * llvmbb - Bot for the main LLVM buildbot master.
167 http://lab.llvm.org:8011/console
168 * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
169 * smooshlab - Apple's internal buildbot master.
170
171* robot - Bugzilla linker. %bug <number>
172
173* clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
174 near-trunk clang instead of gcc.
Sean Silva12159ff2013-01-20 02:19:36 +0000175
176Programming Documentation
177=========================
178
179For developers of applications which use LLVM as a library.
180
181.. toctree::
182 :hidden:
183
184 Atomics
185 CodingStandards
186 CommandLine
187 CompilerWriterInfo
188 ExtendingLLVM
189 HowToSetUpLLVMStyleRTTI
190 ProgrammersManual
191
Sean Silva9d0eb942013-01-20 02:19:42 +0000192:doc:`LLVM Language Reference Manual <LangRef>`
Sean Silva12159ff2013-01-20 02:19:36 +0000193 Defines the LLVM intermediate representation and the assembly form of the
194 different nodes.
195
Sean Silva9d0eb942013-01-20 02:19:42 +0000196:doc:`Atomics`
Sean Silva12159ff2013-01-20 02:19:36 +0000197 Information about LLVM's concurrency model.
198
Sean Silva9d0eb942013-01-20 02:19:42 +0000199:doc:`ProgrammersManual`
Sean Silva12159ff2013-01-20 02:19:36 +0000200 Introduction to the general layout of the LLVM sourcebase, important classes
201 and APIs, and some tips & tricks.
202
Sean Silva9d0eb942013-01-20 02:19:42 +0000203:doc:`CommandLine`
Sean Silva12159ff2013-01-20 02:19:36 +0000204 Provides information on using the command line parsing library.
205
Sean Silva9d0eb942013-01-20 02:19:42 +0000206:doc:`CodingStandards`
Sean Silva12159ff2013-01-20 02:19:36 +0000207 Details the LLVM coding standards and provides useful information on writing
208 efficient C++ code.
209
Sean Silva9d0eb942013-01-20 02:19:42 +0000210:doc:`HowToSetUpLLVMStyleRTTI`
Sean Silva12159ff2013-01-20 02:19:36 +0000211 How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
212 class hierarchy.
213
Sean Silva9d0eb942013-01-20 02:19:42 +0000214:doc:`ExtendingLLVM`
Sean Silva12159ff2013-01-20 02:19:36 +0000215 Look here to see how to add instructions and intrinsics to LLVM.
216
Sean Silva9d0eb942013-01-20 02:19:42 +0000217`Doxygen generated documentation <http://llvm.org/doxygen/>`_
Sean Silva12159ff2013-01-20 02:19:36 +0000218 (`classes <http://llvm.org/doxygen/inherits.html>`_)
219 (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
220
Sean Silva9d0eb942013-01-20 02:19:42 +0000221`ViewVC Repository Browser <http://llvm.org/viewvc/>`_
222 ..
Sean Silva12159ff2013-01-20 02:19:36 +0000223
Sean Silva9d0eb942013-01-20 02:19:42 +0000224:doc:`CompilerWriterInfo`
Sean Silva12159ff2013-01-20 02:19:36 +0000225 A list of helpful links for compiler writers.
226
227Subsystem Documentation
228=======================
229
230For API clients and LLVM developers.
231
232.. toctree::
233 :hidden:
234
235 AliasAnalysis
236 BitCodeFormat
237 BranchWeightMetadata
238 Bugpoint
239 CodeGenerator
240 ExceptionHandling
241 LinkTimeOptimization
242 SegmentedStacks
243 TableGenFundamentals
244 DebuggingJITedCode
245 GoldPlugin
246 MarkedUpDisassembly
247 SystemLibrary
248 SourceLevelDebugging
249 Vectorizers
250 WritingAnLLVMBackend
251 GarbageCollection
252 WritingAnLLVMPass
253 TableGen/LangRef
254
Sean Silva9d0eb942013-01-20 02:19:42 +0000255:doc:`WritingAnLLVMPass`
Sean Silva12159ff2013-01-20 02:19:36 +0000256 Information on how to write LLVM transformations and analyses.
257
Sean Silva9d0eb942013-01-20 02:19:42 +0000258:doc:`WritingAnLLVMBackend`
Sean Silva12159ff2013-01-20 02:19:36 +0000259 Information on how to write LLVM backends for machine targets.
260
Sean Silva9d0eb942013-01-20 02:19:42 +0000261:doc:`CodeGenerator`
Sean Silva12159ff2013-01-20 02:19:36 +0000262 The design and implementation of the LLVM code generator. Useful if you are
263 working on retargetting LLVM to a new architecture, designing a new codegen
264 pass, or enhancing existing components.
265
Sean Silva9d0eb942013-01-20 02:19:42 +0000266:doc:`TableGenFundamentals`
Sean Silva12159ff2013-01-20 02:19:36 +0000267 Describes the TableGen tool, which is used heavily by the LLVM code
268 generator.
269
Sean Silva9d0eb942013-01-20 02:19:42 +0000270:doc:`AliasAnalysis`
Sean Silva12159ff2013-01-20 02:19:36 +0000271 Information on how to write a new alias analysis implementation or how to
272 use existing analyses.
273
Sean Silva9d0eb942013-01-20 02:19:42 +0000274:doc:`GarbageCollection`
Sean Silva12159ff2013-01-20 02:19:36 +0000275 The interfaces source-language compilers should use for compiling GC'd
276 programs.
277
Sean Silva9d0eb942013-01-20 02:19:42 +0000278:doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
Sean Silva12159ff2013-01-20 02:19:36 +0000279 This document describes the design and philosophy behind the LLVM
280 source-level debugger.
281
Sean Silva9d0eb942013-01-20 02:19:42 +0000282:doc:`Vectorizers`
Sean Silva12159ff2013-01-20 02:19:36 +0000283 This document describes the current status of vectorization in LLVM.
284
Sean Silva9d0eb942013-01-20 02:19:42 +0000285:doc:`ExceptionHandling`
Sean Silva12159ff2013-01-20 02:19:36 +0000286 This document describes the design and implementation of exception handling
287 in LLVM.
288
Sean Silva9d0eb942013-01-20 02:19:42 +0000289:doc:`Bugpoint`
Sean Silva12159ff2013-01-20 02:19:36 +0000290 Automatic bug finder and test-case reducer description and usage
291 information.
292
Sean Silva9d0eb942013-01-20 02:19:42 +0000293:doc:`BitCodeFormat`
Sean Silva12159ff2013-01-20 02:19:36 +0000294 This describes the file format and encoding used for LLVM "bc" files.
295
Sean Silva9d0eb942013-01-20 02:19:42 +0000296:doc:`System Library <SystemLibrary>`
Sean Silva12159ff2013-01-20 02:19:36 +0000297 This document describes the LLVM System Library (``lib/System``) and
298 how to keep LLVM source code portable
299
Sean Silva9d0eb942013-01-20 02:19:42 +0000300:doc:`LinkTimeOptimization`
Sean Silva12159ff2013-01-20 02:19:36 +0000301 This document describes the interface between LLVM intermodular optimizer
302 and the linker and its design
303
Sean Silva9d0eb942013-01-20 02:19:42 +0000304:doc:`GoldPlugin`
Sean Silva12159ff2013-01-20 02:19:36 +0000305 How to build your programs with link-time optimization on Linux.
306
Sean Silva9d0eb942013-01-20 02:19:42 +0000307:doc:`DebuggingJITedCode`
Sean Silva12159ff2013-01-20 02:19:36 +0000308 How to debug JITed code with GDB.
309
Sean Silva9d0eb942013-01-20 02:19:42 +0000310:doc:`BranchWeightMetadata`
Sean Silva12159ff2013-01-20 02:19:36 +0000311 Provides information about Branch Prediction Information.
312
Sean Silva9d0eb942013-01-20 02:19:42 +0000313:doc:`SegmentedStacks`
Sean Silva12159ff2013-01-20 02:19:36 +0000314 This document describes segmented stacks and how they are used in LLVM.
315
Sean Silva9d0eb942013-01-20 02:19:42 +0000316:doc:`MarkedUpDisassembly`
Sean Silva12159ff2013-01-20 02:19:36 +0000317 This document describes the optional rich disassembly output syntax.
318
319
320Development Process Documentation
321=================================
322
Sean Silva12159ff2013-01-20 02:19:36 +0000323Information about LLVM's development process.
324
325.. toctree::
326 :hidden:
327
328 MakefileGuide
329 Projects
330 LLVMBuild
331 HowToReleaseLLVM
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
349Mailing Lists
350=============
351
352If you can't find what you need in these docs, try consulting the mailing
353lists.
354
Sean Silva9d0eb942013-01-20 02:19:42 +0000355`LLVM Announcements List`__
Sean Silva12159ff2013-01-20 02:19:36 +0000356 This is a low volume list that provides important announcements regarding
357 LLVM. It gets email about once a month.
358
Sean Silva9d0eb942013-01-20 02:19:42 +0000359 .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce
Sean Silva12159ff2013-01-20 02:19:36 +0000360
Sean Silva9d0eb942013-01-20 02:19:42 +0000361`Developer's List`__
Sean Silva12159ff2013-01-20 02:19:36 +0000362 This list is for people who want to be included in technical discussions of
363 LLVM. People post to this list when they have questions about writing code
364 for or using the LLVM tools. It is relatively low volume.
365
Sean Silva9d0eb942013-01-20 02:19:42 +0000366 .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
Sean Silva12159ff2013-01-20 02:19:36 +0000367
Sean Silva9d0eb942013-01-20 02:19:42 +0000368`Bugs & Patches Archive`__
Sean Silva12159ff2013-01-20 02:19:36 +0000369 This list gets emailed every time a bug is opened and closed, and when people
370 submit patches to be included in LLVM. It is higher volume than the LLVMdev
371 list.
372
Sean Silva9d0eb942013-01-20 02:19:42 +0000373 .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/
Sean Silva12159ff2013-01-20 02:19:36 +0000374
Sean Silva9d0eb942013-01-20 02:19:42 +0000375`Commits Archive`__
Sean Silva12159ff2013-01-20 02:19:36 +0000376 This list contains all commit messages that are made when LLVM developers
377 commit code changes to the repository. It is useful for those who want to
378 stay on the bleeding edge of LLVM development. This list is very high volume.
379
Sean Silva9d0eb942013-01-20 02:19:42 +0000380 .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/
Sean Silva12159ff2013-01-20 02:19:36 +0000381
Sean Silva9d0eb942013-01-20 02:19:42 +0000382`Test Results Archive`__
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
Daniel Dunbarfbb80412012-04-19 16:31:37 +0000389Indices and tables
390==================
391
392* :ref:`genindex`
393* :ref:`search`