[commit: ghc] ghc-8.4: users-guide: Consistently document LLVM version requirement (fdccc66)

Thu Dec 14 22:05:10 UTC 2017

Repository : ssh://git@git.haskell.org/ghc

On branch  : ghc-8.4
Link       : http://ghc.haskell.org/trac/ghc/changeset/fdccc6666d838cf8708b9fc03a9ce2aa04fe9439/ghc

>---------------------------------------------------------------

commit fdccc6666d838cf8708b9fc03a9ce2aa04fe9439
Author: Ben Gamari <ben at smart-cactus.org>
Date:   Thu Dec 14 13:44:52 2017 -0500

    users-guide: Consistently document LLVM version requirement


>---------------------------------------------------------------

fdccc6666d838cf8708b9fc03a9ce2aa04fe9439
 docs/users_guide/8.4.1-notes.rst  |  3 +++
 docs/users_guide/codegens.rst     | 15 ++++++++++-----
 docs/users_guide/conf.py          |  4 ++++
 docs/users_guide/ghc_config.py.in |  2 ++
 docs/users_guide/phases.rst       |  5 +++++
 5 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/docs/users_guide/8.4.1-notes.rst b/docs/users_guide/8.4.1-notes.rst
index 246a278..7c2f954 100644
--- a/docs/users_guide/8.4.1-notes.rst
+++ b/docs/users_guide/8.4.1-notes.rst
@@ -108,6 +108,9 @@ Language
 Compiler
 ~~~~~~~~
 
+- LLVM code generator (e.g. :ghc-flag:`-fllvm`) compatible with LLVM releases in
+  the |llvm-version| series.
+
 - Add warning flag :ghc-flag:`-Wmissing-export-lists` which causes the type
   checker to warn when a module does not include an explicit export list.
 
diff --git a/docs/users_guide/codegens.rst b/docs/users_guide/codegens.rst
index 402e783..936d725 100644
--- a/docs/users_guide/codegens.rst
+++ b/docs/users_guide/codegens.rst
@@ -40,7 +40,7 @@ performance as good as the native code generator but for some cases can
 produce much faster code. This is especially true for numeric, array
 heavy code using packages like vector. The penalty is a significant
 increase in compilation times. Select the LLVM backend with the
-``-fllvm`` flag. Currently *LLVM 2.8* and later are supported.
+:ghc-flag:`-fllvm` flag.
 
 You must install and have LLVM available on your ``PATH`` for the LLVM code
 generator to work. Specifically GHC needs to be able to call the ``opt``
@@ -48,12 +48,17 @@ and ``llc`` tools. Secondly, if you are running Mac OS X with LLVM 3.0
 or greater then you also need the `Clang C
 compiler <http://clang.llvm.org>`__ compiler available on your ``PATH``.
 
+.. note::
+
+    Note that this GHC release expects an LLVM version in the |llvm-version|
+    release series.
+
 To install LLVM and Clang:
 
 -  *Linux*: Use your package management tool.
 
 -  *Mac OS X*: Clang is included by default on recent OS X machines when
-   XCode is installed (from ``10.6`` and later). LLVM is not included.
+   XCode is installed (from 10.6 and later). LLVM is not included.
    In order to use the LLVM based code generator, you should install the
    `Homebrew <http://mxcl.github.com/homebrew/>`__ package manager for
    OS X. Alternatively you can download binaries for LLVM and Clang from
@@ -73,7 +78,7 @@ C Code Generator (``-fvia-C``)
 
 This is the oldest code generator in GHC and is generally not included
 any more having been deprecated around GHC 7.0. Select it with the
-``-fvia-C`` flag.
+:ghc-flag:`-fvia-C` flag.
 
 The C code generator is only supported when GHC is built in
 unregisterised mode, a mode where GHC produces "portable" C code as
@@ -81,7 +86,7 @@ output to facilitate porting GHC itself to a new platform. This mode
 produces much slower code though so it's unlikely your version of GHC
 was built this way. If it has then the native code generator probably
 won't be available. You can check this information by calling
-``ghc --info`` (see :ref:`ghc-info`).
+``ghc --info`` (see :ghc-flag:`--info`).
 
 .. _unreg:
 
@@ -112,4 +117,4 @@ to build GHC with the appropriate options set. Consult the GHC Building
 Guide for details.
 
 You can check if your GHC is unregisterised by calling
-``ghc --info`` (see :ref:`ghc-info`).
+``ghc --info`` (see :ghc-flag:`--info`).
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
index 4d4704a..ef7b9d5 100644
--- a/docs/users_guide/conf.py
+++ b/docs/users_guide/conf.py
@@ -24,6 +24,10 @@ source_suffix = '.rst'
 source_encoding = 'utf-8-sig'
 master_doc = 'index'
 
+rst_prolog = """
+.. |llvm-version| replace:: {llvm_version}
+""".format(llvm_version=ghc_config.llvm_version)
+
 # General information about the project.
 project = u'Glasgow Haskell Compiler'
 copyright = u'2015, GHC Team'
diff --git a/docs/users_guide/ghc_config.py.in b/docs/users_guide/ghc_config.py.in
index 113d1b0..4ff77ad 100644
--- a/docs/users_guide/ghc_config.py.in
+++ b/docs/users_guide/ghc_config.py.in
@@ -16,3 +16,5 @@ lib_versions = {
 }
 
 version = '@ProjectVersion@'
+
+llvm_version = '@LlvmVersion@'
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 169cb36..da8a84b 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -527,6 +527,11 @@ Options affecting code generation
     via LLVM requires LLVM's :command:`opt` and :command:`llc` executables to be
     in :envvar:`PATH`.
 
+    .. note::
+
+        Note that this GHC release expects an LLVM version in the |llvm-version|
+        release series.
+
 .. ghc-flag:: -fno-code
     :shortdesc: Omit code generation
     :type: dynamic

