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