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