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