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