Customizing The Building Kamailio With CMake Options
Building Kamailio From Source Using CMake - ToC
When building Kamailio from source using CMake, you can customize the build process by passing various configuration options. These options allow you to tailor the build to your specific needs, such as specifying the installation prefix, including or excluding modules, and enabling or disabling features.
NOTE: We assume that our current working directory is the root of the Kamailio source tree and therefore we use -S . -B build in the examples below.
The alternative is to change directory to the build directory and use cmake .. [all the options].
Configure the Build
Select generator (Optional, You can omit this step)
Default is platform dependant (make for UNIX)
We can use generators that produces build instructions for make, ninja or other supported generators.
This should be provided as a parameter to the cmake command:
CMAKE_INSTALL_PREFIX
The CMAKE_INSTALL_PREFIX option specifies the directory where Kamailio will be installed. By default, Kamailio is installed in /usr/local. To change the installation prefix, use the following command:
Replace /path/to/installation/directory with the desired installation directory.
INCLUDE_MODULES and EXCLUDE_MODULES
Kamailio has a wide range of modules that can be included or excluded from the build. The INCLUDE_MODULES and EXCLUDE_MODULES options allow you to specify which modules to include or exclude.
To include specific modules, use the following command:
Replace module1,module2,module3 with the names of the modules you want to include, separated by space.
Note: If you specify both INCLUDE_MODULES and EXCLUDE_MODULES, the EXCLUDE_MODULES option takes precedence. This means that if a module is listed in both options, it will be excluded from the build, even if it is also listed in the INCLUDE_MODULES option.
To exclude specific modules, use the following command:
Replace module4 module5 module6 with the names of the modules you want to exclude, separated by space.
MODULE_GROUP_NAME
The MODULE_GROUP_NAME option allows you to specify a module group name. This is useful for organizing modules into logical groups. You can provide multiple group names separated by space.
To set a custom module group name, use the following command:
Replace GROUP with the desired module group name. By default, the module group name is set to DEFAULT. You can see the available group names in the groups.cmake file and cmake will print if you provide and invalid group name.
Special group names:
ALL: Includes all available modules. (no grouping applied - all modules are built)DEFAULT: Includes the default set of modules for the core which have no dependencies.ALL_PACKAGED: This will expand to include all groups defined ingroups.cmakein${MODULE_GROUP_PACKAGE_GROUPS}variable. Useful to build all modules but as part of their respective package groups.
BUILD_DOC
The BUILD_DOC option controls whether documentation is built or not. To enable documentation building, use the following command:
To disable documentation building, use the following command:
VERBOSE
The VERBOSE option controls the verbosity of the build process. To enable verbose output, use the following command:
To disable verbose output, use the following command:
USE_TLS
The USE_TLS option controls whether TLS support is enabled or not. To enable TLS support, use the following command:
To disable TLS support, use the following command:
Other Feature Options
Kamailio offers various feature options that can be enabled or disabled during the build process. Some examples (but not limited) include:
USE_MCAST: Enables or disables Multicast.USE_DNS_CACHE: Enables or disables DNS cache.USE_DNS_FAILOVER: Enables or disables DNS failover.LUAJIT: Enable LuaJIT (for app_lua modules).
To see the full list of feature options (this will include some variables pointing to found libraries and also CMAKE configureable variables like CMAKE_BUILD_TYPE:STRING=),
or if you prefer there is a ccmake terminal-GUI tool that can be used to configure the build.
sudo apts install cmake-curses-gui
ccmake .. # from the build directory
# Use arrow keys to navigate, Enter to select.
# Press 't' to toggle advancded variables like external packages location.
# Press 'c' to configure (this will run cmake configuration step).
# Press 'g' to generate Makerfiles or whatever build system you use.
To enable or disable these features, use the following format:
Replace FEATURE_OPTION with the name of the feature you want to enable or disable, and ON/OFF with the desired state.
EXTRA_DEFS
Some build definitions are present in the Kamailio codebase but are not yet exposed as dedicated CMake options.
To set these, you can use the EXTRA_DEFS CMake option, which accepts a semicolon-separated list of definitions to pass to the build system.
Example usage:
Replace DEFINITION and ANOTHER_DEF=VALUE with the actual definitions you want to set.
Advanced Feature Options
Some features may require additional configuration, such as specifying paths to external libraries or setting specific flags. These advanced options can also be set using the -D flag with the cmake command in configuration phase.
LOCK_METHOD
The LOCK_METHOD option allows you to specify the locking mechanism used by Kamailio. To set the locking method, use the following command:
Replace method_name with the desired locking method. Available methods are:
- AUTO: Automatically select the best available locking method. (default)
- FAST_LOCK: Use fast lock mechanism
- FUTEX: Use futex locking mechanism
- PTHREAD_MUTEX: Use pthread mutex locking mechanism.
- POSIX_SEM: Use POSIX semaphores locking mechanism.
- SYSV_SEM: Use System V semaphores locking mechanism.
RADIUSCLIENT
The RADIUSCLIENT option allows you to specify the RADIUS client library to be used by Kamailio modules. To set the RADIUS client library, use the following command:
Replace library_name with the desired RADIUS client library. Available libraries are:
- FREERADIUS: Use FreeRADIUS client library.
- RADCLI: Use RADCLI client library. (default)
- RADIUSCLIENT_NG: Use RADIUSCLIENT_NG client library. (discontinued, should be avoided, use FREERADIUS instead)
LIBSSL_STATIC_SRCPATH
Note: This option is relevant only when LIBSSL_STATIC=ON and LIBSSL_STATIC_SRCLIB=ON are set for the tls or tlsa module.
The LIBSSL_STATIC_SRCPATH option allows you to specify the path for a static version of the OpenSSL library built from sources. This is useful if you want to link Kamailio tls modules statically with
OpenSSL.
CMake modules defining external packages
Kamailio CMake build system includes CMake modules for finding and configuring various external packages. These modules are located in the cmake/modules directory of the Kamailio source tree.
Some of the available CMake modules for external packages include:
- FindErlang.cmake
- FindLdap.cmake
- FindMySQL.cmake
- FindRadius.cmake
along with many others.
These modules can be used to find and configure the corresponding external packages during the build process. You can use these modules by including them in your CMakeLists.txt file and calling the appropriate find_package command.
If you need to customize the paths or settings for these external packages, you can do so by setting the appropriate CMake variables before calling find_package. For example, to specify a custom installation path for the MySQL client library, you can set the MySQL_DIR variable:
See the documentation for each CMake module for more information on the available variables and options.
Example Command
Here's an example command that includes specific modules, excludes others, sets a custom module group name, enables documentation building, and enables TLS support:
cmake -S . -B build -DINCLUDE_MODULES="tls async" -DEXCLUDE_MODULES="db_oracle dnssec jwt microhttpd tls" -DMODULE_GROUP_NAME=DEFAULT -DBUILD_DOC=ON -DUSE_TLS=ON
Remember to replace the module names and the custom module group name with your desired values.
Building the Project
After configuring the project with the desired options, you can build it using the following command: (This will use whatever generator you have configured in your system and configured the project to use see CMAKE_GENERATOR variable)
Build everything configured
See cmake --build docs for more options
which is equivalent to (if you are using a CMAKE_GENERATOR=Unix Makefiles)
make all is the same as make and -j8 will use 8 threads to build the project.
Build a specific target
The following command will be only the target kamailio which is the core of the project.
Every module (each folder inside src/modules/) is a target and you can build it individually by using it's name as the target.
Mind that some modules depending on external libraries will error if their dependencies are not found and prompt you to provide the path to the include folders and library files or install the development package for that library.
For example:
tls will error if openssl is not found: You should either install the openssl development package or provide the path to the openssl include folders and library using the OPENSSL_INCLUDE_DIR and OPENSSL_SSL_LIBRARY variables (See Feature Options with Advanced Variables section above).
Similar variables exist for other libraries.
To build a specific module, use the following command:
#cmake --build build --target <module_name>
cmake --build build --target tls
cmake --build build --target async
or equivalently
Clean the Project
To clean the project, use the following command:
or equivalently
This will remove all the generated files and directories, leaving the source code intact.
Reconfigure the Project
To reconfigure the project, you can simply run the configuration command again:
Note: It's recommended to delete the contents of build directory and create a new one to avoid any potential issues. See next note.
Note: If you have a recent enough version of CMake (>3.24), you can use the --fresh option. This removes any existing CMakeCache.txt file and associated CMakeFiles/ directory, and recreates them from scratch
You can also use a new build directory to avoid any potential issues and apply different compile options for different builds.
cmake -S . -B build_no_tls -DCMAKE_INSTALL_PREFIX=/opt/kamailio-no-tls -DUSE_TLS=OFF [-Dother_option=value [...]]
Install the Project
After building the project, you can install it using the following command:
or equivalently
cd build # if you are not already in the build directory
make install # you may need sudo if install in system paths
This will install the project to the CMAKE_INSTALL_PREFIX if provided or the default /usr/local if not provided.
Uninstall the Project
To uninstall the project, use the following command:
or equivalently
cd build # if you are not already in the build directory
make uninstall # you may need sudo if install in system paths
This will uninstall the project from the CMAKE_INSTALL_PREFIX.
Using Kamailio
After installing Kamailio, you can use it by running the kamailio command.
The rest of the steps should be the same as Step 6: What and where was installed.
For more information on using Kamailio, see the Kamailio documentation.
Troubleshooting
If you encounter any issues during the build process, please check the output for error messages.
If you are unable to resolve the issue, you can seek help on the Kamailio mailing list or open an issue on the Kamailio GitHub repository.