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