The attached software is provided for Crashlytics NDK early adopters and customers who need increased flexibility when uploading symbol files to Crashlytics servers. The functionality provided is experimental and may not be supported in future releases.
THE ATTACHED JAR FILE IS PRE-RELEASE SOFTWARE. IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
To properly symbolicate stack traces that include native code, Crashlytics requires symbol information to be uploaded for each native library used in an app. The Crashlytics Gradle plugin will automatically generate and upload symbol information for many common NDK use cases. This zip file provides a command-line utility to generate and upload symbols without using Gradle, as well as an experimental new symbol generator that can be used with or without Gradle.
# The path to the supplied buildtools jar. Make sure the version number matches.
# (This file can be moved from the unzip directory to anywhere that is
# convenient.)
CRASHLYTICS_JAR=crashlytics-buildtools/repository/com/google/firebase/firebase-crashlytics-buildtools/<VERSION>/firebase-crashlytics-buildtools-<VERSION>.jar
# The `-verbose` option will log debugging output to STDOUT, which is
# recommended during the first use of the utility, to validate if symbol
# generation & upload were successful.
# The path to the unstripped version of your native library file, containing
# debugging symbols that will be used to symbolicate native crashes. The
# stripped version of this file is included in your app.
UNSTRIPPED_LIBRARY=path/to/unstripped/mylib.so
# The path to a local cache directory in which symbol files generated by this
# utility will be stored prior to uploading. The utility will create this
# directory if it does not exist.
SYMBOL_CACHE_DIR=path/to/symbol/cacheDir
# The Android app id and Firebase-specific Google app id, usually declared in
# google-services.json.
ANDROID_APP_ID="com.example.myapp"
GOOGLE_APP_ID="x:xxxxxxxxxxxx:android:xxxxxxxxxxxxxxxx"
# This option causes the new Breakpad-based symbol generator to be used. To use
# the legacy generator, set the `symbolGenerator` option to "csym".
SYMBOL_GENERATOR=breakpad
# This command will generate a symbol file for UNSTRIPPED_LIBRARY and put it in
# SYMBOL_CACHE_DIR. You can run this command multiple times with different files
# as the UNSTRIPPED_LIBRARY.
java -jar $CRASHLYTICS_JAR -generateNativeSymbols -verbose \
-unstrippedLibrary $UNSTRIPPED_LIBRARY \
-symbolFileCacheDir $SYMBOL_CACHE_DIR \
-symbolGenerator $SYMBOL_GENERATOR
# This command will upload all symbol files in SYMBOL_CACHE_DIR to Crashlytics
# servers for the specified app. The value of $SYMBOL_GENERATOR must match the
# preceding command.
java -jar $CRASHLYTICS_JAR -uploadNativeSymbols -verbose \
-androidApplicationId $ANDROID_APP_ID \
-googleAppId $GOOGLE_APP_ID \
-symbolFileCacheDir $SYMBOL_CACHE_DIR \
-symbolGenerator $SYMBOL_GENERATOR
When using the symbolGenerator=breakpad, the -generateNativeSymbols command
will extract a binary executable and required dependencies to a local
.crashlytics directory, creating it if necessary. You can safely delete this
directory at any time.
First, ensure your app is configured for Crashlytics NDK by following the Getting Started guide.
Next, configure your Gradle project to use the supplied, experimental version of the Crashlytics Gradle plugin by updating the project-level Gradle file's buildscript repository:
buildscript {
repositories {
maven { url "file://PATH_TO_UNZIP_LOCATION/crashlytics-buildtools/repository"
google()
mavenCentral()
}
dependencies {
// Double-check this version matches the one unzipped into the above
// local maven repo.
classpath "com.google.firebase:crashlytics-gradle:VERSION
}
}
To use the Breakpad symbol generator & upload symbols to Crashlytics, run the
uploadCrashlyticsSymbolFile<VARIANT> task as usual, with the following
additional command-line argument to Gradle:
-Pcom.google.firebase.crashlytics.symbolGenerator=breakpad
For example:
> ./gradlew app:assembleRelease uploadCrashlyticsSymbolFileRelease \
-Pcom.google.firebase.crashlytics.symbolGenerator=breakpad
The above uses a bundled version of the breakpad symbol generator binary. Some
customers may with to build their own native breakpad dump_syms binary. To
specify a different binary, use the com.google.firebase.crashlytics.breakpadBinary
property. For example:
> ./gradlew app:assembleRelease uploadCrashlyticsSymbolFileRelease \
-Pcom.google.firebase.crashlytics.symbolGenerator=breakpad
-Pcom.google.firebase.crashlytics.breakpadBinary=\bin\dump_syms.bin
Instead of using the properties described above, you can enable the Breakpad symbol generator via the app build.gradle file:
android {
// ...
buildTypes {
// ...
release {
//...
firebaseCrashlytics {
nativeSymbolUploadEnabled true
symbolGenerator {
// Option 1: use bundled breakpad native binary
breakpad()
// Option 2: specify an alternate breakpad binary
breakpad {
binary file("path/to/breakpad/binary")
}
}
}
}
}
Note that you will need to run the app:clean task if switching between
Breakpad and non-Breakpad modes.
To verify the Crashlytics Gradle plugin actions, you can try run Gradle with the
--debug option and filter the output for lines containing
[com.google.firebase.crashlytics]
See LICENSES.txt for the licenses of included open source software.