Merge pull request #414 from ojeda/docs

Doc improvements

Author: ojeda

Documentation/rust/coding.rst

@@ -30,12 +30,12 @@ Typically, you will want to instruct your editor/IDE to format while you type,
 when you save or at commit time. However, if for some reason you want
 to reformat the entire kernel Rust sources at some point, you may run::
 
-	make rustfmt
+	make LLVM=1 rustfmt
 
 To check if everything is formatted (printing a diff otherwise), e.g. if you
 have configured a CI for a tree as a maintainer, you may run::
 
-	make rustfmtcheck
+	make LLVM=1 rustfmtcheck
 
 Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
 individual files, and does not require a kernel configuration. Sometimes it may
@@ -49,7 +49,7 @@ While ``rustc`` is a very helpful compiler, some extra lints and analysis are
 available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to
 the same invocation you use for compilation, e.g.::
 
-	make ARCH=... CROSS_COMPILE=... CC=... -j... CLIPPY=1
+	make LLVM=1 CLIPPY=1
 
 At the moment, we do not enforce a "clippy-free" compilation, so you can treat
 the output the same way as the extra warning levels for C, e.g. like ``W=2``.

Documentation/rust/docs.rst

@@ -38,7 +38,7 @@ This has the added advantage that they will be tailored to your particular
 kernel configuration. To generate them, simply use the ``rustdoc`` target with
 the same invocation you use for compilation, e.g.::
 
-	make ARCH=... CROSS_COMPILE=... CC=... -j... rustdoc
+	make LLVM=1 rustdoc
 
 
 Writing the docs

Documentation/rust/quick-start.rst

@@ -56,7 +56,7 @@ libclang
 ********
 
 ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
-in the kernel, which means you will need a recent LLVM installed; like when
+in the kernel, which means you will need an LLVM installed; like when
 you compile the kernel with ``CC=clang`` or ``LLVM=1``.
 
 Your Linux distribution is likely to have a suitable one available, so it is
@@ -66,20 +66,19 @@ There are also some binaries for several systems and architectures uploaded at:
 
     https://releases.llvm.org/download.html
 
-For Debian-based distributions, you can also fetch them from:
-
-    https://apt.llvm.org
-
 Otherwise, building LLVM takes quite a while, but it is not a complex process:
 
     https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
 
+See Documentation/kbuild/llvm.rst for more information and further ways
+to fetch pre-built releases and distribution packages.
+
 
 bindgen
 *******
 
 The bindings to the C side of the kernel are generated at build time using
-the ``bindgen`` tool. A recent version should work, e.g. ``0.56.0``.
+the ``bindgen`` tool. The version we currently support is ``0.56.0``.
 
 Install it via (this will build the tool from source)::
 
@@ -184,14 +183,14 @@ And enable some sample modules either as built-in or as loadable.
 Building
 --------
 
-Building a kernel with Clang or a complete LLVM toolchain is the best supported
-setup at the moment. That is::
+Building a kernel with a complete LLVM toolchain is the best supported setup
+at the moment. That is::
 
-    make ARCH=... CROSS_COMPILE=... CC=clang -j...
+    make LLVM=1
 
-or::
+For architectures that do not support a full LLVM toolchain, use::
 
-    make ARCH=... CROSS_COMPILE=... LLVM=1 -j...
+    make CC=clang
 
 Using GCC also works for some configurations, but it is *very* experimental at
 the moment.
@@ -209,7 +208,7 @@ is your toolchain doesn't support Rust's new v0 mangling scheme yet. There are
 a few ways out:
 
   - If you don't mind building your own tools, we provide the following fork
-    with the support cherry-picked from GCC on top of very recent releases:
+    with the support cherry-picked from GCC:
 
         https://github.com/Rust-for-Linux/binutils-gdb/releases/tag/gdb-10.1-release-rust
         https://github.com/Rust-for-Linux/binutils-gdb/releases/tag/binutils-2_35_1-rust