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