docs/index.rst

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