AcoSail/llvm-project
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[docs] Update README and GettingStarted

Browse Source 
Funnel fetching and building LLVM instructions into GettingStarted.

Modernize the build steps a little.

Remove comments saying CMAKE_BUILD_TYPE defaults to Debug as that's not true anymore (must explicitly pass it).

Reviewed By: MaskRay, hans

Differential Revision: https://reviews.llvm.org/D145413
This commit is contained in:
Arthur Eubanks 2023-03-06 11:45:23 -08:00
parent 2afce71fcf
commit 65548ff349
3 changed files with 51 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@ -1,27 +1,16 @@
# The LLVM Compiler Infrastructure # The LLVM Compiler Infrastructure
This directory and its sub-directories contain the source code for LLVM,
a toolkit for the construction of highly optimized compilers,
optimizers, and run-time environments.
The README briefly describes how to get started with building LLVM.
For more information on how to contribute to the LLVM project, please
take a look at the
[Contributing to LLVM](https://llvm.org/docs/Contributing.html) guide.
## Getting Started with the LLVM System
Taken from [here](https://llvm.org/docs/GettingStarted.html).
### Overview
Welcome to the LLVM project! Welcome to the LLVM project!
This repository contains the source code for LLVM, a toolkit for the
construction of highly optimized compilers, optimizers, and run-time
environments.
The LLVM project has multiple components. The core of the project is The LLVM project has multiple components. The core of the project is
itself called "LLVM". This contains all of the tools, libraries, and header itself called "LLVM". This contains all of the tools, libraries, and header
files needed to process intermediate representations and convert them into files needed to process intermediate representations and convert them into
object files. Tools include an assembler, disassembler, bitcode analyzer, and object files. Tools include an assembler, disassembler, bitcode analyzer, and
bitcode optimizer. It also contains basic regression tests. bitcode optimizer.
C-like languages use the [Clang](http://clang.llvm.org/) frontend. This C-like languages use the [Clang](http://clang.llvm.org/) frontend. This
component compiles C, C++, Objective-C, and Objective-C++ code into LLVM bitcode component compiles C, C++, Objective-C, and Objective-C++ code into LLVM bitcode
@ -31,92 +20,20 @@ Other components include:
the [libc++ C++ standard library](https://libcxx.llvm.org), the [libc++ C++ standard library](https://libcxx.llvm.org),
the [LLD linker](https://lld.llvm.org), and more. the [LLD linker](https://lld.llvm.org), and more.
### Getting the Source Code and Building LLVM ## Getting the Source Code and Building LLVM
The LLVM Getting Started documentation may be out of date. The [Clang
Getting Started](http://clang.llvm.org/get_started.html) page might have more
accurate information.
This is an example work-flow and configuration to get and build the LLVM source:
1. Checkout LLVM (including related sub-projects like Clang):
* ``git clone https://github.com/llvm/llvm-project.git``
* Or, on windows, ``git clone --config core.autocrlf=false
https://github.com/llvm/llvm-project.git``
2. Configure and build LLVM and Clang:
* ``cd llvm-project``
* ``cmake -S llvm -B build -G <generator> [options]``
Some common build system generators are:
* ``Ninja`` --- for generating [Ninja](https://ninja-build.org)
build files. Most llvm developers use Ninja.
* ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
* ``Visual Studio`` --- for generating Visual Studio projects and
solutions.
* ``Xcode`` --- for generating Xcode projects.
Some common options:
* ``-DLLVM_ENABLE_PROJECTS='...'`` and ``-DLLVM_ENABLE_RUNTIMES='...'`` ---
semicolon-separated list of the LLVM sub-projects and runtimes you'd like to
additionally build. ``LLVM_ENABLE_PROJECTS`` can include any of: clang,
clang-tools-extra, cross-project-tests, flang, libc, libclc, lld, lldb,
mlir, openmp, polly, or pstl. ``LLVM_ENABLE_RUNTIMES`` can include any of
libcxx, libcxxabi, libunwind, compiler-rt, libc or openmp. Some runtime
projects can be specified either in ``LLVM_ENABLE_PROJECTS`` or in
``LLVM_ENABLE_RUNTIMES``.
For example, to build LLVM, Clang, libcxx, and libcxxabi, use
``-DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
* ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
path name of where you want the LLVM tools and libraries to be installed
(default ``/usr/local``). Be careful if you install runtime libraries: if
your system uses those provided by LLVM (like libc++ or libc++abi), you
must not overwrite your system's copy of those libraries, since that
could render your system unusable. In general, using something like
``/usr`` is not advised, but ``/usr/local`` is fine.
* ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
* ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
(default is Yes for Debug builds, No for all other build types).
* ``cmake --build build [-- [options] <target>]`` or your build system specified above
directly.
* The default target (i.e. ``ninja`` or ``make``) will build all of LLVM.
* The ``check-all`` target (i.e. ``ninja check-all``) will run the
regression tests to ensure everything is in working order.
* CMake will generate targets for each tool and library, and most
LLVM sub-projects generate their own ``check-<project>`` target.
* Running a serial build will be **slow**. To improve speed, try running a
parallel build. That's done by default in Ninja; for ``make``, use the option
``-j NNN``, where ``NNN`` is the number of parallel jobs to run.
In most cases, you get the best performance if you specify the number of CPU threads you have.
On some Unix systems, you can specify this with ``-j$(nproc)``.
* For more information see [CMake](https://llvm.org/docs/CMake.html).
Consult the Consult the
[Getting Started with LLVM](https://llvm.org/docs/GettingStarted.html#getting-started-with-llvm) [Getting Started with LLVM](https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm)
page for detailed information on configuring and compiling LLVM. You can visit page for information on building and running LLVM.
[Directory Layout](https://llvm.org/docs/GettingStarted.html#directory-layout)
to learn about the layout of the source code tree. For information on how to contribute to the LLVM project, please take a look at
the [Contributing to LLVM](https://llvm.org/docs/Contributing.html) guide.
## Getting in touch ## Getting in touch
Join [LLVM Discourse forums](https://discourse.llvm.org/), [discord chat](https://discord.gg/xS7Z362) or #llvm IRC channel on [OFTC](https://oftc.net/). Join the [LLVM Discourse forums](https://discourse.llvm.org/), [Discord
chat](https://discord.gg/xS7Z362), or #llvm IRC channel on
[OFTC](https://oftc.net/).
The LLVM project has adopted a [code of conduct](https://llvm.org/docs/CodeOfConduct.html) for The LLVM project has adopted a [code of conduct](https://llvm.org/docs/CodeOfConduct.html) for
participants to all modes of communication within the project. participants to all modes of communication within the project.

3
llvm/docs/CMake.rst
View File

@ -191,9 +191,6 @@ used variables that control features of LLVM and enabled subprojects.
**CMAKE_BUILD_TYPE**:STRING **CMAKE_BUILD_TYPE**:STRING
This configures the optimization level for ``make`` or ``ninja`` builds. This configures the optimization level for ``make`` or ``ninja`` builds.
The default ``CMAKE_BUILD_TYPE`` is set to ``Debug`` but you should
carefully read the list below to figure out what configuration matches
your use case the best.
Possible values: Possible values:

64
llvm/docs/GettingStarted.rst
View File

@ -27,28 +27,23 @@ the `LLD linker <https://lld.llvm.org>`_, and more.
Getting the Source Code and Building LLVM Getting the Source Code and Building LLVM
========================================= =========================================
The LLVM Getting Started documentation may be out of date. The `Clang #. Check out LLVM (including subprojects like Clang):
Getting Started <https://clang.llvm.org/get_started.html>`_ page might have more
accurate information.
This is an example workflow and configuration to get and build the LLVM source:
#. Checkout LLVM (including related subprojects like Clang):
* ``git clone https://github.com/llvm/llvm-project.git`` * ``git clone https://github.com/llvm/llvm-project.git``
* Or, on windows, ``git clone --config core.autocrlf=false * Or, on windows:
``git clone --config core.autocrlf=false
https://github.com/llvm/llvm-project.git`` https://github.com/llvm/llvm-project.git``
* To save storage and speed-up the checkout time, you may want to do a * To save storage and speed-up the checkout time, you may want to do a
`shallow clone <https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt>`_. `shallow clone <https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt>`_.
For example, to get the latest revision of the LLVM project, use For example, to get the latest revision of the LLVM project, use
``git clone --depth 1 https://github.com/llvm/llvm-project.git`` ``git clone --depth 1 https://github.com/llvm/llvm-project.git``
#. Configure and build LLVM and Clang: #. Configure and build LLVM and Clang:
* ``cd llvm-project`` * ``cd llvm-project``
* ``mkdir build`` * ``cmake -S llvm -B build -G <generator> [options]``
* ``cd build``
* ``cmake -G <generator> -DCMAKE_BUILD_TYPE=<type> [options] ../llvm``
Some common build system generators are: Some common build system generators are:
@ -59,27 +54,30 @@ This is an example workflow and configuration to get and build the LLVM source:
solutions. solutions.
* ``Xcode`` --- for generating Xcode projects. * ``Xcode`` --- for generating Xcode projects.
Some Common options: * See the `CMake docs
<https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_
for a more comprehensive list.
Some common options:
* ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
subprojects you'd like to additionally build. Can include any of: clang, subprojects you'd like to additionally build. Can include any of: clang,
clang-tools-extra, lldb, compiler-rt, lld, polly, or cross-project-tests. clang-tools-extra, lldb, lld, polly, or cross-project-tests.
For example, to build LLVM, Clang, libcxx, and libcxxabi, use For example, to build LLVM, Clang, and LLD, use
``-DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``. ``-DLLVM_ENABLE_PROJECTS="clang;lld"``.
* ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
pathname of where you want the LLVM tools and libraries to be installed pathname of where you want the LLVM tools and libraries to be installed
(default ``/usr/local``). (default ``/usr/local``).
* ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug information * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug
of the build. The default value is ``Debug`` which fits people who want information of the build. Valid options for *type* are ``Debug``,
to work on LLVM or its libraries. ``Release`` is a better fit for most ``Release``, ``RelWithDebInfo``, and ``MinSizeRel``. For more detailed
users of LLVM and Clang. For more detailed information see information see :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`.
:ref:`CMAKE_BUILD_TYPE <cmake_build_type>`.
* ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled * ``-DLLVM_ENABLE_ASSERTIONS=ON`` --- Compile with assertion checks enabled
(default is Yes for Debug builds, No for all other build types). (default is ON for Debug builds, OFF for all other build types).
* ``cmake --build . [--target <target>]`` or the build system specified * ``cmake --build . [--target <target>]`` or the build system specified
above directly. above directly.
@ -98,10 +96,19 @@ This is an example workflow and configuration to get and build the LLVM source:
option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the
number of available CPUs. number of available CPUs.
* For more information see `CMake <CMake.html>`__ * A basic CMake and build/test invocation which only builds LLVM and no other
subprojects:
* If you get an "internal compiler error (ICE)" or test failures, see ``cmake -S llvm -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug``
`below`_.
``ninja -C build check-llvm``
This will setup an LLVM build with debugging info, then compile LLVM and
run LLVM tests.
* For more detailed information on CMake options, see `CMake <CMake.html>`__
* If you get build or test failures, see `below`_.
Consult the `Getting Started with LLVM`_ section for detailed information on Consult the `Getting Started with LLVM`_ section for detailed information on
configuring and compiling LLVM. Go to `Directory Layout`_ to learn about the configuring and compiling LLVM. Go to `Directory Layout`_ to learn about the
@ -601,8 +608,11 @@ used by people developing LLVM.
| | out-of-tree targets. The default value includes: | | | out-of-tree targets. The default value includes: |
| | ``AArch64, AMDGPU, ARM, AVR, BPF, Hexagon, Lanai, | | | ``AArch64, AMDGPU, ARM, AVR, BPF, Hexagon, Lanai, |
| | Mips, MSP430, NVPTX, PowerPC, RISCV, Sparc, | | | Mips, MSP430, NVPTX, PowerPC, RISCV, Sparc, |
| | SystemZ, WebAssembly, X86, XCore``. | | | SystemZ, WebAssembly, X86, XCore``. Setting this |
| | | | | to ``"host"`` will only compile the host |
| | architecture (e.g. equivalent to specifying ``X86``|
| | on an x86 host machine) can |
| | significantly speed up compile and test times. |
+-------------------------+----------------------------------------------------+ +-------------------------+----------------------------------------------------+
| LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source | | LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source |
| | code This is disabled by default because it is | | | code This is disabled by default because it is |