users-guide: Consistently document LLVM version requirement

(cherry picked from commit fdccc6666d838cf8708b9fc03a9ce2aa04fe9439)

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 246a278579..7c2f95444b 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 402e783ef1..936d7251dd 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 4d4704a769..ef7b9d51ba 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 113d1b022f..4ff77adc9d 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 169cb366d6..da8a84b25a 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