Skip to content

Commit e154ae4

Browse files
committed
Improve Android-specific documentation
1 parent 4a20f96 commit e154ae4

File tree

2 files changed

+25
-5
lines changed

2 files changed

+25
-5
lines changed

src/symbolize/gimli.rs

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,19 @@ struct Cache {
270270
struct Library {
271271
name: OsString,
272272
#[cfg(target_os = "android")]
273+
/// On Android, the dynamic linker [can map libraries directly from a
274+
/// ZIP archive][ndk-linker-changes] (typically an `.apk`).
275+
///
276+
/// The linker requires that these libraries are stored uncompressed
277+
/// and page-aligned.
278+
///
279+
/// These "embedded" libraries have filepaths of the form
280+
/// `/path/to/my.apk!/lib/mylib.so` (where `/path/to/my.apk` is the archive
281+
/// and `lib/mylib.so` is the name of the library within the archive).
282+
///
283+
/// This mechanism is present on Android since API level 23.
284+
///
285+
/// [ndk-linker-changes]: https://android.googlesource.com/platform/bionic/+/main/android-changes-for-ndk-developers.md#opening-shared-libraries-directly-from-an-apk
273286
zip_offset: Option<u64>,
274287
#[cfg(target_os = "aix")]
275288
/// On AIX, the library mmapped can be a member of a big-archive file.

src/symbolize/gimli/elf.rs

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,12 +43,18 @@ impl Mapping {
4343
})
4444
}
4545

46-
/// On Android, shared objects can be loaded directly from a
47-
/// ZIP archive. For example, an app may load a library from
48-
/// `/data/app/com.example/base.apk!/lib/x86_64/mylib.so`
46+
/// On Android, shared objects can be loaded directly from a ZIP archive
47+
/// (see: [`super::Library::zip_offset`]).
4948
///
50-
/// `zip_offset` should be page-aligned; the dynamic linker
51-
/// requires this when it loads libraries.
49+
/// If `zip_offset` is not None, we interpret the `path` as an
50+
/// "embedded" library path, and the value of `zip_offset` tells us where
51+
/// in the ZIP archive the library data starts.
52+
///
53+
/// We expect `zip_offset` to be page-aligned because the dynamic linker
54+
/// requires this. Otherwise, loading the embedded library will fail.
55+
///
56+
/// If we fail to load an embedded library for any reason, we fallback to
57+
/// interpreting the path as a literal file on disk (same as calling [`Self::new`]).
5258
#[cfg(target_os = "android")]
5359
pub fn new_android(path: &Path, zip_offset: Option<u64>) -> Option<Mapping> {
5460
fn map_embedded_library(path: &Path, zip_offset: u64) -> Option<Mapping> {
@@ -75,6 +81,7 @@ impl Mapping {
7581
}
7682

7783
// if ZIP offset is given, try mapping as a ZIP-embedded library
84+
// otherwise, fallback to mapping as a literal filepath
7885
if let Some(zip_offset) = zip_offset {
7986
map_embedded_library(path, zip_offset).or_else(|| Self::new(path))
8087
} else {

0 commit comments

Comments
 (0)