1LLVM Dependency 2=============== 3 4Overview 5-------- 6 7SwiftShader's [Reactor](Reactor.md) library uses LLVM 8as one of its JIT-compiler backends. This page contains notes about building and 9upgrading LLVM. 10 11Directory structure 12------------------- 13 14The current version of LLVM we use is 10, and can be found in 15`third_party/llvm-10.0`. 16 17In this folder you will find the following directories: 18 19* configs : Contains per-platform headers that LLVM sources include to 20 configure the build. These are generated by running `scripts/update.py` 21 (more on that below). 22* llvm : Contains a subset of the LLVM source code needed to build the JIT 23 support required by SwiftShader. 24* scripts : Contains `update.py`, which is used to update the files in the 25 `configs` folder. More on that below. 26 27Updating the current version of LLVM to latest 28---------------------------------------------- 29 30Updating to the latest version of LLVM can be tricky to do manually, especially 31because the [llvm-project repo](https://github.com/llvm/llvm-project) includes 32much more than just LLVM (e.g. it includes all the Clang source). Furthermore, 33we may have local changes to our copy of LLVM that must be maintained, or at 34least considered across updates. 35 36To ease this pain, run the script `third_party/update-llvm-10.sh` on Linux. This 37script works by updating a separate branch of SwiftShader, `llvm10-clean`, on 38which the latest snapshot of LLVM is fetched and committed, and then this branch 39is merged back into `master`. During the merge, if there are conflicts to 40resolve because of local changes we've made, these can be resolved in the usual 41manner, and the merge can be resumed. 42 43The script is configured to fetch from the branch in `LLVM_REPO_BRANCH`, and 44will automatically grab the latest commit on that branch. 45 46Although not always necessary, if there were new configuration variables added 47or modified, you may need to run `update.py` as described below. Otherwise, if 48all goes well, the update to LLVM can be committed and pushed. 49 50Updating LLVM configuration files 51--------------------------------- 52 53The script `third_party/llvm-10.0/scripts/update.py` is used to update the 54config files in `third_party/llvm-10.0/configs`. 55 56Before running this script, you must make sure to update two variables in it 57(and commit this change): 58 59``` 60# LLVM_BRANCH must match the value of the same variable in third_party/update-llvm-10.sh 61LLVM_BRANCH = "release/10.x" 62 63# LLVM_COMMIT must be set to the commit hash that we last updated to when running third_party/update-llvm-10.sh. 64# Run 'git show -s origin/llvm10-clean' and look for 'llvm-10-update: <hash>' to retrieve it. 65LLVM_COMMIT = "d32170dbd5b0d54436537b6b75beaf44324e0c28" 66``` 67 68The script takes a platform as argument, and extra CMake args. For example, to 69update the Linux configs, run: 70 71``` 72python3 update.py linux -j 200 73``` 74 75This script does the following: 76 77* Clones the LLVM repo and checks out `LLVM_COMMIT` from `LLVM_BRANCH`. 78* Builds LLVM specifically for the target architectures specified in 79 `LLVM_TRIPLES` dictionary. 80* Copies the specified platform config files to 81 `third_party/llvm-10.0/configs`, applying certain transformations to the 82 files, such as undefining macros listed in `LLVM_UNDEF_MACROS` (see the 83 `copy_platform_file` function). 84 85Note that certain configuration options depend on the host OS, you will need to 86run the script on the right host OS. See the `LLVM_PLATFORM_TO_HOST_SYSTEM` 87dictionary for the mapping, which looks like this at the time of this writing: 88 89``` 90# Mapping of target platform to the host it must be built on 91LLVM_PLATFORM_TO_HOST_SYSTEM = { 92 'android': 'Linux', 93 'darwin': 'Darwin', 94 'linux': 'Linux', 95 'windows': 'Windows', 96 'fuchsia': 'Linux' 97} 98``` 99 100Generally, Windows to build Window, Darwin to build Darwin (MacOS), and Linux 101for everything else. Also note that for android and fuchsia, the config is 102closest to that of Linux, but you will likely have to manually tweak the configs 103(in particular, `configs/<platform>/include/llvm/Config/config.h`). 104 105Supported platforms, architectures, and build systems 106----------------------------------------------------- 107 108SwiftShader is used by many products on many architectures: 109 110* OS: Windows, Linux, MacOS, Android, Fuchsia 111* Architecture: x64, x86, ARM, ARM64, MIPS, MIPS64 112* Build systems: CMake, GN, Soong, Blaze 113 114Upgrading/updating LLVM usually entails making sure it builds for all of these.