search

BelledonneCommunications / linphone-sdk

Mirror for linphone-sdk (https://gitlab.linphone.org/BC/public/linphone-sdk.git)
GNU Affero General Public License v3.0
107 stars 81 forks source link

readme

pipeline status

Linphone-SDK

Linphone-SDK is a project that bundles Liblinphone and its dependencies as git submodules, in the purpose of simplifying the compilation and packaging of the whole Liblinphone suite, comprising Mediastreamer2, Belle-sip, oRTP and many others. Its compilation produces a SDK suitable to create applications running on top of these components. The submodules that are not developed or maintained by the Linphone team are grouped in the external/ directory. The currently supported platforms are Android, iOS, Desktop (Linux, Windows, Mac OS X) and UWP (Universal Windows Platform).

License

Copyright © Belledonne Communications

The software products developed in the context of the Linphone project are dual licensed, and are available either :

Build dependencies

Common to all target platforms

The following tools must be installed on the build machine:

If you are building the AV1 codec, which is enabled by default (ENABLE_AV1=Off to disable), you will also need:

Retrieve the dependencies

Linphone-SDK's git repository comprises git submodules. It must be cloned with the --recursive option. After updating or switching branches, never forget to checkout and update the submodules with:

git submodule update --init --recursive

Windows

SDK compilation is supported on Visual Studio 15 2017/Visual Studio 16 2019 and MSYS2 https://www.msys2.org/.

Only CMake, 7Zip and MSYS2 are needed before the build. Add the 7Zip executable in your PATH as it is not automatically done.

MSYS2

Follow MSYS2 instructions on their "Getting Started" page.

Both MinGW32 and MinGW64 are supported.

When building the SDK and if you set -DENABLE_WINDOWS_TOOLS_CHECK=ON, it will install automatically from MSYS2 : toolchain, python, doxygen, perl, yasm, gawk, bzip2, nasm, sed, intltool, graphviz, meson and ninja (if needed)

In this order, add C:\msys64\mingw<N>\bin, C:\msys64\ and C:\msys64\usr\bin in your PATH environement variable from Windows advanced settings. Binaries from the msys folder (not from mingw32/64) doesn't fully support Windows Path and thus, they are to be avoided. is the version of MinGW32/64

Visual Studio

Visual Studio must also be properly configured with addons. Under "Tools"->"Obtain tools and features", make sure that the following components are installed:

For Visual Studio 2022 :

Build

A build with the Ninja generator (-G "Ninja") or the Ninja Multi-Config generator (-G "Ninja Multi-Config") is preferred for speed-up build times.

There are two slightly different ways to build, depending on whether you use a multi-config CMake generator (Xcode, Ninja Multi-Config, Visual Studio) or not (Unix Makefiles, Ninja). In both cases, the steps are:

  1. Configure the project
  2. Build the project

The steps described here are the base for building, but a few specifics behaviors for each platform are good to know and are described in the next subsections.

Multi-Config generator

In the case of a multi-config generator, you will:

  1. Execute CMake to configure the project by giving the preset you want to build (you can get the list of presets available with the cmake --list-presets command), the build directory where you want the build to take place, the generator you want to use and eventually some additional options: cmake --preset=<PRESET> -B <BUILD DIRECTORY> -G <MULTI-CONFIG GENERATOR> <SOME OPTIONS>
  2. Build the SDK: cmake --build <BUILD DIRECTORY> --config <CONFIG> or cmake --build <BUILD DIRECTORY> --config <CONFIG> --parallel <number of jobs> (which is faster).

The <CONFIG> is one of these:

Unique config generator

In this case, you will need to choose the build configuration in the first step, the configuration one. For that, you need to use the CMAKE_BUILD_TYPE=<CONFIG> option, and then you do not need to pass the --config <CONFIG> option in the build step. This will give:

  1. Configure the project: cmake --preset=<PRESET> -B <BUILD DIRECTORY> -G <GENERATOR> -DCMAKE_BUILD_TYPE=<CONFIG> <SOME OPTIONS>
  2. Build the SDK: cmake --build <BUILD DIRECTORY>

iOS

Requirement:

Sample configuration for arm64 targeting iPhone only in Debug mode:

cmake --preset=ios-sdk -G Xcode -B build-ios -DLINPHONESDK_IOS_PLATFORM=Iphone -DLINPHONESDK_IOS_ARCHS="arm64" cmake --build build-ios --config Debug

You can also build using the 'Ninja' or 'Unix makefiles' generators:

cmake --preset=ios-sdk -G Ninja -B build-ios -DCMAKE_BUILD_TYPE=Debug cmake --build build-ios

If the generator is not specified, Xcode will be used by default.

⚙ Note to developers: If a new Apple .framework folder needs to be added to the iOS build, remember to update the NuGet iOS project to include it.

Android (using Docker)

Download the Docker image of the Android build environment:

public access, with token

Use this token to access the Docker registry :

user : gitlab+deploy-token-17

pass : fFVgA_5Mf-qn2WbvsKRL

private access

A simple login with your Gitlab account should work. To know what docker image to pull, first check .gitlab-ci-files/android/builds.yml Currently we are using bc-dev-android-r27 image name.

You'll find the associated tag in .gitlab-ci-files/.docker-images.yml (for Android R27 image it is currently 20240717_update_ndk).

Replace <name> and <tag> in the commands below by the value you found.

docker login gitlab.linphone.org:4567/bc/public/linphone-sdk
docker pull gitlab.linphone.org:4567/bc/public/linphone-sdk/<name>:<tag>

Load the build environment:

cd <linphone-sdk-source>
docker run -it --volume=$PWD:/home/bc/linphone-sdk gitlab.linphone.org:4567/bc/public/linphone-sdk/<name>:<tag> /bin/bash -i

Next command lines must be typed in the docker shell:

# Configure the build
cmake --preset=android-sdk -B build-android -DLINPHONESDK_ANDROID_ARCHS=arm64 -DCMAKE_BUILD_TYPE=RelWithDebInfo <extra-variable-definitions>

# Build
cmake --build build-android --parallel <number of jobs>

# Quit build environment
exit

The freshly built SDK is located in the build-android/ directory.

MacOS

Requirement:

Configure the project with:

cmake --preset=mac-sdk -B build-mac -G Xcode

And build it with:

cmake --build build-mac --config RelWithDebInfo

As for the iOS build, you can alternatively build with Ninja instead of Xcode by specifying it during the configuration step:

cmake --preset=mac-sdk -B build-mac -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build-mac

Windows

Requirement:

Configure the project with:

cmake --preset=windows-sdk -B build-windows

As for all other platforms, you can then build with:

cmake --build build-windows --config RelWithDebInfo

However it may be convenient to build from Visual Studio, which you can do:

Windows UWP and Stores

Requirement:

You can use linphone-sdk in your Windows UWP app with the UWP mode. Win32 application can use the Windows Store mode in order to be publishable in Windows Stores. The Windows Bridge mode is built by using the windows-store preset instead of the windows one. The UWP mode is built by using the uwp preset instead of the windows one. If -DLINPHONESDK_UWP_ARCHS is not used, x86 and x64 will be build.

Then, you can inject directly all your libraries that you need or package the SDK in a Nuget package.

NuGet packaging

The Linphone SDK is available as a .nuget package for .NET applications (Windows & Xamarin).

See the cmake/NuGet folder for build instructions.

Python wrapper & wheel packaging

To build the python wrapper, you first need to install cython tool using pip. If you want to build the documentation, also install pdoc tool. Finally install wheel tool to be able to build a .whl package. Minimal python version to build wrapper is 3.10

Then build the SDK with -DENABLE_PYTHON_WRAPPER=ON and optionally -DENABLE_DOC=ON. To generate the wheel package, use wheel target after install target (required for RPATH to be properly set for shared libs inside the wheel).

For example:

cmake --preset=default -B build-python -DENABLE_PYTHON_WRAPPER=ON -DENABLE_DOC=ON
cmake --build build-python --target install
cmake --build build-python --target wheel

Upgrading your SDK

Simply re-invoking cmake --build <BUILD DIRECTORY> in your build directory should update your SDK. If compilation fails, you may need to rebuilding everything by erasing your build directory and restarting your build as explained above.

Customizing the build

The SDK compilation can be customized by passing -D options to CMake when configuring the project. If you know the options you want to use, just pass them to CMake.

Otherwise, you can use the cmake-gui or ccmake commands to configure all the available options interactively.

The following options control the cpu architectures built for a target platform:

These ON/OFF options control the enablement of important features of the SDK, which have an effect on the size of produced size object code:

Android permissions

The SDK declares a bunch of permission it may or may not need depending on your usage.

If you need to remove one or more of them, you can do it in your own app's AndroidManifest.xml file like this:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" tools:node="remove" />

Licensing: GPL third parties versus non GPL third parties

This SDK can be generated in 2 flavors:

To generate the a SDK with GPL third parties, use the -DENABLE_GPL_THIRD_PARTIES=YES option when configuring the project (you can set "NO" to disable explicitly).

Note regarding third party components subject to license

The Linphone SDK can be compiled with third parties code that are subject to patent license, especially: AMR, SILK and H264 codecs. To build a SDK with any of these features you need to enable the ENABLE_NON_FREE_FEATURES option (disabled by default). Before embedding these features in your final application, make sure to have the right to do so.

For more information, please visit our dedicated wiki page

Nuget packaging

You can package 3 kinds of binaries : win32, uwp and win32 with Windows Store Compatibility.

In an another build folder (like buildNuget), set these options. At least one path is needed :

Build the Package:

cmake .. -DLINPHONESDK_PACKAGER=Nuget -DLINPHONESDK_UWP_ZIP_PATH=C:/projects/desktop-uwp/linphone-sdk/builduwp/linphone-sdk
cmake --build . --target ALL_BUILD --config=RelWithDebInfo

The nuget package will be in linphone-sdk/packages The generated package can keep the same file name between each generations on the same git version. Visual studio keep a cache of the Nuget and you need to delete its internal folder to take account any newer version for the same name. The folder can be found in your system path at /.nuget/packages/linphonesdk

Demo app

There is a very limited version of an application that can use this nuget at https://gitlab.linphone.org/BC/public/linphone-windows10