What is it?

The Linphone CMake Builder is a bunch of CMake scripts that constitute a kind of meta-builder to ease the build of Linphone and all its dependencies.
Its source code is located in the linphone-cmake-builder repository hosted on the git.linphone.org server.

You can get it using:

It is also included in the various Linphone projects as a submodule, eg. it is a submodule of linphone-android or linphone-iphone.

Terminology

The Linphone CMake Builder defines:

• Build targets
• Builders
• Configurations
• Options
• Toolchains

Let's see what each of these concepts are.

Build targets

These are what you ultimately aim to build. The default build target is linphone. However, some others are available, eg. ms2. Using a build target set to ms2 will only build mediastreamer2 and its dependencies, and so linphone and its dependencies other than mediastreamer2 will not get built.
The build target being used can be defined by passing the -DLINPHONE_BUILDER_TARGET=<target> option when invoking CMake.

Builders

The Linphone CMake Builder contains builders definition files in its builders directory. Each file describes how to get the source code and how to build a specific component, usually a library.

Configurations

Configurations are stored in the configs directory and enable to activate/deactivate some features and to override some default values defined in the builders. We have configurations for each of the Linphone applications. For example, we have a configuration for the desktop version of Linphone, one for the Android version, and so on.
The configuration being used is defined by passing the -DLINPHONE_BUILDER_CONFIG_FILE=confis/<config-filename> option when invoking CMake.

Options

CMake options are defined in the Linphone CMake Builder to enable the user to activate/deactivate some features when building its application. These options are grouped by build targets. For example, the CMake options that have an impact on the mediastreamer2 build are located in the options/ms2.cmake file. Common options are located in the options/common.cmake file. This has the effect that if you are targetting ms2 only for instance, options for linphone would not get loaded and so not proposed to the user.
Here are some examples of options that are defined:

• ENABLE_OPENH264: This option is located in the options/ms2.cmake file and has the effect to activate or deactivate the build of the OpenH264 library.
• ENABLE_UNIT_TESTS: This option is located in the options/common.cmake file and is used to enable/disable the build of unit testing libraries/programs globally.

Toolchains

These are standard CMake toolchain files. We have defined toolchain files for each platforms that we support. These files are located in the toolchains directory.

Defining a builder

A builder file is a standard CMake file. It must be named <builder_name>.cmake.
Some commands are put in this file to describe how to get the source code and how to build this software component. Each of these commands have two variants, one beginning with lcb_ and one beginning with lcb_builder_. These are similar but the second one takes an additional first argument being the builder_name. In a builder file, the Linphone CMake Builder knows which builder is being defined so the first variant should be used. However, the second variant should be used in a config file to override the settings of a specific builder.

All the commands can be put in three different groups, the commands describing how to get the source code, the commands describing how to build the software component, and the commands describing the relations of the builder with the other builders and the system.

Getting the source code

The source code of a builder can be obtained using several methods. It can be:

• Fetched from a git repository: use the lcb_git_repository, lcb_git_tag and lcb_git_tag_latest commands,
• A tarball downloaded via HTTP or FTP: use the lcb_url and lcb_ulr_hash commands,
• Already included in the source tree of the meta-project you are building: use the lcb_external_source_paths command.

We recommend using the last method as it prevents from fetching the source code each time the project is built and permits using different versions of a builder in several meta-projects.

lcb_git_repository, lcb_builder_git_repository

Give a git repository URL to download the source code from git while building the software component.

Example:

lcb_git_tag, lcb_builder_git_tag

Give the git tag to fetch from the git repository when getting the source code from git.

Example:

lcb_git_tag_latest, lcb_builder_git_tag_latest

This is the same as lcb_git_tag and lcb_builder_git_tag when is used when the -DLINPHONE_BUILDER_LATEST=YES option is passed to CMake. This is to be able to have a stable and a development version of the builder.

Example:

lcb_url, lcb_builder_url

An HTTP or FTP URL to use to download a source code tarball.

Example:

lcb_url_hash, lcb_builder_url_hash

An integrity hash to check that the downloaded tarball is not corrupted. This is optional and to be used when lcb_url or lcb_builder_url is also used.

Example:

lcb_external_source_paths, lcb_builder_external_source_paths

This is the recommended method to get the source code of a software component. The root directory to search for external source paths is defined by passing the -DLINPHONE_BUILDER_EXTERNAL_SOURCE_PATH=<path> option to CMake. Then all the paths defined with lcb_external_source_paths or lcb_builder_external_source_paths will be appended to the root directory to search for an existing directory. The first existing one will be the one used to build from.

Example:

Building

lcb_build_method, lcb_builder_build_method

Tell the Linphone CMake Builder which build method to use to build the software component. The available values are: autotools, cmake, custom, dummy and rpm.

The default built method is cmake so if you build a software component using CMake you do not need to use lcb_build_method or lcb_builder_build_method at all.

The autotools build method is to build a software component using autogen, autoconf, configure...

The custom build method allows you to define scripts to use to configure, build and install a software component.

The dummy build method just does nothing.

The rpm build method is for building with rpmbuild.

Example:

lcb_cmake_options, lcb_builder_cmake_options

Define CMake options to pass to CMake for this builder. Several options can be passed at once, and the command can be called several times, the new options will simply get added to the already defined ones.
Of course, this option has an effect only if the build method defined with lcb_build_method or lcb_builder_build_method is cmake (the default).

Example:

lcb_configure_options, lcb_builder_configure_options

This is exactly the same as lcb_cmake_options and lcb_builder_cmake_options but for builders using the autotools build method.

Example:

lcb_linking_type, lcb_builder_linking_type

Define the options to use regarding the linking type, that is if the software component has to be linking statically, dynamically or both.
When using the cmake build method, a default value of DEFAULT_VALUE_CMAKE_LINKING_TYPE is used as the linking type. This value is usually defined in the config file.
For other build methods it has to be defined manually. For example, when using the autotools build method, it will usually be called like this:

Example:

lcb_cross_compilation_options, lcb_builder_cross_compilation_options

These commands work only for the autotools build method.
They define some options that will be passed to configure for cross compilation. Note that a second call to one of these commands will override the options passed to a first call.

Example:

lcb_make_options, lcb_builder_make_options

These commands work only for the autotools build method.
They define some additional options to pass to the make command.

Example:

lcb_extra_cppflags, lcb_builder_extra_cppflags

Give some additional flags that will be used by the C and C++ compilers.

Example:

lcb_extra_cflags, lcb_builder_extra_cflags

Give some additional flags that will be used by the C compiler.

Example:

lcb_extra_cxxflags, lcb_builder_extra_cxxflags

Give some additional flags that will be used by the C++ compiler.

Example:

lcb_extra_ldflags, lcb_builder_extra_ldflags

Give some additional flags that will be used by the linker.

Example:

lcb_extra_asflags, lcb_builder_extra_asflags

Give some additional flags that will be used by the assembler.

lcb_build_in_source_tree, lcb_builder_build_in_source_tree

Tell the Linphone CMake Builder to build a software component in its source tree instead of a separate directory. We strongly advise not doing it, but it may be necessary for some software components whose build system is badly designed.

Example:

lcb_use_autogen, lcb_builder_use_autogen

These commands work only for the autotools and rpm build methods.
Tell the Linphone CMake Builder to call autogen.sh before calling the configure script.

Example:

lcb_use_autoreconf, lcb_builder_use_autoreconf

These commands work only for the autotools and rpm build methods.
Tell the Linphone CMake Builder to call autoreconf before calling the configure script.
If lcb_use_autogen(YES) is also called in the builder, this command will be ignored.

Example:

lcb_patch_command, lcb_builder_patch_command

Tell the Linphone CMake Builder to add a step to the build process before configuring the builder to patch its source code. We do not recommend using these commands, you better include the patches to your source code repository.

Example:

lcb_configure_command_source, lcb_builder_configure_command_source

These commands only work for the custom build method.
Tell the Linphone CMake Builder the path to the script that will be used for the configure step for this software component.

Example:

lcb_build_command_source, lcb_builder_build_command_source

These commands only work for the custom build method.
Tell the Linphone CMake Builder the path to the script that will be used for the build step for this software component.

Example:

lcb_install_command_source, lcb_builder_install_command_source

These commands only work for the custom build method.
Tell the Linphone CMake Builder the path to the script that will be used for the install step for this software component.

Example:

lcb_config_h_file, lcb_builder_config_h_file

These commands work only for the autotools build method.
These instruct the Linphone CMake Builder the name of the header file generated by the configure step for the builder. This is needed so that it can detect that the configure as already been done successfully if you build the whole meta-project a second time.

Example:

lcb_spec_file, lcb_builder_spec_file

These commands work only for the rpm build method.
These instruct the Linphone CMake Builder the name of the spec file that will be used by rpmbuild to generate the RPM package.

Example:

lcb_rpmbuild_name, lcb_builder_rpmbuild_name

These commands work only for the rpm build method.
These instruct the Linphone CMake Builder the name of the RPM package to generate with rpmbuild if it is different than the builder name.

Example:

lcb_install_target, lcb_builder_install_target

These commands work only for the autotools and rpm build methods.
They define the name of the install target if it is different than install.

Example:

lcb_do_not_use_cmake_flags, lcb_builder_do_not_use_cmake_flags

These commands work only for the autotools build method.
Tell the Linphone CMake Builder to not pass the default CMake compilation flags to the autotools based build system of the software component.

Example:

lcb_ignore_warnings, lcb_builder_ignore_warnings

Tell the Linphone CMake Builder to add some compilation flags to ignore compilation warnings.

Example:

lcb_configure_env, lcb_builder_configure_env

These commands work only for the autotools and rpm build methods.
Tell the Linphone CMake Builder to pass some environment variables when running the configure script.

Example:

lcb_plugin, lcb_builder_plugin

These commands work only for the cmake build method.
If you pass YES to lcb_plugin or lcb_builder_plugin you inform the Linphone CMake Builder that it has to use the DEFAULT_VALUE_CMAKE_PLUGIN_LINKING_TYPE instead of DEFAULT_VALUE_CMAKE_LINKING_TYPE. But the linking type can still be overridden using lcb_linking_type or lcb_builder_linking_type.

Example:

Relation with other builders

When building a specific build target, a builder with the same name will get included. Then all the builders declared as dependencies of this first builder will also get included, and this process will iterate recursively.

lcb_dependencies, lcb_builder_dependencies

Declare dependencies on other builders. Several dependencies can be passed at once, and the command can be called several times, the new dependencies will simply get added the already defined ones.

Example:

lcb_groupable, lcb_builder_groupable

This command is used by the Belledonne Communications projects only and you should not use it. It's just a way to group all our projects in a single one instead of building them separately. That way we have access to all our source code in a single IDE project instead of several ones, which eases the development.

Example:

lcb_may_be_found_on_system, lcb_builder_may_be_found_on_system

This declares a builder as potentially already available on the build system. If the -DLINPHONE_BUILDER_USE_SYSTEM_DEPENDENCIES=YES option is passed to CMake then this builder will be bypassed to use the dependency found on the system instead.

Example:

Adding builders without changing the linphone-cmake-builder repository

The Linphone CMake Builder includes a mechanism to include builders from an external directory. You provide the path to this directory (an absolute path) with the -DLINPHONE_BUILDER_EXTERNAL_BUILDERS_PATH option to CMake.
The CMakeLists.txt file located in this directory will then get included.

In this file, you can add new dependencies to a existing builder from the Linphone CMake Builder. For instance, this command will add a dependency of mediastreamer2 on the new libcaca builder:

Doing this the Linphone CMake Builder will load the libcaca.cmake builder file located in the external builders path.

You can also add completely new build targets in the CMakeLists.txt file located in the external builders path. For instance, this command will add a new myliblinphonebasedproject build target that depends on the linphone build target:

It will have the effect to load the myliblinphonebasedproject.cmake builder file located in the external builders path.

To see a full example of this external builders path mechanism, you can clone the git://git.linphone.org/external-builders-example.git repository and call CMake with the -DLINPHONE_BUILDER_EXTERNAL_BUILDERS_PATH=<path_where_you_cloned_the_external_builders_example_repository -DLINPHONE_BUILDER_TARGET=myliblinphonebasedproject options.