From c6e6e286510cf35ab7c72cefde022c5d047d67b1 Mon Sep 17 00:00:00 2001
From: Sergey Bogolepov <sergey.bogolepov@jetbrains.com>
Date: Wed, 19 Aug 2020 14:58:34 +0700
Subject: [PATCH] [Docs] Using LLVM from the absolute path

---
 BUILDING_LLVM.md | 16 +++++++++++++++-
 HACKING.md       | 12 +++++++++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/BUILDING_LLVM.md b/BUILDING_LLVM.md
index 5ebe2def6f2..f91b5087727 100644
--- a/BUILDING_LLVM.md
+++ b/BUILDING_LLVM.md
@@ -34,7 +34,12 @@ After these steps `clang-llvm-apple-8.0.0-darwin-macos` directory will contain L
 
 ## 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.
+By default, Kotlin/Native will try to download LLVM distribution from CDN if it is not present in `$HOME/.konan/dependencies` folder. 
+There are two ways to bypass this behaviour.
+
+#### Option A. Substitute prebuilt distribution.
+This option doesn't require you to edit compiler sources, but a bit harder.
+
 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.
@@ -42,6 +47,12 @@ So to avoid LLVM downloading, we should manually add a record to the `.extracted
 
 and put `clang-llvm-apple-8.0.0-darwin-macos` directory from the Part 1 to `$HOME/.konan/dependencies/`.
 
+#### Option B. Provide an absolute path to the distribution.
+This option requires user to edit [konan.properties file](konan/konan.properties).
+Set `llvmHome.<HOST_NAME>` to an absolute path to your LLVM distribution and 
+set `llvmVersion.<HOST_NAME>` to its version.
+For example, provide a path to `clang-llvm-apple-8.0.0-darwin-macos` from the Part 1 and set version to 8.0.0.
+
 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).
 
@@ -49,3 +60,6 @@ Please note that we still need to run `./gradlew dependencies:update` to downloa
 
 — Can I override `.konan` location?  
 — Yes, by setting `$KONAN_DATA_DIR` environment variable. See [HACKING.md](HACKING.md#compiler-environment-variables).
+
+- Can I use another LLVM distribution without rebuilding Kotlin/Native?
+- Yes, see [HACKING.md](HACKING.md#using-different-llvm-distributions-as-part-of-kotlinnative-compilation-pipeline).
\ No newline at end of file
diff --git a/HACKING.md b/HACKING.md
index df528c346dd..aa5759cc543 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -229,9 +229,19 @@ $ ./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
+See [BUILDING_LLVM.md](BUILDING_LLVM.md) if you want to build and use your own LLVM distribution
 instead of provided one.
 
+### Using different LLVM distributions as part of Kotlin/Native compilation pipeline.
+
+`llvmHome.<HOST_NAME>` variable in `<distribution_location>/konan/konan.properties` controls 
+which LLVM distribution Kotlin/Native will use in its compilation pipeline. 
+You can replace its value with either `$llvm.<HOST_NAME>.{dev, user}` to use one of predefined distributions
+or pass an absolute to your own distribution. 
+Don't forget to set `llvmVersion.<HOST_NAME>` to the version of your LLVM distribution.
+
+### Playing with compilation pipeline.
+
 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.