Revert "DebugInfo: remove unused helper function getDICompositeType."
[oota-llvm.git] / docs / index.rst
1 Overview
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
9 The LLVM compiler infrastructure supports a wide range of projects, from
10 industrial strength compilers to specialized JIT applications to small
11 research projects.
12
13 Similarly, documentation is broken down into several high-level groupings
14 targeted at different audiences:
15
16 LLVM Design & Overview
17 ======================
18
19 Several 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
53 User Guides
54 ===========
55
56 For those new to the LLVM system.
57
58 NOTE: If you are a user who is only interested in using LLVM-based
59 compilers, you should look into `Clang <http://clang.llvm.org>`_ or
60 `DragonEgg <http://dragonegg.llvm.org>`_ instead. The documentation here is
61 intended for users who have a need to work with the intermediate LLVM
62 representation.
63
64 .. toctree::
65    :hidden:
66
67    CMake
68    HowToBuildOnARM
69    CommandGuide/index
70    GettingStarted
71    GettingStartedVS
72    FAQ
73    Lexicon
74    HowToAddABuilder
75    yaml2obj
76    HowToSubmitABug
77    SphinxQuickstartTemplate
78    Phabricator
79    TestingGuide
80    tutorial/index
81    ReleaseNotes
82    Passes
83    YamlIO
84    GetElementPtr
85
86 :doc:`GettingStarted`
87    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
91 :doc:`CMake`
92    An addendum to the main Getting Started guide for those using the `CMake
93    build system <http://www.cmake.org>`_.
94
95 :doc:`HowToBuildOnARM`
96    Notes on building and testing LLVM/Clang on ARM.
97
98 :doc:`GettingStartedVS`
99    An addendum to the main Getting Started guide for those using Visual Studio
100    on Windows.
101
102 :doc:`tutorial/index`
103    Tutorials about using LLVM. Includes a tutorial about making a custom
104    language with LLVM.
105
106 :doc:`LLVM Command Guide <CommandGuide/index>`
107    A reference manual for the LLVM command line utilities ("man" pages for LLVM
108    tools).
109
110 :doc:`Passes`
111    A list of optimizations and analyses implemented in LLVM.
112
113 :doc:`FAQ`
114    A list of common questions and problems and their solutions.
115
116 :doc:`Release notes for the current release <ReleaseNotes>`
117    This describes new features, known bugs, and other limitations.
118
119 :doc:`HowToSubmitABug`
120    Instructions for properly submitting information about any bugs you run into
121    in the LLVM system.
122
123 :doc:`SphinxQuickstartTemplate`
124   A template + tutorial for writing new Sphinx documentation. It is meant
125   to be read in source form.
126
127 :doc:`LLVM Testing Infrastructure Guide <TestingGuide>`
128    A reference manual for using the LLVM testing infrastructure.
129
130 `How to build the C, C++, ObjC, and ObjC++ front end`__
131    Instructions for building the clang front-end from source.
132
133    .. __: http://clang.llvm.org/get_started.html
134
135 :doc:`Lexicon`
136    Definition of acronyms, terms and concepts used in LLVM.
137
138 :doc:`HowToAddABuilder`
139    Instructions for adding new builder to LLVM buildbot master.
140
141 :doc:`YamlIO`
142    A reference guide for using LLVM's YAML I/O library.
143
144 :doc:`GetElementPtr`
145   Answers to some very frequent questions about LLVM's most frequently
146   misunderstood instruction.
147
148 Programming Documentation
149 =========================
150
151 For 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
163    Extensions
164
165 :doc:`LLVM Language Reference Manual <LangRef>`
166   Defines the LLVM intermediate representation and the assembly form of the
167   different nodes.
168
169 :doc:`Atomics`
170   Information about LLVM's concurrency model.
171
172 :doc:`ProgrammersManual`
173   Introduction to the general layout of the LLVM sourcebase, important classes
174   and APIs, and some tips & tricks.
175
176 :doc:`Extensions`
177   LLVM-specific extensions to tools and formats LLVM seeks compatibility with.
178
179 :doc:`CommandLine`
180   Provides information on using the command line parsing library.
181
182 :doc:`CodingStandards`
183   Details the LLVM coding standards and provides useful information on writing
184   efficient C++ code.
185
186 :doc:`HowToSetUpLLVMStyleRTTI`
187   How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
188   class hierarchy.
189
190 :doc:`ExtendingLLVM`
191   Look here to see how to add instructions and intrinsics to LLVM.
192
193 `Doxygen generated documentation <http://llvm.org/doxygen/>`_
194   (`classes <http://llvm.org/doxygen/inherits.html>`_)
195   (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
196
197 `ViewVC Repository Browser <http://llvm.org/viewvc/>`_
198    ..
199
200 :doc:`CompilerWriterInfo`
201   A list of helpful links for compiler writers.
202
203 Subsystem Documentation
204 =======================
205
206 For 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
230    HowToUseAttributes
231    NVPTXUsage
232
233 :doc:`WritingAnLLVMPass`
234    Information on how to write LLVM transformations and analyses.
235
236 :doc:`WritingAnLLVMBackend`
237    Information on how to write LLVM backends for machine targets.
238
239 :doc:`CodeGenerator`
240    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
244 :doc:`TableGenFundamentals`
245    Describes the TableGen tool, which is used heavily by the LLVM code
246    generator.
247
248 :doc:`AliasAnalysis`
249    Information on how to write a new alias analysis implementation or how to
250    use existing analyses.
251
252 :doc:`GarbageCollection`
253    The interfaces source-language compilers should use for compiling GC'd
254    programs.
255
256 :doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
257    This document describes the design and philosophy behind the LLVM
258    source-level debugger.
259
260 :doc:`Vectorizers`
261    This document describes the current status of vectorization in LLVM.
262
263 :doc:`ExceptionHandling`
264    This document describes the design and implementation of exception handling
265    in LLVM.
266
267 :doc:`Bugpoint`
268    Automatic bug finder and test-case reducer description and usage
269    information.
270
271 :doc:`BitCodeFormat`
272    This describes the file format and encoding used for LLVM "bc" files.
273
274 :doc:`System Library <SystemLibrary>`
275    This document describes the LLVM System Library (``lib/System``) and
276    how to keep LLVM source code portable
277
278 :doc:`LinkTimeOptimization`
279    This document describes the interface between LLVM intermodular optimizer
280    and the linker and its design
281
282 :doc:`GoldPlugin`
283    How to build your programs with link-time optimization on Linux.
284
285 :doc:`DebuggingJITedCode`
286    How to debug JITed code with GDB.
287
288 :doc:`BranchWeightMetadata`
289    Provides information about Branch Prediction Information.
290
291 :doc:`SegmentedStacks`
292    This document describes segmented stacks and how they are used in LLVM.
293
294 :doc:`MarkedUpDisassembly`
295    This document describes the optional rich disassembly output syntax.
296
297 :doc:`HowToUseAttributes`
298   Answers some questions about the new Attributes infrastructure.
299
300 :doc:`NVPTXUsage`
301    This document describes using the NVPTX back-end to compile GPU kernels.
302
303
304 Development Process Documentation
305 =================================
306
307 Information about LLVM's development process.
308
309 .. toctree::
310    :hidden:
311
312    DeveloperPolicy
313    MakefileGuide
314    Projects
315    LLVMBuild
316    HowToReleaseLLVM
317    Packaging
318
319 :doc:`DeveloperPolicy`
320    The LLVM project's policy towards developers and their contributions.
321
322 :doc:`Projects`
323   How-to guide and templates for new projects that *use* the LLVM
324   infrastructure.  The templates (directory organization, Makefiles, and test
325   tree) allow the project code to be located outside (or inside) the ``llvm/``
326   tree, while using LLVM header files and libraries.
327
328 :doc:`LLVMBuild`
329   Describes the LLVMBuild organization and files used by LLVM to specify
330   component descriptions.
331
332 :doc:`MakefileGuide`
333   Describes how the LLVM makefiles work and how to use them.
334
335 :doc:`HowToReleaseLLVM`
336   This is a guide to preparing LLVM releases. Most developers can ignore it.
337
338 :doc:`ReleaseProcess`
339   This is a validate a new release, during the release process. Most developers can ignore it.
340
341 :doc:`Packaging`
342    Advice on packaging LLVM into a distribution.
343
344 Community
345 =========
346
347 LLVM has a thriving community of friendly and helpful developers.
348 The two primary communication mechanisms in the LLVM community are mailing
349 lists and IRC.
350
351 Mailing Lists
352 -------------
353
354 If you can't find what you need in these docs, try consulting the mailing
355 lists.
356
357 `Developer's List (llvmdev)`__
358   This list is for people who want to be included in technical discussions of
359   LLVM. People post to this list when they have questions about writing code
360   for or using the LLVM tools. It is relatively low volume.
361
362   .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
363
364 `Commits Archive (llvm-commits)`__
365   This list contains all commit messages that are made when LLVM developers
366   commit code changes to the repository. It also serves as a forum for
367   patch review (i.e. send patches here). It is useful for those who want to
368   stay on the bleeding edge of LLVM development. This list is very high
369   volume.
370
371   .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/
372
373 `Bugs & Patches Archive (llvmbugs)`__
374   This list gets emailed every time a bug is opened and closed. It is
375   higher volume than the LLVMdev list.
376
377   .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/
378
379 `Test Results Archive (llvm-testresults)`__
380   A message is automatically sent to this list by every active nightly tester
381   when it completes.  As such, this list gets email several times each day,
382   making it a high volume list.
383
384   .. __: http://lists.cs.uiuc.edu/pipermail/llvm-testresults/
385
386 `LLVM Announcements List (llvm-announce)`__
387   This is a low volume list that provides important announcements regarding
388   LLVM.  It gets email about once a month.
389
390   .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce
391
392 IRC
393 ---
394
395 Users and developers of the LLVM project (including subprojects such as Clang)
396 can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
397
398 This channel has several bots.
399
400 * Buildbot reporters
401
402   * llvmbb - Bot for the main LLVM buildbot master.
403     http://lab.llvm.org:8011/console
404   * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
405   * smooshlab - Apple's internal buildbot master.
406
407 * robot - Bugzilla linker. %bug <number>
408
409 * clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
410   near-trunk clang instead of gcc.
411
412
413 Indices and tables
414 ==================
415
416 * :ref:`genindex`
417 * :ref:`search`