Skip to content

Commit

Permalink
[docs] Wordsmithing to program layout descriptio in GettingStarted
Browse files Browse the repository at this point in the history 
This just incrementally improves what was already there; it's questionable whether this content belongs in the getting started guide at all.

Patch by Ben Nathanson w/permission w/minor edtis by me.



git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@260040 91177308-0d34-0410-b5e6-96231b3b80d8
  • Loading branch information
@preames
preames committed Feb 7, 2016
1 parent 56df681 commit a22f43f
Showing 1 changed file with 63 additions and 97 deletions.
160 changes: 63 additions & 97 deletions docs/GettingStarted.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ Here's the short story for getting up and running quickly with LLVM:
`below`_.

Consult the `Getting Started with LLVM`_ section for detailed information on
configuring and compiling LLVM. Go to `Program Layout`_ to learn about the
configuring and compiling LLVM. Go to `Directory Layout`_ to learn about the
layout of the source code tree.

Requirements
Expand Down Expand Up @@ -936,152 +936,123 @@ use this command instead of the 'echo' command above:
.. _Program Layout:
.. _general layout:

Program Layout
==============
Directory Layout
================

One useful source of information about the LLVM source base is the LLVM `doxygen
<http://www.doxygen.org/>`_ documentation available at
<http://www.doxygen.org/>`_ documentation available at
`<http://llvm.org/doxygen/>`_. The following is a brief introduction to code
layout:

``llvm/examples``
-----------------

This directory contains some simple examples of how to use the LLVM IR and JIT.
Simple examples using the LLVM IR and JIT.

``llvm/include``
----------------

This directory contains public header files exported from the LLVM library. The
three main subdirectories of this directory are:
Public header files exported from the LLVM library. The three main subdirectories:

``llvm/include/llvm``

This directory contains all of the LLVM specific header files. This directory
also has subdirectories for different portions of LLVM: ``Analysis``,
``CodeGen``, ``Target``, ``Transforms``, etc...
All LLVM-specific header files, and subdirectories for different portions of
LLVM: ``Analysis``, ``CodeGen``, ``Target``, ``Transforms``, etc...

``llvm/include/llvm/Support``

This directory contains generic support libraries that are provided with LLVM
but not necessarily specific to LLVM. For example, some C++ STL utilities and
a Command Line option processing library store their header files here.
Generic support libraries provided with LLVM but not necessarily specific to
LLVM. For example, some C++ STL utilities and a Command Line option processing
library store header files here.

``llvm/include/llvm/Config``

This directory contains header files configured by the ``configure`` script.
Header files configured by the ``configure`` script.
They wrap "standard" UNIX and C header files. Source code can include these
header files which automatically take care of the conditional #includes that
the ``configure`` script generates.

``llvm/lib``
------------

This directory contains most of the source files of the LLVM system. In LLVM,
almost all code exists in libraries, making it very easy to share code among the
different `tools`_.
Most source files are here. By putting code in libraries, LLVM makes it easy to
share code among the `tools`_.

``llvm/lib/IR/``

This directory holds the core LLVM source files that implement core classes
like Instruction and BasicBlock.
Core LLVM source files that implement core classes like Instruction and
BasicBlock.

``llvm/lib/AsmParser/``

This directory holds the source code for the LLVM assembly language parser
library.
Source code for the LLVM assembly language parser library.

``llvm/lib/Bitcode/``

This directory holds code for reading and write LLVM bitcode.
Code for reading and writing bitcode.

``llvm/lib/Analysis/``

This directory contains a variety of different program analyses, such as
Dominator Information, Call Graphs, Induction Variables, Interval
Identification, Natural Loop Identification, etc.
A variety of program analyses, such as Call Graphs, Induction Variables,
Natural Loop Identification, etc.

``llvm/lib/Transforms/``

This directory contains the source code for the LLVM to LLVM program
transformations, such as Aggressive Dead Code Elimination, Sparse Conditional
Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global
Elimination, and many others.
IR-to-IR program transformations, such as Aggressive Dead Code Elimination,
Sparse Conditional Constant Propagation, Inlining, Loop Invariant Code Motion,
Dead Global Elimination, and many others.

``llvm/lib/Target/``

This directory contains files that describe various target architectures for
code generation. For example, the ``llvm/lib/Target/X86`` directory holds the
X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM
backend.
Files describing target architectures for code generation. For example,
``llvm/lib/Target/X86`` holds the X86 machine description.

``llvm/lib/CodeGen/``

This directory contains the major parts of the code generator: Instruction
Selector, Instruction Scheduling, and Register Allocation.
The major parts of the code generator: Instruction Selector, Instruction
Scheduling, and Register Allocation.

``llvm/lib/MC/``

(FIXME: T.B.D.)

``llvm/lib/Debugger/``

This directory contains the source level debugger library that makes it
possible to instrument LLVM programs so that a debugger could identify source
code locations at which the program is executing.
(FIXME: T.B.D.) ....?

``llvm/lib/ExecutionEngine/``

This directory contains libraries for executing LLVM bitcode directly at
runtime in both interpreted and JIT compiled fashions.
Libraries for directly executing bitcode at runtime in interpreted and
JIT-compiled scenarios.

``llvm/lib/Support/``

This directory contains the source code that corresponds to the header files
located in ``llvm/include/ADT/`` and ``llvm/include/Support/``.
Source code that corresponding to the header files in ``llvm/include/ADT/``
and ``llvm/include/Support/``.

``llvm/projects``
-----------------

This directory contains projects that are not strictly part of LLVM but are
shipped with LLVM. This is also the directory where you should create your own
LLVM-based projects.

``llvm/runtime``
----------------

This directory contains libraries which are compiled into LLVM bitcode and used
when linking programs with the Clang front end. Most of these libraries are
skeleton versions of real libraries; for example, libc is a stripped down
version of glibc.

Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end
to compile.
Projects not strictly part of LLVM but shipped with LLVM. This is also the
directory for creating your own LLVM-based projects which leverage the LLVM
build system.

``llvm/test``
-------------

This directory contains feature and regression tests and other basic sanity
checks on the LLVM infrastructure. These are intended to run quickly and cover a
lot of territory without being exhaustive.
Feature and regression tests and other sanity checks on LLVM infrastructure. These
are intended to run quickly and cover a lot of territory without being exhaustive.

``test-suite``
--------------

This is not a directory in the normal llvm module; it is a separate Subversion
module that must be checked out (usually to ``projects/test-suite``). This
module contains a comprehensive correctness, performance, and benchmarking test
suite for LLVM. It is a separate Subversion module because not every LLVM user
is interested in downloading or building such a comprehensive test suite. For
further details on this test suite, please see the :doc:`Testing Guide
A comprehensive correctness, performance, and benchmarking test suite for LLVM.
Comes in a separate Subversion module because not every LLVM user is interested
in such a comprehensive suite. For details see the :doc:`Testing Guide
<TestingGuide>` document.

.. _tools:

``llvm/tools``
--------------

The **tools** directory contains the executables built out of the libraries
Executables built out of the libraries
above, which form the main part of the user interface. You can always get help
for a tool by typing ``tool_name -help``. The following is a brief introduction
to the most important tools. More detailed information is in
Expand Down Expand Up @@ -1129,72 +1100,67 @@ the `Command Guide <CommandGuide/index.html>`_.
``opt``

``opt`` reads LLVM bitcode, applies a series of LLVM to LLVM transformations
(which are specified on the command line), and then outputs the resultant
bitcode. The '``opt -help``' command is a good way to get a list of the
(which are specified on the command line), and outputs the resultant
bitcode. '``opt -help``' is a good way to get a list of the
program transformations available in LLVM.

``opt`` can also be used to run a specific analysis on an input LLVM bitcode
file and print out the results. It is primarily useful for debugging
``opt`` can also run a specific analysis on an input LLVM bitcode
file and print the results. Primarily useful for debugging
analyses, or familiarizing yourself with what an analysis does.

``llvm/utils``
--------------

This directory contains utilities for working with LLVM source code, and some of
the utilities are actually required as part of the build process because they
are code generators for parts of LLVM infrastructure.
Utilities for working with LLVM source code; some are part of the build process
because they are code generators for parts of the infrastructure.


``codegen-diff``

``codegen-diff`` is a script that finds differences between code that LLC
generates and code that LLI generates. This is a useful tool if you are
``codegen-diff`` finds differences between code that LLC
generates and code that LLI generates. This is useful if you are
debugging one of them, assuming that the other generates correct output. For
the full user manual, run ```perldoc codegen-diff'``.

``emacs/``

The ``emacs`` directory contains syntax-highlighting files which will work
with Emacs and XEmacs editors, providing syntax highlighting support for LLVM
assembly files and TableGen description files. For information on how to use
the syntax files, consult the ``README`` file in that directory.
Emacs and XEmacs syntax highlighting for LLVM assembly files and TableGen
description files. See the ``README`` for information on using them.

``getsrcs.sh``

The ``getsrcs.sh`` script finds and outputs all non-generated source files,
which is useful if one wishes to do a lot of development across directories
and does not want to individually find each file. One way to use it is to run,
for example: ``xemacs `utils/getsources.sh``` from the top of your LLVM source
Finds and outputs all non-generated source files,
useful if one wishes to do a lot of development across directories
and does not want to find each file. One way to use it is to run,
for example: ``xemacs `utils/getsources.sh``` from the top of the LLVM source
tree.

``llvmgrep``

This little tool performs an ``egrep -H -n`` on each source file in LLVM and
Performs an ``egrep -H -n`` on each source file in LLVM and
passes to it a regular expression provided on ``llvmgrep``'s command
line. This is a very efficient way of searching the source base for a
line. This is an efficient way of searching the source base for a
particular regular expression.

``makellvm``

The ``makellvm`` script compiles all files in the current directory and then
Compiles all files in the current directory, then
compiles and links the tool that is the first argument. For example, assuming
you are in the directory ``llvm/lib/Target/Sparc``, if ``makellvm`` is in your
path, simply running ``makellvm llc`` will make a build of the current
you are in ``llvm/lib/Target/Sparc``, if ``makellvm`` is in your
path, running ``makellvm llc`` will make a build of the current
directory, switch to directory ``llvm/tools/llc`` and build it, causing a
re-linking of LLC.

``TableGen/``

The ``TableGen`` directory contains the tool used to generate register
Contains the tool used to generate register
descriptions, instruction set descriptions, and even assemblers from common
TableGen description files.

``vim/``

The ``vim`` directory contains syntax-highlighting files which will work with
the VIM editor, providing syntax highlighting support for LLVM assembly files
and TableGen description files. For information on how to use the syntax
files, consult the ``README`` file in that directory.
vim syntax-highlighting for LLVM assembly files
and TableGen description files. See the ``README`` for how to use them.

.. _simple example:

Expand Down

0 comments on commit a22f43f

Please sign in to comment.