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    LibFuzzer
 181
 182 :doc:`LLVM Language Reference Manual <LangRef>`
 183   Defines the LLVM intermediate representation and the assembly form of the
 184   different nodes.
 185
 186 :doc:`Atomics`
 187   Information about LLVM's concurrency model.
 188
 189 :doc:`ProgrammersManual`
 190   Introduction to the general layout of the LLVM sourcebase, important classes
 191   and APIs, and some tips & tricks.
 192
 193 :doc:`Extensions`
 194   LLVM-specific extensions to tools and formats LLVM seeks compatibility with.
 195
 196 :doc:`CommandLine`
 197   Provides information on using the command line parsing library.
 198
 199 :doc:`CodingStandards`
 200   Details the LLVM coding standards and provides useful information on writing
 201   efficient C++ code.
 202
 203 :doc:`HowToSetUpLLVMStyleRTTI`
 204   How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your
 205   class hierarchy.
 206
 207 :doc:`ExtendingLLVM`
 208   Look here to see how to add instructions and intrinsics to LLVM.
 209
 210 `Doxygen generated documentation <http://llvm.org/doxygen/>`_
 211   (`classes <http://llvm.org/doxygen/inherits.html>`_)
 212   (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
 213
 214 `Documentation for Go bindings <http://godoc.org/llvm.org/llvm/bindings/go/llvm>`_
 215
 216 `ViewVC Repository Browser <http://llvm.org/viewvc/>`_
 217    ..
 218
 219 :doc:`CompilerWriterInfo`
 220   A list of helpful links for compiler writers.
 221
 222 :doc:`LibFuzzer`
 223   A library for writing in-process guided fuzzers.
 224
 225 Subsystem Documentation
 226 =======================
 227
 228 For API clients and LLVM developers.
 229
 230 .. toctree::
 231    :hidden:
 232
 233    AliasAnalysis
 234    BitCodeFormat
 235    BlockFrequencyTerminology
 236    BranchWeightMetadata
 237    Bugpoint
 238    CodeGenerator
 239    ExceptionHandling
 240    LinkTimeOptimization
 241    SegmentedStacks
 242    TableGenFundamentals
 243    TableGen/index
 244    DebuggingJITedCode
 245    GoldPlugin
 246    MarkedUpDisassembly
 247    SystemLibrary
 248    SourceLevelDebugging
 249    Vectorizers
 250    WritingAnLLVMBackend
 251    GarbageCollection
 252    WritingAnLLVMPass
 253    HowToUseAttributes
 254    NVPTXUsage
 255    AMDGPUUsage
 256    StackMaps
 257    InAlloca
 258    BigEndianNEON
 259    CoverageMappingFormat
 260    Statepoints
 261    MergeFunctions
 262    BitSets
 263    FaultMaps
 264
 265 :doc:`WritingAnLLVMPass`
 266    Information on how to write LLVM transformations and analyses.
 267
 268 :doc:`WritingAnLLVMBackend`
 269    Information on how to write LLVM backends for machine targets.
 270
 271 :doc:`CodeGenerator`
 272    The design and implementation of the LLVM code generator.  Useful if you are
 273    working on retargetting LLVM to a new architecture, designing a new codegen
 274    pass, or enhancing existing components.
 275
 276 :doc:`TableGen <TableGen/index>`
 277    Describes the TableGen tool, which is used heavily by the LLVM code
 278    generator.
 279
 280 :doc:`AliasAnalysis`
 281    Information on how to write a new alias analysis implementation or how to
 282    use existing analyses.
 283
 284 :doc:`GarbageCollection`
 285    The interfaces source-language compilers should use for compiling GC'd
 286    programs.
 287
 288 :doc:`Source Level Debugging with LLVM <SourceLevelDebugging>`
 289    This document describes the design and philosophy behind the LLVM
 290    source-level debugger.
 291
 292 :doc:`Vectorizers`
 293    This document describes the current status of vectorization in LLVM.
 294
 295 :doc:`ExceptionHandling`
 296    This document describes the design and implementation of exception handling
 297    in LLVM.
 298
 299 :doc:`Bugpoint`
 300    Automatic bug finder and test-case reducer description and usage
 301    information.
 302
 303 :doc:`BitCodeFormat`
 304    This describes the file format and encoding used for LLVM "bc" files.
 305
 306 :doc:`System Library <SystemLibrary>`
 307    This document describes the LLVM System Library (``lib/System``) and
 308    how to keep LLVM source code portable
 309
 310 :doc:`LinkTimeOptimization`
 311    This document describes the interface between LLVM intermodular optimizer
 312    and the linker and its design
 313
 314 :doc:`GoldPlugin`
 315    How to build your programs with link-time optimization on Linux.
 316
 317 :doc:`DebuggingJITedCode`
 318    How to debug JITed code with GDB.
 319
 320 :doc:`MCJITDesignAndImplementation`
 321    Describes the inner workings of MCJIT execution engine.
 322
 323 :doc:`BranchWeightMetadata`
 324    Provides information about Branch Prediction Information.
 325
 326 :doc:`BlockFrequencyTerminology`
 327    Provides information about terminology used in the ``BlockFrequencyInfo``
 328    analysis pass.
 329
 330 :doc:`SegmentedStacks`
 331    This document describes segmented stacks and how they are used in LLVM.
 332
 333 :doc:`MarkedUpDisassembly`
 334    This document describes the optional rich disassembly output syntax.
 335
 336 :doc:`HowToUseAttributes`
 337   Answers some questions about the new Attributes infrastructure.
 338
 339 :doc:`NVPTXUsage`
 340    This document describes using the NVPTX back-end to compile GPU kernels.
 341
 342 :doc:`AMDGPUUsage`
 343    This document describes how to use the AMDGPU back-end.
 344
 345 :doc:`StackMaps`
 346   LLVM support for mapping instruction addresses to the location of
 347   values and allowing code to be patched.
 348
 349 :doc:`BigEndianNEON`
 350   LLVM's support for generating NEON instructions on big endian ARM targets is
 351   somewhat nonintuitive. This document explains the implementation and rationale.
 352
 353 :doc:`CoverageMappingFormat`
 354   This describes the format and encoding used for LLVM’s code coverage mapping.
 355
 356 :doc:`Statepoints`
 357   This describes a set of experimental extensions for garbage
 358   collection support.
 359
 360 :doc:`MergeFunctions`
 361   Describes functions merging optimization.
 362
 363 :doc:`InAlloca`
 364   Description of the ``inalloca`` argument attribute.
 365
 366 :doc:`FaultMaps`
 367   LLVM support for folding control flow into faulting machine instructions.
 368
 369 Development Process Documentation
 370 =================================
 371
 372 Information about LLVM's development process.
 373
 374 .. toctree::
 375    :hidden:
 376
 377    DeveloperPolicy
 378    MakefileGuide
 379    Projects
 380    LLVMBuild
 381    HowToReleaseLLVM
 382    Packaging
 383    ReleaseProcess
 384    Phabricator
 385
 386 :doc:`DeveloperPolicy`
 387    The LLVM project's policy towards developers and their contributions.
 388
 389 :doc:`Projects`
 390   How-to guide and templates for new projects that *use* the LLVM
 391   infrastructure.  The templates (directory organization, Makefiles, and test
 392   tree) allow the project code to be located outside (or inside) the ``llvm/``
 393   tree, while using LLVM header files and libraries.
 394
 395 :doc:`LLVMBuild`
 396   Describes the LLVMBuild organization and files used by LLVM to specify
 397   component descriptions.
 398
 399 :doc:`MakefileGuide`
 400   Describes how the LLVM makefiles work and how to use them.
 401
 402 :doc:`HowToReleaseLLVM`
 403   This is a guide to preparing LLVM releases. Most developers can ignore it.
 404
 405 :doc:`ReleaseProcess`
 406   This is a guide to validate a new release, during the release process. Most developers can ignore it.
 407
 408 :doc:`Packaging`
 409    Advice on packaging LLVM into a distribution.
 410
 411 :doc:`Phabricator`
 412    Describes how to use the Phabricator code review tool hosted on
 413    http://reviews.llvm.org/ and its command line interface, Arcanist.
 414
 415 Community
 416 =========
 417
 418 LLVM has a thriving community of friendly and helpful developers.
 419 The two primary communication mechanisms in the LLVM community are mailing
 420 lists and IRC.
 421
 422 Mailing Lists
 423 -------------
 424
 425 If you can't find what you need in these docs, try consulting the mailing
 426 lists.
 427
 428 `Developer's List (llvmdev)`__
 429   This list is for people who want to be included in technical discussions of
 430   LLVM. People post to this list when they have questions about writing code
 431   for or using the LLVM tools. It is relatively low volume.
 432
 433   .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
 434
 435 `Commits Archive (llvm-commits)`__
 436   This list contains all commit messages that are made when LLVM developers
 437   commit code changes to the repository. It also serves as a forum for
 438   patch review (i.e. send patches here). It is useful for those who want to
 439   stay on the bleeding edge of LLVM development. This list is very high
 440   volume.
 441
 442   .. __: http://lists.cs.uiuc.edu/pipermail/llvm-commits/
 443
 444 `Bugs & Patches Archive (llvmbugs)`__
 445   This list gets emailed every time a bug is opened and closed. It is
 446   higher volume than the LLVMdev list.
 447
 448   .. __: http://lists.cs.uiuc.edu/pipermail/llvmbugs/
 449
 450 `Test Results Archive (llvm-testresults)`__
 451   A message is automatically sent to this list by every active nightly tester
 452   when it completes.  As such, this list gets email several times each day,
 453   making it a high volume list.
 454
 455   .. __: http://lists.cs.uiuc.edu/pipermail/llvm-testresults/
 456
 457 `LLVM Announcements List (llvm-announce)`__
 458   This is a low volume list that provides important announcements regarding
 459   LLVM.  It gets email about once a month.
 460
 461   .. __: http://lists.cs.uiuc.edu/mailman/listinfo/llvm-announce
 462
 463 IRC
 464 ---
 465
 466 Users and developers of the LLVM project (including subprojects such as Clang)
 467 can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
 468
 469 This channel has several bots.
 470
 471 * Buildbot reporters
 472
 473   * llvmbb - Bot for the main LLVM buildbot master.
 474     http://lab.llvm.org:8011/console
 475   * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
 476   * smooshlab - Apple's internal buildbot master.
 477
 478 * robot - Bugzilla linker. %bug <number>
 479
 480 * clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
 481   near-trunk clang instead of gcc.
 482
 483
 484 Indices and tables
 485 ==================
 486
 487 * :ref:`genindex`
 488 * :ref:`search`