Repository: mun-lang/mun (language: rust)

Issue:
Arch Linux build info out of date
With  #254 the build instructions for ArchLinux are out of date (Since we require LLVM8 now). We should update these, but it also requires that we create and upload a package for lld8.


Discussion / hints:
@jakbyte Since you created the build instructions for Arch previously, would you be interested in picking this up?
Unfortunately, it looks like the `llvm8` AUR package that already exists [doesn't build without a workaround](https://aur.archlinux.org/packages/llvm8#comment-745687). I can't make an `lld8` package without that package being fixed.
@wackbyte I noticed there have been some changes to the `llvm8` AUR package. Does this fix the issues you were having before?
@Wodann Im thinking about dropping support for building Arch builds in our Readme. We should at some point describe in more detail how to build LLVM for various platforms ([similar to Zig](https://github.com/ziglang/zig/wiki/How-to-build-LLVM,-libclang,-and-liblld-from-source)) but since its hard for us to test on this platform I feel like we cant really actively support this. 

Once the next inkwell release lands (beta1), we should be able to build a "standalone" binary that should be usable on Arch. This should support most use-cases. If someone does want to build from source we should document a common way of building LLVM, Clang and LLD from source ([something like this](https://github.com/ziglang/zig/wiki/Building-Static-Zig-on-FreeBSD)). 

WDYT?
I agree with that. If we can provide adequate documentation for people to support Mun on their respective systems that'd strike a better balance at this stage of development.
👍 Ill write something up in the development section of the book.

Fix patch:
diff --git a/README.md b/README.md
index e0c2ff804..526e567b5 100644
--- a/README.md
+++ b/README.md
@@ -142,73 +142,19 @@ Windows (64-bit only).
 
 ## Building from Source
 
-### Installing dependencies
-
 Make sure you have the following dependencies installed on you machine:
 
-#### Rust
-
-Install the latest stable version of Rust, [e.g. using
-rustup](https://www.rust-lang.org/tools/install). 
-
-#### LLVM
-
-Mun targets LLVM 8.0.1. Installing LLVM is platform dependant and as such can be
-a pain. The following steps are how we install LLVM on [our CI
-runners](.github/actions/install-llvm/index.js):
-
-* ***nix**: Package managers of recent *nix distros can install binary versions
-  of LLVM, e.g.:
-  ```bash
-  # Ubuntu 18.04
-  sudo apt install llvm-8 llvm-8-* liblld-8*
-  ```
-* **Arch Linux** The binary version of LLVM can currently only be installed
-  using an AUR helper, such as `yay`:
-  ```bash
-  yay -Syu lld7-headers lld7-libs-static
-  ```
-  It is also possible to perform a manual package installation as follows:
-  ```bash
-  # NOTE: this installs all of the lld7 packages
-  cd /tmp
-  git clone https://aur.archlinux.org/lld7.git
-  cd lld7
-  makepkg -si
-  ```
-  When running `llvm-config`, an error can occur signalling that
-  `/usr/lib/libtinfo.so.5` is missing. If a newer version is present, create a
-  symlink; e.g. `ln -s /usr/lib/libtinfo.so.6 /usr/lib/libtinfo.so.5`),
-  otherwise download the library.
-* **macOS**: [Brew](https://brew.sh/) contains a binary distribution of LLVM
-  8.0.1. However, as it's not the latest version, it won't be added to the path.
-  We are using [llvm-sys](https://crates.io/crates/llvm-sys) to manage version,
-  but another option is to export the `LLVM_SYS_80_PREFIX` variable, which will
-  not clutter your `PATH`. To install:
-  ```bash
-  brew install llvm@8
-  # Export LLVM_SYS_PREFIX to not clubber PATH
-  export LLVM_SYS_PREFIX=$(brew --prefix llvm@8)
-  ```
-* **windows**: Binary distrubutions are available for Windows on the LLVM
-  website, but they do not contain a number of libraries that are required by
-  Mun. To avoid having to go to the trouble of compiling LLVM yourself, we
-  created a [repository](https://github.com/mun-lang/llvm-package-windows) that
-  automatically compiles the required binaries. It also contains a
-  [release](https://github.com/mun-lang/llvm-package-windows/releases/v8.0.1)
-  that you can download and extract to your machine. Once downloaded and
-  extracted, add the `<extract_dir>/bin` folder to the `PATH` environment
-  variable.
-
-### Clone source
+* [Rust](https://www.rust-lang.org/tools/install)
+* [LLVM 8](https://docs.mun-lang.org/ch04-02-building-llvm.html)
+
+Clone the source code, including all submodules:
 
 ```bash
 git clone https://github.com/mun-lang/mun.git
-
 git submodule update --init --recursive
 ```
 
-### Compiling
+Use `cargo` to build a release version
 
 ```bash
 cargo build --release
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 46b30dfef..c3472e0dc 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -22,3 +22,4 @@
 
 - [Developer Documentation](ch04-00-developer-docs.md)
     - [Salsa](ch04-01-salsa.md)
+    - [Building LLVM](ch04-02-building-llvm.md)
diff --git a/book/src/ch04-02-building-llvm.md b/book/src/ch04-02-building-llvm.md
new file mode 100644
index 000000000..a3f0d5e8e
--- /dev/null
+++ b/book/src/ch04-02-building-llvm.md
@@ -0,0 +1,100 @@
+# Building LLVM
+
+Most, if not all, dependencies can be build by cargo except for LLVM.
+The Mun compiler makes heavy use of LLVM for all code-generation capabilities.
+Installing it, however, can be tricky.
+This document is a short guide on how to install LLVM on your machine so you can build Mun yourself.
+
+Currently, Mun targets LLVM 8 so everything in this document refers to that version.
+However, these instructions should also hold for newer versions. 
+
+## Prebuild binaries
+
+On some OSes prebuild binaries are available.
+
+> NOTE: not all prebuild releases contain all libraries required by Mun. 
+> For instance, prebuild releases of LLVM for Windows are missing required executables and libraries.
+
+### Windows
+
+For Windows, [we maintain a repository](https://github.com/mun-lang/llvm-package-windows) which contains [releases](https://github.com/mun-lang/llvm-package-windows/releases) that can can be used to build Mun. 
+These releases are also used on our CI runners. 
+
+To use a release, download and extract it to your machine. 
+To make sure the build pipeline can find the binaries, add an environment variable called `LLVM_SYS_80_PREFIX` that points to the folder where you extracted the release.
+It is also possible to add the `bin` folder of the release to your path but using the environment variables allows you to have multiple LLVM releases on your machine.
+
+> For LLVM 8 you should add the `LLVM_SYS_80_PREFIX` environment variable, for LLVM 11 add `LLVM_SYS_110_PREFIX`.
+
+### Debian & Ubuntu
+
+LLVM provides APT repositories for several versions of LLVM which contain all the required binaries required to build Mun. 
+Visit the [LLVM APT website](https://apt.llvm.org/) to find the correct APT repository to use. 
+To add the repository:
+
+```bash
+# Retrieve the archive signature
+wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add -
+
+# Add the repository
+# ${REPO_NAME} should be something like:
+# deb http://apt.llvm.org/focal/ llvm-toolchain-focal-8 main
+#
+# The `add-apt-repository` command is installed by the `software-properties-common` package:
+# sudo apt install software-properties-common 
+add-apt-repository "${REPO_NAME}"
+```
+
+Once you have the proper APT repository configured you can install the required LLVM binaries with:
+
+```bash
+apt install llvm-8 llvm-8-* liblld-8*
+```
+
+### MacOS
+
+[Brew](https://brew.sh/) contains a cask for LLVM that can be used to build Mun:
+
+```bash
+brew install llvm@8
+```
+
+After installing LLVM, you can either add the `bin` folder of the release to your path; or you can add a release-specific environment variable called `LLVM_SYS_80_PREFIX` that points to the release:
+
+```bash
+export LLVM_SYS_80_PREFIX=$(brew --prefix llvm@8)
+```
+
+Adding the `LLVM_SYS_80_PREFIX` variable is usually easier because the LLVM binaries will not conflict with any preinstalled version of LLVM and it allows you to easily install another version of LLVM side-by-side.
+
+> For LLVM 8 you should add the `LLVM_SYS_80_PREFIX` environment variable, for LLVM 11 add `LLVM_SYS_110_PREFIX`.
+
+## Building from source
+
+If there are no prebuild packages available for your OS, your best bet is to install LLVM from source. 
+The build time of LLVM is quite long so this is a relatively time-consuming process.
+
+You need at least: 
+- A C++ compiler (like GCC)
+- [CMake](https://cmake.org/)
+- [Python](https://www.python.org/)
+
+Download a dump of the LLVM repository from the [LLVM github repository](https://github.com/llvm/llvm-project) and extract it somewhere, e.g.:
+
+```bash
+wget -qO- \
+  https://github.com/llvm/llvm-project/archive/llvmorg-8.0.1.tar.gz | \
+  tar xzf -
+```
+
+Then build the required components and install them to `~/local`.
+
+```bash
+cd llvm-project-llvmorg-8.0.1/llvm
+mkdir build
+cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="lld;clang" -DCMAKE_INSTALL_PREFIX=$HOME/local -DCMAKE_INSTALL_PREFIX=$HOME/local -DLLVM_ENABLE_LIBXML2=OFF
+make install -j
+```
+
+After LLVM is build, make sure to add the `$HOME/local/bin` to you path or add an environment variable `LLVM_SYS_80_PREFIX` (or `LLVM_SYS_110_PREFIX` depending on the LLVM version you installed) that points to `$HOME/local`. 


Test patch: