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