# Working with the NDK Toolchains

The latest version of this document is available at
https://android.googlesource.com/platform/ndk/+/mirror-goog-main-ndk/docs/Toolchains.md.

The LLVM toolchain shipped in the NDK is not built as a part of the NDK build
process. Instead is it built separately and checked into git as a prebuilt that
is repackaged when shipped in the NDK.

An artifact of the toolchain build is the distribution tarball. That artifact is
unpacked into a location in the Android tree and checked in. The NDK build step
for the toolchain copies that directory into the NDK and makes some
modifications to make the toolchains suit the NDK rather than the platform.
For example, non-NDK runtime libraries are deleted and the NDK sysroot is
installed to the `sysroot` subdirectory of the toolchain so it can be found
automatically by the compiler.

Note: Any changes to either toolchain need to be tested in the platform *and*
the NDK. The platform and the NDK both get their toolchains from the same build.

TODO: This process is far too manual. `checkbuild.py` should be updated (or
additional scripts added) to ease this process.

## Clang

Clang's build process is described in the [Android LLVM Readme]. Note that Clang
cannot be built from the NDK tree. The output tarball is extracted to
`prebuilts/clang/host/$HOST/clang-$REVISION`. `checkbuild.py toolchain`
repackages this into the NDK out directory.

[Android LLVM Readme]: https://android.googlesource.com/toolchain/llvm_android/+/refs/heads/mirror-goog-main-llvm-toolchain-source/README.md

### Updating to a New Clang

If you're updating the NDK to use a new release of the LLVM toolchain, do the
following.

Note: These steps need to be run after installing the new prebuilt from the
build server to `prebuilts/clang` (see the [update-prebuilts.py]). The LLVM team
will handle installing the new toolchain to prebuilts, but the NDK team usually
makes the change to migrate to the new toolchain as described below.

[update-prebuilts.py]: https://android.googlesource.com/toolchain/llvm_android/+/refs/heads/mirror-goog-main-llvm-toolchain-source/update-prebuilts.py

```bash
# Edit ndk/toolchains.py and update `CLANG_VERSION`.
$ ./checkbuild.py
# ./run_tests.py
```

### Testing local llvm-toolchain changes with the NDK

If you're working with unsubmitted changes to llvm-toolchain and want to test
your LLVM changes in the NDK, do the following. If you're just updating the NDK
to use a newer prebuilt LLVM, you don't need to do this part.

```bash
$ export CLANG_PREBUILTS=`realpath ../prebuilts/clang/host/linux-x86`
$ rm -r $CLANG_PREBUILTS/clang-dev
# $LLVM_TOOLCHAIN refers to the root of your llvm-toolchain source directory. If
# you have a tarball for the toolchain distribution, extract that to
# $CLANG_PREBUILTS/clang-dev instead.
$ cp -r $LLVM_TOOLCHAIN/out/install/$HOST/clang-dev $CLANG_PREBUILTS/
# Update CLANG_VERSION in ndk/toolchains.py to clang-dev.
$ ./checkbuild.py
# Run tests. To run the NDK test suite, you will need to attach the
# appropriately configured devices. The test tool will print warnings for
# missing configurations.
$ ./run_tests.py
```

For details about running tests, see [Testing.md].

[Testing.md]: Testing.md

This installs the new Clang into the prebuilts directory so it can be included
in the NDK.

If you need to make changes to Clang after running the above steps, future
updates can be done more quickly with:

```bash
$ rm -r $CLANG_PREBUILTS/clang-dev
$ tar xf path/to/clang-dev-linux-x86_64.bz2 -C $CLANG_PREBUILTS
$ ./checkbuild.py toolchain
# Run tests.
```

We don't need to rebuild the whole NDK since we've already built most of it.