--- title: C++ slug: install-guides/cpp icon: {"faIcon":"fa-brands fa-uikit"} createdAt: 2023-08-03T04:37:40.707Z --- You can integrate the Ditto SDK into C++ projects to develop for Linux and Android platforms. # Linux To install the C++ SDK: ::::WorkflowBlock :::WorkflowBlockItem Fetch and extract the Ditto package. ([Downloading and Unpacking Ditto](docId\:bAOuf6IAK9whA6HRtBY9G)) ::: :::WorkflowBlockItem Configure your app to link to the Ditto static library. ([Linking to Ditto](docId\:bAOuf6IAK9whA6HRtBY9G)) ::: :::: ## Downloading and Unpacking Ditto Download `Ditto.tar.gz` and unpack an archive containing the `libditto.a` static library and `Ditto` header: :::CodeblockTabs Linux x86\_64 ```curl curl -O https://software.ditto.live/cpp-linux-x86_64/Ditto/4.8.2/dist/Ditto.tar.gz && tar xvfz Ditto.tar.gz ``` Linux aarch64 ```curl curl -O https://software.ditto.live/cpp-linux-aarch64/Ditto/4.8.2/dist/Ditto.tar.gz && tar xvfz Ditto.tar.gz ``` ::: ## Linking to Ditto Add `-lditto` as a compilation step in the `main.cpp` source file: :::hint{type="info"} For instructions on adding cross-platform Bluetooth Low Energy (LE) capabilities, see [Bluetooth on Linux](docId\:GPnhy_1_KdnqAHpHCOXFi). *BlueZ* is the official Bluetooth protocol stack implementation for Linux systems to communicate with other Bluetooth-enabled platforms. ::: :::CodeblockTabs Linux ```curl # This command assumes: # - You have unzipped the Ditto.tar.gz in a relative directory ./sdk/ # - Your main code entry point is in ./src/main.cpp # # Note that the list of necessary libraries to link with may vary # by Linux distribution and version. g++ -std=c++11 ./src/main.cpp -I ./sdk -lditto -ldl -lrt -pthread -L ./sdk -o dist/main; # Once executed, your output will be available at: ./dist/main ``` ::: # Android The Ditto C++ SDK for Android is available in the Maven Central repository: [https://central.sonatype.com/artifact/live.ditto/ditto-cpp](https://central.sonatype.com/artifact/live.ditto/ditto-cpp) Integrating the C++ SDK into an Android app requires use of the Android Native Development Kit (NDK) and the Java Native Interface (JNI) mechanism. To learn more about the NDK and JNI, see [https://developer.android.com/ndk/guides](https://developer.android.com/ndk/guides). ## Setting Up Your Environment Include the Maven Central repository in your Gradle file, and then synchronize it with your project. :::::WorkflowBlock ::::WorkflowBlockItem From your project-level `build.gradle` file located in the app's root directory, ensure the `mavenCentral()` repository is included in the `repositories` section: :::CodeblockTabs Gradle ```none allprojects { repositories { mavenCentral() } } ``` ::: :::: :::WorkflowBlockItem Synchronize your project with the Gradle file by clicking **File **> **Sync Project with Gradle Files**. ::: ::::: ## Adding the Ditto SDK Dependency Add the Ditto SDK to your app’s `build.gradle` file in the `dependencies` block with the appropriate version: :::CodeblockTabs build.gradle ```none implementation "live.ditto:ditto-cpp:4.9.3" ``` ::: It is also necessary to compile and build with an NDK version that is compatible with the NDK used to build the Ditto SDK. Add this to your app's `build.gradle` in the `android` section: :::CodeblockTabs build.gradle ```kotlin ndkVersion "27.2.12479018" ``` ::: To ensure that your app links properly with the shared objects in the SDK, and that your app has debugging symbols for the SDK, add these rules to your `android` `packagingOptions` block: :::CodeblockTabs build.gradle ```none jniLibs { useLegacyPackaging = true keepDebugSymbols.add("**/*.so") } pickFirst 'lib/**/libc++_shared.so' pickFirst 'lib/**/libditto.so' ``` ::: ## Setting Android Context The C++ SDK for Android requires that the app call `Ditto::set_android_context(JNIEnv* env, jobject context)` with an application context object after creating an instance of the C++ `Ditto` class. This context is required by the SDK on Android to access system resources such as network interfaces and files. ## Configuring Permissions The Android operating system limits access to some device functionality for end-user control and privacy. In order to use this functionality, configure your app to declare and request permissions from end users at runtime: ::::WorkflowBlock :::WorkflowBlockItem Review permissions used by Ditto. ([Declaring Permissions](docId\:Qu1foWj_6upugzGqrdUIw)) ::: :::WorkflowBlockItem Proactively check permission status to avoid unnecessary delay between granting access and Ditto being able to use the feature. ([Requesting Permissions](docId\:Qu1foWj_6upugzGqrdUIw)) ::: :::: ## Declaring Permissions in the Android Manifest Android requires certain permissions to be explicitly requested by the app to access features like Bluetooth Low Energy and Wi-Fi Aware. These permissions must be declared in the app's manifest file and requested from the end user at runtime. The Ditto SDK's `AndroidManifest.xml` includes all of the necessary permissions for enabling its mesh network capabilities. These permissions will automatically be merged with your app's permissions, so you should be aware of them. :::CodeblockTabs AndroidManifest.xml ```xml ``` ::: Some of these permissions have an `android:maxSdkVersion` attribute which means they are not used on devices running newer versions of Android. This is a best practice to respect users' privacy when those permissions are not necessary. However, some apps may still need to use one or more of the above permissions across more versions of Android. This can be accomplished by overriding the permission configuration in your app's `AndroidManifest.xml` To override any of these permission limitations in your app, do the following: :::::WorkflowBlock :::WorkflowBlockItem Open the `AndroidManifest.xml` located in the `app/src/main` directory of your project. ::: ::::WorkflowBlockItem Within the same `` tag, just before the `` tag, add the relevant permissions you want to configure (location example): :::CodeblockTabs AndroidManifest.xml ```xml ``` ::: Note the additional `tools:remove` attribute. This tells the manifest merger to selectively remove the `android:maxSdkVersion` behavior from the associated permissions, changing them to apply to all Android versions. :::: ::::: :::hint{type="info"} For more information, see the official [Permissions on Android](https://developer.android.com/guide/topics/permissions/overview) and [Merge manifest files](https://developer.android.com/build/manage-manifests) documentation. ::: ## Requesting Permissions at Runtime At runtime, your app can call the C++ `Ditto::missing_permissions()` function to get a list of permissions required by Ditto that are missing, and your app can request them. # Importing Ditto From the source code of your app, add `#include ` and provide your access credentials: ```cpp auto identity = Identity::OnlinePlayground("YOUR_APP_ID", "PLAYGROUND_TOKEN", true); try { Ditto ditto = Ditto(identity, dir); ditto.set_minimum_log_level(LogLevel::debug); ditto.start_sync(); } catch (const DittoError &err) { } ```