Expand documentation for native-activity sample.

This expands the docs and comments in the native-activity sample to be
something closer to a proper guide. There isn't a very clear flow to it
since the documentation is necessarily spread out into multiple files,
and sometimes the order of the code requires explaining things out of
order, but it's better than nothing.

If we wanted to turn this into an actual guide that could be written in
a clear order without duplicating code snippets into the docs, which
would surely be quickly out of date, we could use something like sphinx
(possibly through readthedocs) to generate something closer to a
literate code sample.

Author: DanAlbert

native-activity/README.md

@@ -1,21 +1,69 @@
 # Native Activity
 
+> [!WARNING]
+> **Most apps should not use the app development model shown in this sample
+> (`NativeActivity`). Instead, use a Java or Kotlin `AppCompatActivity` and
+> connect your native code using JNI like the other samples in this repository.
+> `NativeActivity` and `GameActivity` attempt to translate the Android [activity
+> lifecycle] into a desktop style `main()` function with a polled event loop.
+> That is not how Android apps work, and while it may help you get your
+> prototype running more quickly, as your app matures you will likely end up
+> retranslating the `native_app_glue` model to again look like `Activity`.
+
 This is an Android sample that uses [NativeActivity] with `native_app_glue`,
 which enables building NDK apps without having to write any Java code. In
 practice most apps, even games which are predominantly native code, will need to
-call some Java APIs or customize their app's activity further.
+call some Java APIs or customize their app's activity further. While it may save
+you a small amount of effort during prototyping, it may result in a difficult
+migration later. It's also worth noting that some of the code in this sample is
+spent undoing the work of `native_app_glue` to create a class very similar to
+`Activity`.
 
 The more modern approach to this is to use [GameActivity], which has all the
 same benefits as `NativeActivity` and `native_app_glue`, while also making it
 easier to include Java code in your app without a rewrite later. It's also
-source compatible. This sample will likely migrate to `GameActivity` in the
-future.
+source compatible. However, it still has all the problems explained in the
+warning above, and in practice neither `NativeActivity` nor `GameActivity` is
+the recommended app development model.
 
 The app here is intentionally quite simple, aiming to show the core event and
 draw loop necessary for an app using `native_app_glue` without any extra
 clutter. It uses `AChoreographer` to manage the update/render loop, and uses
 `ANativeWindow` and `AHardwareBuffer` to update the screen with a simple color
 clear.
 
+[activity lifecycle]: https://developer.android.com/guide/components/activities/activity-lifecycle
 [GameActivity]: https://developer.android.com/games/agdk/game-activity
 [NativeActivity]: http://developer.android.com/reference/android/app/NativeActivity.html
+
+## Walkthrough
+
+The interesting sections of code in this sample are in three files:
+[AndroidManifest.xml], [CMakeLists.txt], and [main.cpp]. Each of those files has
+code comments explaining the portions relevant to using `NativeActivity`, but
+the high level details of the app are explained here.
+
+This app uses `NativeActivity` rather than its own child class of `Activity` or
+`AppCompatActivity`. This is specified in the `<activity />` declaration in [the
+manifest].
+
+Apps which use `NativeActivity` are typically written using `native_app_glue`,
+which adapts the Android activity lifecycle code to look more like a desktop
+program with a `main()` function and an event loop. This is set up in the app's
+[CMakeLists.txt file].
+
+When using `native_app_glue` with a [version script], you must export
+`ANativeActivity_onCreate`. This sample does this in
+[libnative-activity.map.txt].
+
+This is a fairly simple application, so all of the code is in a single file,
+[main.cpp]. The entry point for an app using `native_app_glue` is
+`android_main()`. That function is the best place to start reading in this file
+to learn how the sample works, then follow through to the definition of
+`engine_handle_cmd` and `Engine`.
+
+[CMakeLists.txt file]: app/src/main/cpp/CMakeLists.txt
+[libnative-activity.map.txt]: app/src/main/cpp/libnative-activity.map.txt
+[main.cpp]: app/src/main/cpp/main.cpp
+[the manifest]: app/src/main/AndroidManifest.xml
+[version script]: https://developer.android.com/ndk/guides/symbol-visibility

native-activity/app/src/main/AndroidManifest.xml

@@ -1,38 +1,44 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- BEGIN_INCLUDE(manifest) -->
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     android:versionCode="1"
-          android:versionName="1.0">
+    android:versionName="1.0">
 
-  <!--
-  This .apk has no Java/Kotlin code, so set hasCode to false.
+    <!--
+    This .apk has no Java/Kotlin code, so set hasCode to false.
 
-  If you copy from this sample and later add Java/Kotlin code, or add a
-  dependency on a library that does (such as androidx), be sure to set
-  `android:hasCode` to `true` (or just remove it, since that's the default).
-  -->
-  <application
-      android:allowBackup="false"
-      android:fullBackupContent="false"
-      android:icon="@mipmap/ic_launcher"
-      android:label="@string/app_name"
-      android:hasCode="false">
-
-    <!-- Our activity is the built-in NativeActivity framework class.
-         This will take care of integrating with our NDK code. -->
-    <activity android:name="android.app.NativeActivity"
-              android:label="@string/app_name"
-              android:configChanges="orientation|keyboardHidden"
-        android:exported="true">
-      <!-- Tell NativeActivity the name of our .so -->
-      <meta-data android:name="android.app.lib_name"
-                 android:value="native-activity" />
-      <intent-filter>
-        <action android:name="android.intent.action.MAIN" />
-        <category android:name="android.intent.category.LAUNCHER" />
-      </intent-filter>
-    </activity>
-  </application>
+    If you copy from this sample and later add Java/Kotlin code, or add a
+    dependency on a library that does (such as androidx), be sure to set
+    `android:hasCode` to `true` (or just remove it, since that's the default).
+    -->
+    <application
+        android:allowBackup="false"
+        android:fullBackupContent="false"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:hasCode="false">
 
+        <!--
+        This app uses android.app.NativeActivity rather than its own child class of
+        Activity or AppCompatActivity. The advantage of this is that we do not have
+        to write any Java code of our own. The Java portion of the app is provided
+        by the OS.
+        -->
+        <activity
+            android:name="android.app.NativeActivity"
+            android:configChanges="orientation|keyboardHidden"
+            android:exported="true">
+            <!--
+            This property tells NativeActivity which of our app's libraries
+            provide the definition of ANativeActivity_onCreate, which is the
+            entry point for apps using ANativeActivity.
+            -->
+            <meta-data
+                android:name="android.app.lib_name"
+                android:value="native-activity" />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
 </manifest>
-<!-- END_INCLUDE(manifest) -->

native-activity/app/src/main/cpp/CMakeLists.txt

@@ -1,31 +1,34 @@
-#
-# Copyright (C) The Android Open Source Project
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-
+# Copyright (C) 2010 The Android Open Source Project
+# SPDX-License-Identifier: Apache-2.0
 cmake_minimum_required(VERSION 4.1.0)
 project(NativeActivity LANGUAGES C CXX)
 
 include(AppLibrary)
-include(AndroidNdkModules)
 
+# This includes the AndroidNdkModules.cmake file, which is shipped with the
+# NDK's CMake distribution. Including this file defines
+# android_ndk_import_module_native_app_glue(), which defines the
+# native_app_glue target when called.
+include(AndroidNdkModules)
 android_ndk_import_module_native_app_glue()
 
 add_app_library(native-activity SHARED main.cpp)
 
+# Linking the native_app_glue target with our native-activity target (the
+# library which contains the main app code) includes native_app_glue in the app.
 target_link_libraries(native-activity
     android
+    # We have to use $<LINK_LIBRARY:WHOLE_ARCHIVE,native_app_glue> rather than
+    # the simpler native_app_glue spelling to instruct the linker that the
+    # entire native_app_glue static library should be included in
+    # libnative-activity.so, even if the linker does not find any calls in our
+    # code to native_app_glue. This is because native_app_glue is a static
+    # library rather than a shared library, and normally the linker will only
+    # include code from static libraries when it has found a call to that code.
+    # This is usually a good thing because it reduces the size of the app, but
+    # in this case the calls to native_app_glue, specifically the
+    # ANativeActivity_onCreate function, don't come from us, but instead come
+    # from ANativeActivity, which the linker cannot detect.
     $<LINK_LIBRARY:WHOLE_ARCHIVE,native_app_glue>
     log
 )

native-activity/app/src/main/cpp/libnative-activity.map.txt

@@ -1,5 +1,10 @@
 LIBNATIVEACTIVITY {
   global:
+    # When using NativeActivity and you don't need any of your own JNI
+    # functions this is the only symbol that should be exported. If your app
+    # needs additional JNI functions (and most apps will), then you'll need to
+    # include JNI_OnLoad (or your individual Java_... functions if you're not
+    # using RegisterNatives) here.
     ANativeActivity_onCreate;
   local:
     *;