linphone-android builds against a prebuilt AAR, and the native SDK is where the debugging starts

The native library is downloaded, not compiled

The build story begins with a sentence that changes what this repository is. If you have Android Studio, you open the project, wait for Gradle synchronization and build and install, because the linphone library is downloaded from the vendor's Maven repository as an AAR file so you do not have to build anything yourself.

That is a significant architectural decision. The app module is Kotlin, but the SIP stack underneath it is native code, and the repository you are looking at does not contain it. Everything else in this README is a consequence of that split.

For a user installing the app it means nothing. For a developer it means the boundary between the two codebases is where your problems will be. A UI bug is in `app/`, and a crash inside the SIP library needs a different toolchain entirely.

The Gradle route for people without Android Studio is the same shape:

./gradlew assembleDebug

compiles the APK, and:

./gradlew installDebug

installs what was compiled. The release variants are named in parallel, `assembleRelease` and `installRelease`, and the README names the output directories as `./app/build/outputs/apk/debug/` and `./app/build/outputs/apk/release/`.

One extra requirement applies to app bundles. When building a release AppBundle you use the `releaseAppBundle` target instead of `release`, you need the NDK installed, and you need an environment variable named `ANDROID_NDK_HOME` containing its path, so that native library symbols are included in the bundle for the Play Store. That step is required when building a release AppBundle for the Play Store.

Building the SDK locally, and pointing Gradle at it

To work on the native code rather than around it, the README gives a four-step procedure.

First clone the linphone-sdk repository recursively from the vendor's GitLab:

git clone https://gitlab.linphone.org/BC/public/linphone-sdk.git --recursive

The `--recursive` matters because submodules carry dependencies of the SDK.

Second, follow the instructions in the linphone-sdk README to build the SDK. The README deliberately does not duplicate them, which is sensible given the SDK is its own project with its own build requirements.

Third, create or edit `gradle.properties` in `$GRADLE_USER_HOME`, usually `~/.gradle/`, and add the absolute path to the build directory, given as an example:

LinphoneSdkBuildDir=/home/<username>/linphone-sdk/build/

Fourth, rebuild the app in Android Studio.

The location of that file is the detail worth noting. It is in the Gradle user home rather than in the project, so it applies to every project you build on that machine, which is how a local SDK gets picked up without changing anything tracked in the repository.

If you build the SDK you will also want the debug AAR rather than the release one, and the README flags that specifically: to have faster builds by default, the release AAR is used even for the debug APK flavour. So a developer who assumes they are debugging with debug libraries may not be. The README states you must make sure the app build script uses the debug AAR and not the release one.

For native debugging the steps are: install LLDB from SDK Tools in Android Studio, go to Run, Edit Configurations, Debugger, select Dual or Native, add the path to the debug libraries such as `build/libs-debug/`, open a native file and set a breakpoint. Combined with the AAR caveat above, that is six steps before you can debug anything.

Three known issues, and they are environment-specific

The known issues section is short and each entry is a fix rather than an explanation, which is the right shape for a list like this.

The first is a build failure. If you see `AAPT: error: resource drawable/linphone_logo_tinted (aka org.linphone:drawable/linphone_logo_tinted) not found`, the fix is to delete the `app/src/main/res/xml/contacts.xml` file, which the README says you can do simply with `git clean -f`, and start the build again.

That is an interesting entry to read carefully. The same symptom appears whenever the referenced drawable is missing from the AAR being resolved, so it is likely tied to a specific SDK version rather than to the checkout.

The second is a startup crash: `couldn't find "libc++_shared.so"` when the app starts. The fix is to clean the project under the Build menu and build again, and additionally to check that the SDK was built for the right CPU architecture, using the `-DLINPHONESDK_ANDROID_ARCHS=armv7,arm64,x86,x86_64` CMake parameter.

That CMake parameter is the useful part. It tells you the SDK build is architecture-selectable, and a local SDK built for only one architecture will produce exactly this crash on any other device. Using the listed architectures can help avoid architecture-related startup failures.

The third is behavioural rather than a build error: push notifications might not work when the app has been started by Android Studio consecutively to an install, and the fix is to remove the app from the recent activity view and start it again using the launcher icon. That is a known quirk of installing over a running process rather than a defect in the notification path.

Symbolising a native crash, and the four things it needs

The native crash section is the most detailed part of the README and it exists because a stack trace from this app is meaningless without preparation.

First, to get a symbolized stack trace you need the debug version of the libraries. If you have not built the SDK locally, the README explains how to get them: go to the vendor's Maven repository, find the directory matching the SDK version that crashed, download the `linphone-sdk-android-<version>-libs-debug.zip` archive, and extract it, which creates a `libs-debug` directory.

Second, you need the `ndk-stack` tool. Third, you possibly need `adb logcat`. And if your computer is not otherwise used for Android development, the tools are downloadable from Google's site under the Command line tools only section.

There is a fourth requirement that is easy to miss: you also need to know the architecture of the libraries that were used, such as armv7, arm64 or x86. Which links back to the CMake parameter in the known issues, since the debug archive you need is architecture-specific.

So the full chain is: identify the SDK version that crashed, find its debug symbols for the right architecture, get ndk-stack, then symbolise. The README also documents building the SDK locally as an alternative way to obtain the debug libraries.

The native debugging section earlier in the README is the alternative path, and it is quicker when it works because the libraries are already local. Its catch is the release AAR being used by default even for debug builds.

Licensing, distribution and what changed in 6.0.0

Linphone is dual licensed, and the two options are not equivalent for a commercial product.

Under a GNU/GPLv3 licence it is free and open source, and the README asks you to make sure you understand and agree with the terms before using it, pointing at the LICENSE file for details. Under a proprietary licence it is available for a fee to be used in closed source applications, with Belledonne Communications as the contact for questions about costs and services.

The GPL-3.0 half is the one that matters for a decision. If you combine it with an Android application and distribute the result, GPL-3.0 obligations may apply, depending on how the code is combined; the proprietary route is available for closed source applications. The copyright is held by Belledonne Communications, and the repository carries a `LICENSE.txt`.

Distribution has three routes. The app is on Google Play and on F-Droid, and APKs signed with the vendor's own key are downloadable from their website, which is the route to take if you want the build they produced rather than a store's.

On the 6.0.0 release, the README calls it a completely new version, designed with UX and UI experts, and says it marks a turning point in design, features and user experience. The named highlights are improved fluidity, real multi-accounts support and asymmetrical video in calls. That release also raised the platform floor: it only works on Android OS 9.0 and newer.

The application itself is fully SIP-based for all calling, presence and instant messaging features, which is worth noting because it means interoperability depends on SIP rather than on a proprietary signalling protocol. Documentation is spread across a features and RFCs page, a public wiki, and tutorials in Kotlin under the vendor's GitLab, plus a Weblate instance for translation.

Editorial conclusion

linphone-android fits a team that needs SIP calling with presence and instant messaging on Android and can accept a dual-licensed dependency where the open source route is GPL-3.0 and the closed source route is paid. Do not adopt it expecting a self-contained Gradle project, since the core is a native library fetched as an AAR; native debugging uses either local debug libraries or a downloaded debug archive. Verify first which SDK version your app build pulls, and keep the debug AAR available, because the README's native crash instructions assume you have symbolised libraries before a stack trace means anything.

Frequently asked questions

Official sources

1. BelledonneCommunications/linphone-android on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases