summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDimitry Andric <dim@FreeBSD.org>2019-02-15 20:48:51 +0000
committerDimitry Andric <dim@FreeBSD.org>2019-02-15 20:48:51 +0000
commit519e1985aef0136fe593e52b5404e2934b077115 (patch)
tree2ed0abe9c0ca3ad3309b537d91c64bc91c8f0176 /docs
parente79719ce607b6130e41e23dbdc90cc6b4e0401e6 (diff)
Notes
Diffstat (limited to 'docs')
-rw-r--r--docs/CMake.rst9
-rw-r--r--docs/DeveloperPolicy.rst43
-rw-r--r--docs/GettingStarted.rst61
-rw-r--r--docs/LibFuzzer.rst14
-rw-r--r--docs/ReleaseNotes.rst33
5 files changed, 132 insertions, 28 deletions
diff --git a/docs/CMake.rst b/docs/CMake.rst
index a5a574e570777..eb219c58560b6 100644
--- a/docs/CMake.rst
+++ b/docs/CMake.rst
@@ -573,6 +573,15 @@ LLVM-specific variables
options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
variables, respectively.
+**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL
+ If enabled, the compiler and standard library versions won't be checked. LLVM
+ may not compile at all, or might fail at runtime due to known bugs in these
+ toolchains.
+
+**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL
+ If enabled, the compiler version check will only warn when using a toolchain
+ which is about to be deprecated, instead of emitting an error.
+
CMake Caches
============
diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst
index 09912940cde2d..4ed67cbf1ef1d 100644
--- a/docs/DeveloperPolicy.rst
+++ b/docs/DeveloperPolicy.rst
@@ -22,7 +22,7 @@ This policy is also designed to accomplish the following objectives:
#. Make life as simple and easy for contributors as possible.
-#. Keep the tip of tree as stable as possible.
+#. Keep the top of tree as stable as possible.
#. Establish awareness of the project's :ref:`copyright, license, and patent
policies <copyright-license-patents>` with contributors to the project.
@@ -638,6 +638,47 @@ In essences, these rules are necessary for targets to gain and retain their
status, but also markers to define bit-rot, and will be used to clean up the
tree from unmaintained targets.
+.. _toolchain:
+
+Updating Toolchain Requirements
+-------------------------------
+
+We intend to require newer toolchains as time goes by. This means LLVM's
+codebase can use newer versions of C++ as they get standardized. Requiring newer
+toolchains to build LLVM can be painful for those building LLVM; therefore, it
+will only be done through the following process:
+
+ * Generally, try to support LLVM and GCC versions from the last 3 years at a
+ minimum. This time-based guideline is not strict: we may support much older
+ compilers, or decide to support fewer versions.
+
+ * An RFC is sent to the `llvm-dev mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_
+
+ - Detail upsides of the version increase (e.g. which newer C++ language or
+ library features LLVM should use; avoid miscompiles in particular compiler
+ versions, etc).
+ - Detail downsides on important platforms (e.g. Ubuntu LTS status).
+
+ * Once the RFC reaches consensus, update the CMake toolchain version checks as
+ well as the :doc:`getting started<GettingStarted>` guide. We want to
+ soft-error when developers compile LLVM. We say "soft-error" because the
+ error can be turned into a warning using a CMake flag. This is an important
+ step: LLVM still doesn't have code which requires the new toolchains, but it
+ soon will. If you compile LLVM but don't read the mailing list, we should
+ tell you!
+
+ * Ensure that at least one LLVM release has had this soft-error. Not all
+ developers compile LLVM top-of-tree. These release-bound developers should
+ also be told about upcoming changes.
+
+ * Turn the soft-error into a hard-error after said LLVM release has branched.
+
+ * Update the :doc:`coding standards<CodingStandards>` to allow the new
+ features we've explicitly approved in the RFC.
+
+ * Start using the new features in LLVM's codebase.
+
+
.. _copyright-license-patents:
Copyright, License, and Patents
diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst
index b714cc6601a04..c22e821e3b7a0 100644
--- a/docs/GettingStarted.rst
+++ b/docs/GettingStarted.rst
@@ -170,7 +170,7 @@ uses the package and provides other details.
Package Version Notes
=========================================================== ============ ==========================================
`GNU Make <http://savannah.gnu.org/projects/make>`_ 3.79, 3.79.1 Makefile/build processor
-`GCC <http://gcc.gnu.org/>`_ >=4.8.0 C/C++ compiler\ :sup:`1`
+`GCC <http://gcc.gnu.org/>`_ >=5.1.0 C/C++ compiler\ :sup:`1`
`python <http://www.python.org/>`_ >=2.7 Automated test suite\ :sup:`2`
`zlib <http://zlib.net>`_ >=1.2.3.4 Compression library\ :sup:`3`
=========================================================== ============ ==========================================
@@ -220,15 +220,25 @@ Host C++ Toolchain, both Compiler and Standard Library
------------------------------------------------------
LLVM is very demanding of the host C++ compiler, and as such tends to expose
-bugs in the compiler. We are also planning to follow improvements and
-developments in the C++ language and library reasonably closely. As such, we
-require a modern host C++ toolchain, both compiler and standard library, in
-order to build LLVM.
+bugs in the compiler. We also attempt to follow improvements and developments in
+the C++ language and library reasonably closely. As such, we require a modern
+host C++ toolchain, both compiler and standard library, in order to build LLVM.
-For the most popular host toolchains we check for specific minimum versions in
-our build systems:
+LLVM is written using the subset of C++ documented in :doc:`coding
+standards<CodingStandards>`. To enforce this language version, we check the most
+popular host toolchains for specific minimum versions in our build systems:
+
+* Clang 3.5
+* Apple Clang 6.0
+* GCC 5.1
+* Visual Studio 2017
+
+The below versions currently soft-error as we transition to the new compiler
+versions listed above. The LLVM codebase is currently known to compile correctly
+with the following compilers, though this will change in the near future:
* Clang 3.1
+* Apple Clang 3.1
* GCC 4.8
* Visual Studio 2015 (Update 3)
@@ -282,33 +292,36 @@ The first step is to get a recent GCC toolchain installed. The most common
distribution on which users have struggled with the version requirements is
Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
the `toolchain testing PPA`_ and use it to install a modern GCC. There is
-a really nice discussions of this on the `ask ubuntu stack exchange`_. However,
-not all users can use PPAs and there are many other distributions, so it may be
-necessary (or just useful, if you're here you *are* doing compiler development
-after all) to build and install GCC from source. It is also quite easy to do
-these days.
+a really nice discussions of this on the `ask ubuntu stack exchange`_ and a
+`github gist`_ with updated commands. However, not all users can use PPAs and
+there are many other distributions, so it may be necessary (or just useful, if
+you're here you *are* doing compiler development after all) to build and install
+GCC from source. It is also quite easy to do these days.
.. _toolchain testing PPA:
https://launchpad.net/~ubuntu-toolchain-r/+archive/test
.. _ask ubuntu stack exchange:
- http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal
+ https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149
+.. _github gist:
+ https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91
-Easy steps for installing GCC 4.8.2:
+Easy steps for installing GCC 5.1.0:
.. code-block:: console
- % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
- % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2.sig
+ % gcc_version=5.1.0
+ % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2
+ % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig
% wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
- % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-4.8.2.tar.bz2.sig`
+ % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-${gcc_version}.tar.bz2.sig`
% if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi
- % tar -xvjf gcc-4.8.2.tar.bz2
- % cd gcc-4.8.2
+ % tar -xvjf gcc-${gcc_version}.tar.bz2
+ % cd gcc-${gcc_version}
% ./contrib/download_prerequisites
% cd ..
- % mkdir gcc-4.8.2-build
- % cd gcc-4.8.2-build
- % $PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+ % mkdir gcc-${gcc_version}-build
+ % cd gcc-${gcc_version}-build
+ % $PWD/../gcc-${gcc_version}/configure --prefix=$HOME/toolchains --enable-languages=c,c++
% make -j$(nproc)
% make install
@@ -316,7 +329,7 @@ For more details, check out the excellent `GCC wiki entry`_, where I got most
of this information from.
.. _GCC wiki entry:
- http://gcc.gnu.org/wiki/InstallingGCC
+ https://gcc.gnu.org/wiki/InstallingGCC
Once you have a GCC toolchain, configure your build of LLVM to use the new
toolchain for your host compiler and C++ standard library. Because the new
@@ -336,7 +349,7 @@ If you fail to set rpath, most LLVM binaries will fail on startup with a message
from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not
found``. This means you need to tweak the -rpath linker flag.
-When you build Clang, you will need to give *it* access to modern C++11
+When you build Clang, you will need to give *it* access to modern C++
standard library in order to use it as your new host in part of a bootstrap.
There are two easy ways to do this, either build (and install) libc++ along
with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
diff --git a/docs/LibFuzzer.rst b/docs/LibFuzzer.rst
index 0737fbbcd9305..37b0833599a94 100644
--- a/docs/LibFuzzer.rst
+++ b/docs/LibFuzzer.rst
@@ -645,10 +645,20 @@ coverage set of the process (since the fuzzer is in-process). In other words, by
using more external dependencies we will slow down the fuzzer while the main
reason for it to exist is extreme speed.
-Q. What about Windows then? The fuzzer contains code that does not build on Windows.
+Q. Does libFuzzer Support Windows?
------------------------------------------------------------------------------------
-Volunteers are welcome.
+Yes, libFuzzer now supports Windows. Initial support was added in r341082.
+You can download a build of Clang for Windows
+that has libFuzzer from
+`LLVM Snapshot Builds <https://llvm.org/builds/>`_.
+
+Using libFuzzer on Windows without ASAN is unsupported. Building fuzzers with the
+``/MD`` (dynamic runtime library) compile option is unsupported. Support for these
+may be added in the future. Linking fuzzers with the ``/INCREMENTAL`` link option
+(or the ``/DEBUG`` option which implies it) is also unsupported.
+
+Send any questions or comments to the mailing list: libfuzzer(#)googlegroups.com
Q. When libFuzzer is not a good solution for a problem?
---------------------------------------------------------
diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index 2bd435ca9d296..9e2ee95c65194 100644
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -40,6 +40,22 @@ Non-comprehensive list of changes in this release
functionality, or simply have a lot to talk about), see the `NOTE` below
for adding a new subsection.
+* As `discussed on the mailing list
+ <https://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html>`_,
+ building LLVM will soon require more recent toolchains as follows:
+
+ ============= ====
+ Clang 3.5
+ Apple Clang 6.0
+ GCC 5.1
+ Visual Studio 2017
+ ============= ====
+
+ A new CMake check when configuring LLVM provides a soft-error if your
+ toolchain will become unsupported soon. You can opt out of the soft-error by
+ setting the ``LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN`` CMake variable to
+ ``ON``.
+
* The **llvm-cov** tool can now export lcov trace files using the
`-format=lcov` option of the `export` command.
@@ -82,7 +98,7 @@ Changes to the ARM Backend
Changes to the Hexagon Target
---------------------------
+-----------------------------
* Added support for Hexagon/HVX V66 ISA.
@@ -156,6 +172,21 @@ Changes to the DAG infrastructure
External Open Source Projects Using LLVM 8
==========================================
+LDC - the LLVM-based D compiler
+-------------------------------
+
+`D <http://dlang.org>`_ is a language with C-like syntax and static typing. It
+pragmatically combines efficiency, control, and modeling power, with safety and
+programmer productivity. D supports powerful concepts like Compile-Time Function
+Execution (CTFE) and Template Meta-Programming, provides an innovative approach
+to concurrency and offers many classical paradigms.
+
+`LDC <http://wiki.dlang.org/LDC>`_ uses the frontend from the reference compiler
+combined with LLVM as backend to produce efficient native code. LDC targets
+x86/x86_64 systems like Linux, OS X, FreeBSD and Windows and also Linux on ARM
+and PowerPC (32/64 bit). Ports to other architectures like AArch64 and MIPS64
+are underway.
+
Zig Programming Language
------------------------