diff --git a/BUILDING_LLVM.md b/BUILDING_LLVM.md new file mode 100644 index 00000000000..5ebe2def6f2 --- /dev/null +++ b/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). diff --git a/HACKING.md b/HACKING.md index b05b90603f4..ef833453331 100644 --- a/HACKING.md +++ b/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.