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