For apps that use the NDK, native stacktraces from C or C++ code consist of a list of addresses and numeric offsets. BugSnag requires a mapping file to be uploaded to match a given address with a file name and method.
For installation instructions for the BugSnag CLI, please see our Installation guide.
The android-ndk command takes your built .so files and extracts symbol mapping information using the objcopy tool in your NDK installation. This removes all executable code and just leaves the symbol information for upload to the NDK symbol API.
In addition to the symbol file, the command extracts version and build information, including your BugSnag API key, from your app’s manifest file (AndroidManifest.xml). The command attempts to find a merged app manifest file in your project directory, but if you have a non-standard project layout the location can be specified using the --app-manifest option, along with --variant if multiple build flavors exist. All values read from the app manifest can be overridden, or provided entirely, using the --application-id, --version-name and --version-code options.
The simplest way to run the command is from the root directory of your Android project:
$ bugsnag-cli upload android-ndk
Or by providing a specific library to upload:
$ bugsnag-cli upload android-ndk \
app/build/intermediates/merged_native_libs/release/out/lib/arm64-v8a/libMyApp.so
If you have multiple variants built or a non-standard project layout, you might need to provide extra options:
$ bugsnag-cli upload android-ndk \
--variant=release \
--app-manifest-path=app/build/intermediates/merged_manifests/release/AndroidManifest.xml
--android-ndk-root) The path to your NDK installation, used to access the objcopy tool for extracting symbol information. This defaults to the path in the $ANDROID_NDK_ROOT environment variable.
--api-key) Your project’s API key. This defaults to the value of com.bugsnag.android.API_KEY in your app’s manifest file, if found.
You can find your API key in Project Settings from your BugSnag dashboard.
--app-manifest) The path to the app’s manifest file (AndroidManifest.xml), which is used to extract app information required for the upload. By default, the command looks for this file in app/build/intermediates/merged_manifests/<variant>/AndroidManifest.xml from your project directory.
--application-id) The unique application ID, usually the package name, of the app. This defaults to the value of Package in your app’s manifest file, if found.
--dry-run) Used to see the files and options that would be uploaded without actually sending them to the BugSnag endpoint.
--fail-on-upload) Whether to stop any further uploads if a file fails to upload successfully. By default the command attempts to upload all files.
--overwrite) Whether to ignore and overwrite existing uploads with same identifier. By default the command will fail if a matching file exists.
--project-root) Path to strip from the beginning of source file names referenced in stacktraces when displayed as an error in your dashboard. This will default to your project’s root directory if the command has detected one, otherwise it’s empty.
--retries) The number of retry attempts before failing an upload. By default it is only attempted once.
--timeout) The number of seconds to wait before failing an upload attempt. By default the upload is given 300s (5 mins).
--upload-api-root-url) The BugSnag On-premise upload server hostname, optionally containing port number. The command will append the appropriate path to access the correct BugSnag API upload endpoint.
--variant) The build type/flavor (e.g. ‘debug’ or ‘release’). This is used to disambiguate the between built files when searching your project directory.
--version-code) The version code of this build of the app. This defaults to the value of VersionCode in your app’s manifest file, if found.
--version-name) The version of the app. This defaults to the value of VersionName in your app’s manifest file, if found.