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