The latest version of this document is available at https://android.googlesource.com/platform/ndk/+/mirror-goog-main-ndk/docs/Building.md.
Both Linux and Windows NDKs are built on Linux machines. Windows host binaries are cross-compiled with MinGW.
Building the NDK for Mac OS X requires at least 10.13.
The first thing you need is the AOSP NDK repository. If you‘re new to using repo and gerrit, see repo.md for tips. If you’re already familiar with how to use repo and gerrit from other Android projects, you already know plenty :)
Check out the branch master-ndk. Do this in a new directory.
# For non-Googlers: repo init -u https://android.googlesource.com/platform/manifest -b master-ndk --partial-clone # Googlers, follow http://go/repo-init/master-ndk (select AOSP in the Host menu, # and uncheck the box for the git superproject). At time of writing, the correct # invocation is: repo init -u \ sso://android.git.corp.google.com/platform/manifest -b master-ndk --partial-clone
If you wish to rebuild a given release of the NDK, the release branches can also be checked out. They're named ndk-release-r${RELEASE} for newer releases, but ndk-r{RELEASE}-release for older releases. For example, to check out the r19 release branch, use the -b ndk-release-r19 flag instad of -b master-ndk.
Linux dependencies are listed in the Dockerfile. You can use docker to build the NDK:
docker build -t ndk-dev infra/docker docker run -it -u $UID -v `realpath ..`:/src -w /src/ndk ndk-dev ./checkbuild.py
Building on Mac OS X has similar dependencies as Linux, but also requires Xcode.
Running tests requires that adb is in your PATH. This is provided as part of the Android SDK.
To set up your environment to use the correct versions of Python and Python packages, install Poetry.
Note: do not use the Python binaries in prebuilts/python. That distribution lacks a functioning ssl module which is necessary for installing dependencies.
The first time, and also anytime you sync because there might be new or updated dependencies, install the NDK dependencies to the virtualenv managed by poetry.
poetry install
Note: If poetry install hangs on Linux, try PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring poetry install.
Spawn a new shell using the virtualenv that Poetry created. You could instead run NDK commands with the poetry run prefix (e.g. poetry run ./checkbuild.py), but it‘s simpler to just spawn a new shell. Plus, if it’s in your environment your editor can use it.
poetry shell
On macOS you may not be able to use the Python that is in prebuilts because it does not support the ssl module (which poetry itself needs). Until the Python prebuilt includes that module, do the following to use a different Python:
First time setup: ensure that you have pyenv installed. You may need to install homebrew (http://go/homebrew for Googlers, else https://brew.sh/).
$ brew update && brew upgrade pyenv
Then set up your tree to use the correct version of Python. This setting will apply to the directory it is run in, so you will need to do it per NDK tree.
# From the //ndk directory of your NDK tree: $ ../prebuilts/python/darwin-x86/bin/python3 --version Python 3.11.4 # We don't need to match the version exactly, just the major/minor version. $ pyenv install 3.11:latest $ pyenv local 3.11 $ python --version Python 3.11.8 $ poetry env use 3.11 poetry install
Each time the NDK updates to a new version of Python, you'll need to repeat those steps. You may also need to remove the old poetry environment (poetry env list to get the name, poetry env remove to remove it).
checkbuild.py and run_tests.py will complain when you try to use a Python that doesn't come from prebuilts by default. To suppress that, pass --permissive-python-environment when using those tools in this environment.
$ python checkbuild.py
If you get errors from the pythonlint task but it appears to only affect your machine, one of the linters you have installed is probably not the correct version. Run poetry install to sync your environment with the expected versions.
$ python checkbuild.py --system windows64
checkbuild.py will also build all of the NDK tests. This takes about 3x as long as building the NDK itself, so pass --no-build-tests to skip building the tests if you're iterating on build behavior or plan to rebuild only specific tests. Tests can be built later with python run_tests.py --rebuild.
Note: The NDK's build and test scripts are implemented in Python 3 (currently 3.9). checkbuild.py will use a prebuilt Python, but run_tests.py does not do this yet. run_tests.py also can be run outside of a complete development environment (as it is when it is run on Windows), so a Python 3.9 virtualenv is recommended.
Packaging uses zip -9 so is extremely time consuming and disabled by default. Use the --package flag to force packaging locally. This is not required for local development and only needs to be used when testing packaging behavior.