Qt Android integration documentation

[glennra]

Problem Statement

I want to use sentry in a Qt Android app. The documentation I could find about this is here: getsentry/sentry-java#1626 . Following that I have included the sentry-native src using add_subdirectory in my CMakeLists.txt and set SENTRY_INTEGRATION_QT to ON. This builds successfully.

As a C++/Qt developer I'm not familiar all that familiar with gradle and Qt Creator hides all the gradle stuff. I'm unsure of how to include the library that I just built into my app. The instructions here say to add this to build.gradle:

plugins {
  id "com.android.application"
  id "io.sentry.android.gradle" version "4.2.0"
}

but I think this gets the sentry-android library from an external repository and that version doesn't have Qt integration enabled.

Solution Brainstorm

Provide instructions targeted at Qt developers to include a Qt-enabled version of the sentry-android library into their app.

Product Area

Unknown

[getsantry]

Assigning to @getsentry/support for routing ⏲️

[supervacuus]

There is currently no support for "Qt on Android" in either the sentry-native or sentry-android.

We do have a Qt message-handler integration that converts qt messages to sentry breadcrumbs (the thing you enable with SENTRY_INTEGRATION_QT), but this was implemented with Qt Desktop applications in mind. Users who want to use Qt on Android will have to build everything themselves (i.e., there are currently no published maven artifacts that include the Qt integration).

Having said that, you must

• change the version in the gradle.properties of the artifact you want to use in your project to a unique version tag you can reference later
• publishToMavenLocal in the sentry-java build
• make sure that your consuming project has mavenLocal() in its repository list
• and then use that specific version above in your dependency list

How to do this exactly is decidedly not a topic for the Native SDK repo. I could imagine that this is already documented, maybe @markushi knows more. But even if it is documented, I am sure that there is currently no documentation for how Qt integrates these gradle commands, that is probably something that Qt devs can respond to more competently.

cc: @kahest

[glennra]

Thank you for the gradle tips. I'll have a look at that.

There is currently no support for "Qt on Android" in either the sentry-native or sentry-android.

In the documentation for the Sentry Qt support it explicitly says :

"The Qt integration is part of the sentry-native SDK, which currently supports Windows, macOS, Linux, and Android."

We do have a Qt message-handler integration that converts qt messages to sentry breadcrumbs (the thing you enable with SENTRY_INTEGRATION_QT), but this was implemented with Qt Desktop applications in mind. Users who want to use Qt on Android will have to build everything themselves (i.e., there are currently no published maven artifacts that include the Qt integration).

Understood and this was the reason for my original request for documentation.

How to do this exactly is decidedly not a topic for the Native SDK repo.

Given the above quote from the sentry-native install guide it seems like it has been routed correctly.

[supervacuus]

"The Qt integration is part of the sentry-native SDK, which currently supports Windows, macOS, Linux, and Android."

This sentence needs to be better worded or factually corrected. There are currently no build-, install- or unit-tests running that would cover Qt for Android usage in even the most minimal way. It isn't even true that the Native SDK supports Android directly (even without considering Qt).

To state this clearly, the Native SDK is used as a library to support the narrow NDK usage exposed in the downstream sentry-android SDK. While people might be utilizing the Native SDK on Android in other ways, those setups currently cannot be supported. We are open to community contributions to improve the situation, though.

This brings me to the Native SDK Qt support (without considering Android): the only specific Qt "integration" (which also was a community contribution) is a simple implementation and registration of a message handler. It could have been an example code because it only uses the public API of the Native SDK.

If you want to use it without having to integrate a specific native build into your project, you might be better served by copying it and accessing the Native API from your NDK code via the documented approach here: https://docs.sentry.io/platforms/android/configuration/using-ndk/#allowing-the-compiler-to-link-libraries

We are currently working on shifting the modularity of the NDK integration in sentry-android, which might also affect your use case. Still, the driver here is primarily the usage as a component in the sentry-android setup. Supporting Qt for Android would look very different (direct support via toolchain integration, by-passing the indirection via sentry-android and providing a crash-backend that can support Qt in that environment). This is currently not even on the roadmap.

I am sorry that the docs contribute to the confusion of the support level. We must clarify the current formulations.

[kahest]

related docs PR: getsentry/sentry-docs#9090

[glennra]

The above comment is disingenuous. Sentry does "work" on Android with Qt given the mentioned caveats. By "work" I mean it reports if the app crashes, e.g. via a segfault, and it delivers the intercepted Qt messages as described for the Qt integration. The way it works may not be fully featured but it is better than nothing. Withdrawing support instead of providing proper documentation of the build process and the known limitations seems like a backward step, especially for those paying customers that have become customers because it was advertised that Android is supported.
Getting it built is not straightforward, partly because the build information is hidden behind a gradle plugin, and partly because of the way Qt Creator builds Android apps using a combination of CMake and gradle, where CMake is the master and gradle is the worker, which is opposite to the documented methods that are the other way around.
In order to get the Qt integration built and included in the app the essential information needed, without details, is that: the main executable needs to be linked with libsentry.so; libsentry.so needs to be built with Qt integration on and using the same configuration that Qt Creator uses for the app; the appropriate .aar and .jar files from sentry-java need to be packaged in the app; sentry needs to be initialised via a JNI call. This requires some non-trivial, but not complex or extensive, additions to the sentry-android-ndk build script.
It is also possible to build libcurl into sentry-native as the transport.

[kahest]

Hey @glennra thanks for your thoughts. You're correct that it works to some extent, and in order to officially fully support this, we want better docs and also automated tests etc. We'll use this GH issue to track this for now and we appreciate your input.