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