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