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