Update the roadmap.
Test: None
Bug: None
Change-Id: I00e2ef9631ebecea998c762b4e8fdc68f5a19f7c
diff --git a/docs/Roadmap.md b/docs/Roadmap.md
index b659ccc..c3b4a54 100644
--- a/docs/Roadmap.md
+++ b/docs/Roadmap.md
@@ -23,47 +23,82 @@
Every NDK release aims to include a new toolchain, new headers, and a new
version of libc++.
-We also maintain [hotlists](https://github.com/android-ndk/ndk/milestones)
+We also maintain [hotlists](https://github.com/android-ndk/ndk/milestones)
of the bugs we intend to fix in any given NDK release.
----
+### Toolchain updates
+
+The NDK and the Android OS use the same toolchain. Android's toolchain team is
+constantly working on updating to the latest upstream LLVM for the OS. It can
+take a long time to investigate issues when compiling -- or issues that the
+newer compiler finds in -- OS code or OEM code, for all 4 supported
+architectures, so these updates usually take a few months.
+
+Even then, a new OS toolchain may not be good enough for the NDK. In the OS, we
+can work around compiler bugs by changing our code, but for the NDK we want to
+make compiler updates cause as little disruption as possible. We also don't want
+to perform a full compiler update late in the NDK release cycle for the sake of
+stability.
+
+The aim is that each NDK will have a new toolchain that's as up to date as
+feasible without sacrificing stability, but we err on the side of stability when
+we have to make a choice. If an NDK release doesn't include a new compiler, or
+that compiler isn't as new as you'd hoped, trust us --- you wouldn't want
+anything newer that we have just yet!
+
+## Current work
+
+Most of the team's work is currently focused outside the NDK proper, so while
+the NDK release notes may seem a bit sparse, there are still plenty of
+improvements coming for NDK users:
+
+* Providing package management for the NDK (see the
+ [Package management](#package-management) section below).
+* Improving NDK and Android Gradle Plugin documentation.
+* Improving the OS (in particular the linker).
+* Getting an up to date LLDB for Android Studio. We'll be adding LLDB support to
+ ndk-gdb after this is done.
+* Working with the Android frameworks teams to get new NDK APIs.
+
+### Package management
+
+There are many other commonly-used libraries (such as cURL and OpenSSL) that are
+currently difficult to build/package, let alone keep updated. We have built:
+
+* [ndkports] for managing Android builds of open source projects.
+* [Prefab] for generating ndk-build/CMake integration (or any other build
+ system via plugins) for AARs generated by [ndkports].
+
+Most of the current work related to this is going in to populating a corpus of
+libraries for apps to use. OpenSSL, cURL, and jsoncpp will be the first batch,
+but we'll be adding more in time. See the open [package requests] on the Prefab
+bug tracker for the current wishlist.
+
+For more information, see [Issue 916].
+
+[Issue 916]: https://github.com/android/ndk/issues/916
+[Prefab]: https://google.github.io/prefab/
+[ndkports]: https://android.googlesource.com/platform/tools/ndkports/
+[package requests]: https://github.com/google/prefab/issues?q=is%3Aissue+is%3Aopen+label%3A%22package+request%22
## Future work
The following projects are listed in order of their current priority.
Note that some of these projects do not actually affect the contents of the NDK
-package. The samples, cdep, documentation, etc are all NDK work but are
-separate from the NDK package. As such they will not appear in any specific
-release, but are noted here to show where the team's time is being spent.
-
-### Easier access to common open-source libraries
-
-There are many other commonly-used libraries (such as Curl and BoringSSL)
-that are currently difficult to build/package, let alone keep updated. We
-should offer (a) a tool to build open source projects, (b) a repository
-of prebuilts, (c) a command-line tool to add prebuilts to an ndk-build/cmake
-project, and (d) Studio integration to add prebuilts via a GUI.
-
-The tools are nearly complete, and the repository is Maven for easy integration
-into existing Android projects. Access from CMake and ndk-build will be via the
-existing `find_package` and `import-module` facilities, respectively. A GUI in
-Studio will come later.
-
-For more information, see [Issue 916].
-
-[Issue 916]: https://github.com/android/ndk/issues/916
+package. The samples, documentation, etc are all NDK work but are separate from
+the NDK package. As such they will not appear in any specific release, but are
+noted here to show where the team's time is being spent.
### C++ File System API
[Issue 609](https://github.com/android-ndk/ndk/issues/609)
-We don't currently build, test, or ship libc++'s std::filesystem. Until recently
-this API wasn't final, but now is at least a stable API (though it sounds like
-the ABI will change in the near future).
+We don't currently build, test, or ship libc++'s `std::filesystem`.
-There's a fair amount of work involved in getting these tests running, but
-that's something we should do.
+There's a fair amount of work involved in getting these tests running. Some of
+the work has already been done, but there's still more to be done for supporting
+older OS versions.
### CMake
@@ -109,14 +144,14 @@
We should probably add basic doc comments to the bionic headers:
- * One-sentence summary.
- * One paragraph listing any Android differences. (Perhaps worth
- upstreaming this to man7.org too.)
- * Explain any "flags" arguments (at least giving some idea of which flags)?
- * Explain the return value: what does a `char*` point to? Who owns
- it? Are errors -1 (as for most functions) or `<errno.h>` values (for
- `pthread_mutex_lock`)?
- * A "See also" pointing to man7.org?
+* One-sentence summary.
+* One paragraph listing any Android differences. (Perhaps worth upstreaming this
+ to man7.org too.)
+* Explain any "flags" arguments (at least giving some idea of which flags)?
+* Explain the return value: what does a `char*` point to? Who owns it? Are
+ errors -1 (as for most functions) or `<errno.h>` values (for
+ `pthread_mutex_lock`)?
+* A "See also" pointing to man7.org?
Should these be in the NDK API reference too? If so, how will we keep
them from swamping the "real" NDK API?
@@ -125,35 +160,40 @@
to have gained a new man page viewer that takes precedence),
and Visual Studio Code has nothing but feature requests.
+Beyond writing the documentation, we also should invest some time in improving
+the presentation of the NDK API reference on developer.android.com.
+
### Better samples
The samples are low-quality and don't necessarily cover interesting/difficult
topics.
-### Better tools for improving code quality.
+### Better tools for improving code quality
The NDK has long included `gtest` and clang supports various sanitiziers,
but there are things we can do to improve the state of testing/code quality:
- * Test coverage support.
- * Add `gmock`.
- * Make [GTestJNI] available to developers via some some package manager so
- developers can integrate their C++ tests into Studio.
+* Test coverage support.
+* Add `gmock`.
+* Make [GTestJNI] available to developers via Maven so developers can integrate
+ their C++ tests into Studio.
[GTestJNI]: https://github.com/danalbert/GTestJNI
-### NDK API header-only C++ wrappers
+### C++ wrappers for NDK APIs
-NDK APIs are C-only for ABI stability reasons. We should offer header-only
-C++ wrappers for NDK APIs, even if only to offer the benefits of RAII.
-Examples include [Bitmap](https://github.com/android-ndk/ndk/issues/822),
+NDK APIs are C-only for ABI stability reasons.
+
+We should offer C++ wrappers as part of an NDK support library (possibly as part
+of JetPack), even if only to offer the benefits of RAII. Examples include
+[Bitmap](https://github.com/android-ndk/ndk/issues/822),
[ATrace](https://github.com/android-ndk/ndk/issues/821), and
[ASharedMemory](https://github.com/android-ndk/ndk/issues/820).
-### NDK C++ header-only JNI helpers
+### JNI helpers
Complaints about basic JNI handling are common. We should make libnativehelper
-or something similar available to developers.
+available as an AAR.
### NDK icu4c wrapper
@@ -196,6 +236,12 @@
[history]: https://developer.android.com/ndk/downloads/revision_history.html
+### NDK r21 LTS
+
+Updated Clang, LLD, libc++, make, and GDB. Much better LLD behavior on Windows.
+32-bit Windows support removed. Neon by default for all API levels. OpenMP now
+available as both a static and shared library.
+
### NDK r20
Updated Clang and libc++, added Q APIs. Improved out-of-the-box Clang behavior.
