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   (`tarball <http://llvm.org/doxygen/doxygen.tar.gz>`_)
 220
 221 `Documentation for Go bindings <http://godoc.org/llvm.org/llvm/bindings/go/llvm>`_
 222
 223 `ViewVC Repository Browser <http://llvm.org/viewvc/>`_
 224    ..
 225
 226 :doc:`CompilerWriterInfo`
 227   A list of helpful links for compiler writers.
 228
 229 :doc:`LibFuzzer`
 230   A library for writing in-process guided fuzzers.
 231
 232 :doc:`ScudoHardenedAllocator`
 233   A library that implements a security-hardened `malloc()`.
 234
 235 :doc:`OptBisect`
 236   A command line option for debugging optimization-induced failures.
 237
 238 Subsystem Documentation
 239 =======================
 240
 241 For API clients and LLVM developers.
 242
 243 .. toctree::
 244    :hidden:
 245
 246    AliasAnalysis
 247    MemorySSA
 248    BitCodeFormat
 249    BlockFrequencyTerminology
 250    BranchWeightMetadata
 251    Bugpoint
 252    CodeGenerator
 253    ExceptionHandling
 254    LinkTimeOptimization
 255    SegmentedStacks
 256    TableGenFundamentals
 257    TableGen/index
 258    DebuggingJITedCode
 259    GoldPlugin
 260    MarkedUpDisassembly
 261    SystemLibrary
 262    SourceLevelDebugging
 263    Vectorizers
 264    WritingAnLLVMBackend
 265    GarbageCollection
 266    WritingAnLLVMPass
 267    HowToUseAttributes
 268    NVPTXUsage
 269    AMDGPUUsage
 270    StackMaps
 271    InAlloca
 272    BigEndianNEON
 273    CoverageMappingFormat
 274    Statepoints
 275    MergeFunctions
 276    TypeMetadata
 277    FaultMaps
 278    MIRLangRef
 279    Coroutines
 280    GlobalISel
 281    XRay
 282    XRayExample
 283    XRayFDRFormat
 284    PDB/index
 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 Development Process Documentation
 416 =================================
 417
 418 Information about LLVM's development process.
 419
 420 .. toctree::
 421    :hidden:
 422
 423    DeveloperPolicy
 424    Projects
 425    LLVMBuild
 426    HowToReleaseLLVM
 427    Packaging
 428    ReleaseProcess
 429    Phabricator
 430
 431 :doc:`DeveloperPolicy`
 432    The LLVM project's policy towards developers and their contributions.
 433
 434 :doc:`Projects`
 435   How-to guide and templates for new projects that *use* the LLVM
 436   infrastructure.  The templates (directory organization, Makefiles, and test
 437   tree) allow the project code to be located outside (or inside) the ``llvm/``
 438   tree, while using LLVM header files and libraries.
 439
 440 :doc:`LLVMBuild`
 441   Describes the LLVMBuild organization and files used by LLVM to specify
 442   component descriptions.
 443
 444 :doc:`HowToReleaseLLVM`
 445   This is a guide to preparing LLVM releases. Most developers can ignore it.
 446
 447 :doc:`ReleaseProcess`
 448   This is a guide to validate a new release, during the release process. Most developers can ignore it.
 449
 450 :doc:`Packaging`
 451    Advice on packaging LLVM into a distribution.
 452
 453 :doc:`Phabricator`
 454    Describes how to use the Phabricator code review tool hosted on
 455    http://reviews.llvm.org/ and its command line interface, Arcanist.
 456
 457 Community
 458 =========
 459
 460 LLVM has a thriving community of friendly and helpful developers.
 461 The two primary communication mechanisms in the LLVM community are mailing
 462 lists and IRC.
 463
 464 Mailing Lists
 465 -------------
 466
 467 If you can't find what you need in these docs, try consulting the mailing
 468 lists.
 469
 470 `Developer's List (llvm-dev)`__
 471   This list is for people who want to be included in technical discussions of
 472   LLVM. People post to this list when they have questions about writing code
 473   for or using the LLVM tools. It is relatively low volume.
 474
 475   .. __: http://lists.llvm.org/mailman/listinfo/llvm-dev
 476
 477 `Commits Archive (llvm-commits)`__
 478   This list contains all commit messages that are made when LLVM developers
 479   commit code changes to the repository. It also serves as a forum for
 480   patch review (i.e. send patches here). It is useful for those who want to
 481   stay on the bleeding edge of LLVM development. This list is very high
 482   volume.
 483
 484   .. __: http://lists.llvm.org/pipermail/llvm-commits/
 485
 486 `Bugs & Patches Archive (llvm-bugs)`__
 487   This list gets emailed every time a bug is opened and closed. It is
 488   higher volume than the LLVM-dev list.
 489
 490   .. __: http://lists.llvm.org/pipermail/llvm-bugs/
 491
 492 `Test Results Archive (llvm-testresults)`__
 493   A message is automatically sent to this list by every active nightly tester
 494   when it completes.  As such, this list gets email several times each day,
 495   making it a high volume list.
 496
 497   .. __: http://lists.llvm.org/pipermail/llvm-testresults/
 498
 499 `LLVM Announcements List (llvm-announce)`__
 500   This is a low volume list that provides important announcements regarding
 501   LLVM.  It gets email about once a month.
 502
 503   .. __: http://lists.llvm.org/mailman/listinfo/llvm-announce
 504
 505 IRC
 506 ---
 507
 508 Users and developers of the LLVM project (including subprojects such as Clang)
 509 can be found in #llvm on `irc.oftc.net <irc://irc.oftc.net/llvm>`_.
 510
 511 This channel has several bots.
 512
 513 * Buildbot reporters
 514
 515   * llvmbb - Bot for the main LLVM buildbot master.
 516     http://lab.llvm.org:8011/console
 517   * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
 518   * smooshlab - Apple's internal buildbot master.
 519
 520 * robot - Bugzilla linker. %bug <number>
 521
 522 * clang-bot - A `geordi <http://www.eelis.net/geordi/>`_ instance running
 523   near-trunk clang instead of gcc.
 524
 525 Community wide proposals
 526 ------------------------
 527
 528 Proposals for massive changes in how the community behaves and how the work flow
 529 can be better.
 530
 531 .. toctree::
 532    :hidden:
 533
 534    CodeOfConduct
 535    Proposals/GitHubMove
 536    Proposals/VectorizationPlan
 537
 538 :doc:`CodeOfConduct`
 539    Proposal to adopt a code of conduct on the LLVM social spaces (lists, events,
 540    IRC, etc).
 541
 542 :doc:`Proposals/GitHubMove`
 543    Proposal to move from SVN/Git to GitHub.
 544
 545 :doc:`Proposals/VectorizationPlan`
 546    Proposal to model the process and upgrade the infrastructure of LLVM's Loop Vectorizer.
 547
 548 Indices and tables
 549 ==================
 550
 551 * :ref:`genindex`
 552 * :ref:`search`