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