> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apsio.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload NDK symbols

> Upload an Android build's native libraries with debug information so its native crashes show functions, files and lines.

A native crash on Android (C or C++ code, built with the NDK) reaches Apsio as the frames
of the system's crash report: each frame names a library, an offset into it and the
library's GNU build id. Apsio turns `libshop.so + 0x398` into `cart_total` in `shop.c:13`,
inlined frames included, with that library's debug information. See
[Android native code](/concepts/symbols#android-native-code-ndk) for what is symbolicated.

Native crash reports come from Android 12 and later. The stack of a native crash on older
versions is not available to apps.

## With the Gradle plugin

The Apsio Gradle plugin (`io.apsio.gradle`) does it on every release build. Its
`nativeSymbols` option is on by default:

```kotlin theme={null}
apsio {
    nativeSymbols = true // the default; false turns both steps off
}
```

* Release build types get `ndk.debugSymbolLevel = "FULL"` unless they set it, so AGP keeps
  each library's debug information in a separate `.so.dbg` file. The libraries in the app
  are still stripped.
* After the build, the plugin uploads those files with `apsio upload ndk`, under the build
  id it writes into the manifest, next to the [R8 mapping](/symbols/android). It uses the
  token in `APSIO_TOKEN`, as for the mapping.

## With the CLI

From a build script or CI, after the build:

```sh theme={null}
apsio upload ndk native-debug-symbols --build-id 6f1d2c3b-4a59-4e7f-8a1b-2c3d4e5f6a7b
```

* The directory (here `native-debug-symbols`) holds one subdirectory per ABI, `arm64-v8a`,
  `armeabi-v7a`, `x86`, `x86_64` and `riscv64`, with the libraries' ELF files that have debug
  information: the `.so.dbg` files of `debugSymbolLevel = "FULL"` (AGP also zips them, in this layout, into
  `app/build/outputs/native-debug-symbols/<variant>/native-debug-symbols.zip` for Google
  Play: unzip it and pass the folder), or unstripped `.so` files.
* Each file is uploaded under its GNU build id, the id native crashes carry, with its ABI and
  the library's name. A file that is not ELF, has no build id, has no symbols (a stripped
  library) or belongs to another ABI is skipped with a warning.
* `--build-id` is the build id in the app's manifest, the one its R8 mapping uses (see
  [Give the build an id](/symbols/android#1-give-the-build-an-id)). Apsio records which
  libraries that build ships.
* A library Apsio already has is not sent again: a library you did not change keeps its
  build id across builds. `--force` uploads everything again. `--dry-run` checks the files
  without a token or an upload, and `--json` prints a report.
* The command succeeds when every library was uploaded or Apsio had it already. When any
  upload fails it exits with an error (4 when the server rejected the files, 1 for network or
  server errors), after uploading the others, so a build that treats upload errors as
  failures stops.

Link your libraries with a build id: the NDK's toolchain does it by default
(`-Wl,--build-id`). A library without one cannot be matched to its crashes.

## When a native crash stays unsymbolicated

* The build's debug files were never uploaded, or come from another build: a rebuild of the
  same code can produce other build ids.
* The library was linked without a build id.
* The frame is in a library of the system (`libc.so`, `libart.so`): those keep the function
  name the device gives and are never listed as missing.

The release's [missing symbols](/concepts/symbols#missing-symbols) list your libraries that
crashes used and that have no upload, by the debug id made from their build id. Crashes that arrived before the upload are
symbolicated when it lands, and [grouped again](/concepts/issues#grouping) by function names.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.