blob: 4f05e5d2fccb82e4d80ee5943cdcef194657a437 [file] [log] [blame]
Name: libunwindstack
URL: https://android.googlesource.com/platform/system/core
Version: android-q-preview-6
Revision: c620463f775871ecc73fe3ebc3c9cb2d699d789c
Date: October 8, 2019
License: Apache 2.0
License File: LICENSE
Security Critical: yes
Description:
Canonical library to unwind Android call stacks.
libunwindstack (and its relevant dependencies) are copied from Android's
system/core. libunwindstack handles many of the details of unwinding on Android,
which is inherently more difficult than on other platforms due to the wider
variety of frame types that occur on Android. These include Java frames, JITted
Java frames, Chrome C++ frames, and system library C++ frames. Different frame
types can have different call frame information (CFI) formats that the unwinder
must parse to know how to move up the stack. These formats include DWARF,
MiniDebugInfo, and EHABI. libunwindstack handles much of this complexity.
libunwindstack is copied from the Android tree and utilizes common Android
libraries from that tree. This is analagous to how a static library that is
built within the Chromium tree might utilize //base and //threading. For
libunwindstack, we copy its Android tree dependencies into this directory.
Further complicating matters, Chrome is built against a much older version of
the Android NDK than this version of libunwindstack, which targets Android tip
of tree. The local modifications made allow libunwindstack to compile against
Chrome's older version of the NDK.
To update libunwindstack, you generally get everything compiling locally, then
go back and structure a logical sequence of CLs to get to that point.
In practice, this looks something like:
1. Remove the src/ directory.
2. Copy the full source directories for the folders we need. This can be done
with `tools/copy_libunwindstack_sources.py <upstream_git_tag>`. Do NOT
submit a CL with these full directories: we still need to delete the vast
majority of the files in these directories because they add to the checkout
size but aren't needed to compile libunwindstack.
3. Apply all existing patches onto the src/ directory with
`tools/apply_patches.py`. If any of these patch files need to be modified in
order to successfully apply, do so.
4. Try to compile libunwindstack and fix any compile error. Repeat until
libunwindstack compiles. Generally this will involve adding or removing files
from BUILD.gn or editing source files to not use Android NDK APIs that are
newer than the version of Android that Chrome targets. If files from an
new directory are needed, `copy_libunwindstack_sources.py` should be updated
appropriately.
5. TODO: Write a script that removes unneeded source files from src/. Document
that script here.
6. Send out and submit a CL adding the files from Android platform/system/core
that were ultimately required to compile libunwindstack, but without any
changes that you had to make in order to get them to compile.
This CL will act as a diffbase that makes it possible to review the
incremental changes that you had to make to get libunwindstack to compile.
Note that after you submit this CL, `master` will be in a noncompiling state.
7. One at a time, send out CLs for the changes you needed to make to get to a
compiling state. For example, "Apply existing patches on top of Android-R",
"Add new patch to make foo.cc not use noncompiling API X".
For any new edits that you must make to make the source files compile, make
sure to generate a corresponding patch in the patches/ folder and upload it
in the same CL.
A patch file can be generated for your change with:
git diff master -- <modified_file> > patches/000N-your-patch-name.txt
(Note that it's usually easier to use this manual patch generation method
than git format-patch due to how git commits are squashed in Chromium.)
8. Once you're done, make sure that all source files used are listed in the
`srcs` list of their respective target in BUILD.gn.
TODO: Write a script to make this easy (it will be very similar to the script
to remove unnecessary files, as they both use the results of ninja -d
keepdeps).
Local modifications:
- Android's base/ directory is renamed android-base/.
- 0001-lzma-interface.patch:
Chromium uses an older version of LZMA (15.14, released 2015/12/31) than
platform/system/core (18.06, released 2018/12/30). libunwindstack uses the 8
parameter XzUnpacker_Code call, which wasn't available until 18.03
(https://bit.ly/2Bju4zF).
The 7 parameter XzUnpacker_Code call is equivalent to the new
XzUnpacker_CodeFull call (https://bit.ly/2Bju4zF), which is in turn equivalent
to XzUnpacker_Code with the new `srcFinished` parameter set to `true`
(https://bit.ly/33IIHsK). Because of this, we can safely delete the `true`
`srcFinished` parameter used by libunwindstack and have our 15.14-compliant
code be the same as upstream libunwindstack's 18.06-compliant code.
We also add a missing typedef.
- 0002-remove-temporarydir.patch:
The `TemporaryDir` destructor uses the `nftw` function, which isn't available
in Android NDK version 16 (it was first made available in 17, as per
https://bit.ly/2MSMlt5). `TemporaryDir` is unused by libunwindstack, though,
so we safely remove the entire class.
- 0003-remove-file-logging.patch:
Removes all instances of PLOG() from android-base/file.cpp, which allows us to
remove the dependency on android-base/logging.cpp. logging.cpp is problematic
because it attempts to use BSD's getprogname(), which isn't available in
Android NDK version 16 (it was first made available in 21, as per
https://bit.ly/2nX0nBs).
- 0004-gnu-basename.patch:
Adds a short implementation of the non-modifying GNU basename() function
which isn't available in Android NDK version 16 (it was first made available
in 23, as per https://bit.ly/31Gkyl9). We call this function `compat_basename`.
Although there's a POSIX basename() available via <libgen.h>, that function
has different behavior with regards to trailing slashes and can also modify
its argument under some circumstances.