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