[Documentation] Building Apple LLVM for Kotlin/Native (#4297)

BUILDING_LLVM.md

@@ -0,0 +1,51 @@
+# Building Apple LLVM for Kotlin/Native
+
+This document describes how to compile LLVM distribution and use it to build Kotlin/Native on macOS.  
+Usually, you don't need to compile LLVM by yourself:
+* If you use Kotlin/Native compiler it will download LLVM on the first run. 
+* If you contribute to kotlin-native repository then use `:dependencies:update` Gradle task.
+
+But if you don't want to download prebuilt LLVM or want to experiment with your own distribution, 
+you came to the right place.
+
+## Part 1. Building the right LLVM version for macOS.
+
+For macOS host we use LLVM from [Apple downstream](https://github.com/apple/llvm-project). 
+Branch is [**apple/stable/20190104**](https://github.com/apple/llvm-project/tree/apple/stable/20190104) 
+because it is similar (or even the same) to what Apple ships with Xcode 11.*. 
+After cloning the repo and changing the branch we perform the following steps to build LLVM toolchain:
+
+```bash
+mkdir build
+
+cd build
+
+cmake -DLLVM_ENABLE_PROJECTS="clang;lld;libcxx;libcxxabi" \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DLLVM_ENABLE_ASSERTIONS=Off \
+ -G Ninja \
+ -DCMAKE_INSTALL_PREFIX=clang-llvm-apple-8.0.0-darwin-macos \
+ ../llvm
+
+ninja install
+```
+
+After these steps `clang-llvm-apple-8.0.0-darwin-macos` directory will contain LLVM distribution that is suitable for building Kotlin/Native.
+
+## Part 2. Building Kotlin/Native against given LLVM distribution.
+
+By default, Kotlin/Native will try to download LLVM distribution from CDN if it is not present in `$HOME/.konan/dependencies` folder.
+The compiler checks dependency presence by reading contents of `$HOME/.konan/dependencies/.extracted` file. 
+So to avoid LLVM downloading, we should manually add a record to the `.extracted` file:
+1. Create `$HOME/.konan/dependencies/.extracted` file if it is not created.
+2. Add `clang-llvm-apple-8.0.0-darwin-macos` line.
+
+and put `clang-llvm-apple-8.0.0-darwin-macos` directory from the Part 1 to `$HOME/.konan/dependencies/`.
+
+Now we are ready to build Kotlin/Native itself. The process is described in [README.md](README.md).
+Please note that we still need to run `./gradlew dependencies:update` to download other dependencies (e.g. libffi).
+
+## Q&A
+
+— Can I override `.konan` location?  
+— Yes, by setting `$KONAN_DATA_DIR` environment variable. See [HACKING.md](HACKING.md#compiler-environment-variables).

HACKING.md

@@ -229,6 +229,9 @@ $ ./gradlew backend.native:tests:runExternal -Ptest_two_stage=true 2>&1 | tee lo
 
 ## LLVM
 
+See [BUILDING_LLVM.md](BUILDING_LLVM.md) if you want to use your own LLVM distribution
+instead of provided one.
+
 Following compiler phases control different parts of LLVM pipeline:
 1. `LinkBitcodeDependencies`. Linkage of produced bitcode with runtime and some other dependencies.
 2. `BitcodeOptimization`. Running LLVM optimization pipeline.