Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc /}}
3 {{/box}}
4
5 = What is it? =
6
7 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.
8 Its source code is located in the //linphone-cmake-builder// repository hosted on the //git.linphone.org// server.
9
10
11 You can get it using:
12
13 {{code language="bash"}}
14 git clone git://git.linphone.org/linphone-cmake-builder.git
15 {{/code}}
16
17
18 It is also included in the various Linphone projects as a submodule, eg. it is a submodule of //linphone-android// or //linphone-iphone//.
19
20 = Terminology =
21
22 The Linphone CMake Builder defines:
23
24 * Build targets
25 * Builders
26 * Configurations
27 * Options
28 * Toolchains
29
30 Let's see what each of these concepts are.
31
32 == Build targets ==
33
34 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.
35 The build target being used can be defined by passing the ##-DLINPHONE_BUILDER_TARGET=<target>## option when invoking CMake.
36
37 == Builders ==
38
39 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.
40
41 == Configurations ==
42
43 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.
44 The configuration being used is defined by passing the ##-DLINPHONE_BUILDER_CONFIG_FILE=confis/<config-filename>## option when invoking CMake.
45
46 == Options ==
47
48 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.
49 Here are some examples of options that are defined:
50
51 * ##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.
52 * ##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.
53
54 == Toolchains ==
55
56 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.
57
58 = Defining a builder =
59
60 A builder file is a standard CMake file. It must be named //<builder_name>.cmake//.
61 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.
62
63 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.
64
65 == Getting the source code ==
66
67 The source code of a builder can be obtained using several methods. It can be:
68
69 * Fetched from a git repository: use the //lcb_git_repository//, //lcb_git_tag// and //lcb_git_tag_latest// commands,
70 * A tarball downloaded via HTTP or FTP: use the //lcb_url// and //lcb_ulr_hash// commands,
71 * Already included in the source tree of the meta-project you are building: use the //lcb_external_source_paths// command.
72
73 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.
74
75 === lcb_git_repository, lcb_builder_git_repository ===
76
77 Give a git repository URL to download the source code from git while building the software component.
78
79 Example:
80
81 {{code language="cmake"}}
82 lcb_git_repository("git://git.linphone.org/linphone.git")
83 {{/code}}
84
85 === lcb_git_tag, lcb_builder_git_tag ===
86
87 Give the git tag to fetch from the git repository when getting the source code from git.
88
89 Example:
90
91 {{code language="cmake"}}
92 lcb_git_tag("3.10.0")
93 {{/code}}
94
95 === lcb_git_tag_latest, lcb_builder_git_tag_latest ===
96
97 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.
98
99 Example:
100
101 {{code language="cmake"}}
102 lcb_git_tag_latest("master")
103 {{/code}}
104
105 === lcb_url, lcb_builder_url ===
106
107 An HTTP or FTP URL to use to download a source code tarball.
108
109 Example:
110
111 {{code language="cmake"}}
112 lcb_url("http://downloads.xiph.org/releases/opus/opus-1.1.1.tar.gz")
113 {{/code}}
114
115 === lcb_url_hash, lcb_builder_url_hash ===
116
117 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.
118
119 Example:
120
121 {{code language="cmake"}}
122 lcb_url_hash("MD5=cfb354d4c65217ca32a762f8ab15f2ac")
123 {{/code}}
124
125 === lcb_external_source_paths, lcb_builder_external_source_paths ===
126
127 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.
128
129 Example:
130
131 {{code language="cmake"}}
132 lcb_external_source_paths("mediastreamer2" "linphone/mediastreamer2")
133 {{/code}}
134
135 == Building ==
136
137 === lcb_build_method, lcb_builder_build_method ===
138
139 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//.
140
141 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.
142
143 The //autotools// build method is to build a software component using autogen, autoconf, configure...
144
145 The //custom// build method allows you to define scripts to use to configure, build and install a software component.
146
147 The //dummy// build method just does nothing.
148
149 The //rpm// build method is for building with //rpmbuild//.
150
151 Example:
152
153 {{code language="cmake"}}
154 lcb_build_method("autotools")
155 {{/code}}
156
157 === lcb_cmake_options, lcb_builder_cmake_options ===
158
159 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.
160 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).
161
162 Example:
163
164 {{code language="cmake"}}
165 lcb_cmake_options(
166 "-DENABLE_NON_FREE_CODECS=${ENABLE_NON_FREE_CODECS}"
167 "-DENABLE_UNIT_TESTS=${ENABLE_UNIT_TESTS}"
168 "-DENABLE_DEBUG_LOGS=${ENABLE_DEBUG_LOGS}"
169 "-DENABLE_PCAP=${ENABLE_PCAP}"
170 "-DENABLE_DOC=${ENABLE_DOC}"
171 "-DENABLE_TOOLS=${ENABLE_TOOLS}"
172 )
173 {{/code}}
174
175 === lcb_configure_options, lcb_builder_configure_options ===
176
177 This is exactly the same as //lcb_cmake_options// and //lcb_builder_cmake_options// but for builders using the //autotools// build method.
178
179 Example:
180
181 {{code language="cmake"}}
182 lcb_configure_options(
183 "--disable-v4l-utils"
184 "--disable-qv4l2"
185 "--disable-libdvbv5"
186 "--with-udevdir=${CMAKE_INSTALL_PREFIX}/etc"
187 "--without-jpeg"
188 )
189 {{/code}}
190
191 === lcb_linking_type, lcb_builder_linking_type ===
192
193 Define the options to use regarding the linking type, that is if the software component has to be linking statically, dynamically or both.
194 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.
195 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:
196
197 {{code language="cmake"}}
198 lcb_linking_type("--disable-static" "--enable-shared")
199 {{/code}}
200
201 Example:
202
203 {{code language="cmake"}}
204 lcb_linking_type("-DENABLE_STATIC=YES" "-DENABLE_SHARED=NO")
205 {{/code}}
206
207 === lcb_cross_compilation_options, lcb_builder_cross_compilation_options ===
208
209 These commands work only for the //autotools// build method.
210 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.
211
212 Example:
213
214 {{code language="cmake"}}
215 lcb_cross_compilation_options(
216 "--prefix=${CMAKE_INSTALL_PREFIX}"
217 "--host=${LINPHONE_BUILDER_HOST}"
218 )
219 {{/code}}
220
221 === lcb_make_options, lcb_builder_make_options ===
222
223 These commands work only for the //autotools// build method.
224 They define some additional options to pass to the //make// command.
225
226 Example:
227
228 {{code language="cmake"}}
229 lcb_make_options("RANLIB=\"\$RANLIB\"")
230 {{/code}}
231
232 === lcb_extra_cppflags, lcb_builder_extra_cppflags ===
233
234 Give some additional flags that will be used by the C and C++ compilers.
235
236 Example:
237
238 {{code language="cmake"}}
239 lcb_extra_cppflags("-D__USE_MINGW_ANSI_STDIO")
240 {{/code}}
241
242 === lcb_extra_cflags, lcb_builder_extra_cflags ===
243
244 Give some additional flags that will be used by the C compiler.
245
246 Example:
247
248 {{code language="cmake"}}
249 lcb_extra_cflags("-fembed-bitcode")
250 {{/code}}
251
252 === lcb_extra_cxxflags, lcb_builder_extra_cxxflags ===
253
254 Give some additional flags that will be used by the C++ compiler.
255
256 Example:
257
258 {{code language="cmake"}}
259 lcb_extra_cxxflags("-std=c++11")
260 {{/code}}
261
262 === lcb_extra_ldflags, lcb_builder_extra_ldflags ===
263
264 Give some additional flags that will be used by the linker.
265
266 Example:
267
268 {{code language="cmake"}}
269 lcb_extra_ldflags("-static-libgcc")
270 {{/code}}
271
272 === lcb_extra_asflags, lcb_builder_extra_asflags ===
273
274 Give some additional flags that will be used by the assembler.
275
276 === lcb_build_in_source_tree, lcb_builder_build_in_source_tree ===
277
278 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.
279
280 Example:
281
282 {{code language="cmake"}}
283 lcb_build_in_source_tree(YES)
284 {{/code}}
285
286 === lcb_use_autogen, lcb_builder_use_autogen ===
287
288 These commands work only for the //autotools// and //rpm// build methods.
289 Tell the Linphone CMake Builder to call ##autogen.sh## before calling the ##configure## script.
290
291 Example:
292
293 {{code language="cmake"}}
294 lcb_use_autogen(YES)
295 {{/code}}
296
297 === lcb_use_autoreconf, lcb_builder_use_autoreconf ===
298
299 These commands work only for the //autotools// and //rpm// build methods.
300 Tell the Linphone CMake Builder to call ##autoreconf## before calling the ##configure## script.
301 If //lcb_use_autogen(YES)// is also called in the builder, this command will be ignored.
302
303 Example:
304
305 {{code language="cmake"}}
306 lcb_use_autoreconf(YES)
307 {{/code}}
308
309 === lcb_patch_command, lcb_builder_patch_command ===
310
311 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.
312
313 Example:
314
315 {{code language="cmake"}}
316 lcb_patch_command("${CMAKE_COMMAND}" "-E" "copy" "${CMAKE_CURRENT_SOURCE_DIR}/builders/sqlite3/CMakeLists.txt" "<SOURCE_DIR>")
317 {{/code}}
318
319 === lcb_configure_command_source, lcb_builder_configure_command_source ===
320
321 These commands only work for the //custom// build method.
322 Tell the Linphone CMake Builder the path to the script that will be used for the configure step for this software component.
323
324 Example:
325
326 {{code language="cmake"}}
327 lcb_configure_command_source(${CMAKE_CURRENT_SOURCE_DIR}/builders/openh264/configure.sh.cmake)
328 {{/code}}
329
330 === lcb_build_command_source, lcb_builder_build_command_source ===
331
332 These commands only work for the //custom// build method.
333 Tell the Linphone CMake Builder the path to the script that will be used for the build step for this software component.
334
335 Example:
336
337 {{code language="cmake"}}
338 lcb_build_command_source(${CMAKE_CURRENT_SOURCE_DIR}/builders/openh264/build.sh.cmake)
339 {{/code}}
340
341 === lcb_install_command_source, lcb_builder_install_command_source ===
342
343 These commands only work for the //custom// build method.
344 Tell the Linphone CMake Builder the path to the script that will be used for the install step for this software component.
345
346 Example:
347
348 {{code language="cmake"}}
349 lcb_install_command_source(${CMAKE_CURRENT_SOURCE_DIR}/builders/openh264/install.sh.cmake)
350 {{/code}}
351
352 === lcb_config_h_file, lcb_builder_config_h_file ===
353
354 These commands work only for the //autotools// build method.
355 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.
356
357 Example:
358
359 {{code language="cmake"}}
360 lcb_config_h_file("vpx_config.h")
361 {{/code}}
362
363 === lcb_spec_file, lcb_builder_spec_file ===
364
365 These commands work only for the //rpm// build method.
366 These instruct the Linphone CMake Builder the name of the spec file that will be used by //rpmbuild// to generate the RPM package.
367
368 Example:
369
370 {{code language="cmake"}}
371 lcb_spec_file("ortp.spec")
372 {{/code}}
373
374 === lcb_rpmbuild_name, lcb_builder_rpmbuild_name ===
375
376 These commands work only for the //rpm// build method.
377 These instruct the Linphone CMake Builder the name of the RPM package to generate with //rpmbuild// if it is different than the builder name.
378
379 Example:
380
381 {{code language="cmake"}}
382 lcb_rpmbuild_name("mediastreamer")
383 {{/code}}
384
385 === lcb_install_target, lcb_builder_install_target ===
386
387 These commands work only for the //autotools// and //rpm// build methods.
388 They define the name of the install target if it is different than //install//.
389
390 Example:
391
392 {{code language="cmake"}}
393 lcb_install_target("install-lib-shared")
394 {{/code}}
395
396 === lcb_do_not_use_cmake_flags, lcb_builder_do_not_use_cmake_flags ===
397
398 These commands work only for the //autotools// build method.
399 Tell the Linphone CMake Builder to not pass the default CMake compilation flags to the autotools based build system of the software component.
400
401 Example:
402
403 {{code language="cmake"}}
404 lcb_do_not_use_cmake_flags(YES)
405 {{/code}}
406
407 === lcb_ignore_warnings, lcb_builder_ignore_warnings ===
408
409 Tell the Linphone CMake Builder to add some compilation flags to ignore compilation warnings.
410
411 Example:
412
413 {{code language="cmake"}}
414 lcb_ignore_warnings(YES)
415 {{/code}}
416
417 === lcb_configure_env, lcb_builder_configure_env ===
418
419 These commands work only for the //autotools// and //rpm// build methods.
420 Tell the Linphone CMake Builder to pass some environment variables when running the configure script.
421
422 Example:
423
424 {{code language="cmake"}}
425 lcb_configure_env("CC=$CC")
426 {{/code}}
427
428 === lcb_plugin, lcb_builder_plugin ===
429
430 These commands work only for the //cmake// build method.
431 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//.
432
433 Example:
434
435 {{code language="cmake"}}
436 lcb_plugin(YES)
437 {{/code}}
438
439 == Relation with other builders ==
440
441 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.
442
443 === lcb_dependencies, lcb_builder_dependencies ===
444
445 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.
446
447 Example:
448
449 {{code language="cmake"}}
450 lcb_dependencies("bctoolbox" "bellesip" "ortp" "ms2")
451 {{/code}}
452
453 === lcb_groupable, lcb_builder_groupable ===
454
455 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.
456
457 Example:
458
459 {{code language="cmake"}}
460 lcb_groupable(YES)
461 {{/code}}
462
463 === lcb_may_be_found_on_system, lcb_builder_may_be_found_on_system ===
464
465 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.
466
467 Example:
468
469 {{code language="cmake"}}
470 lcb_may_be_found_on_system(YES)
471 {{/code}}
472
473 = Adding builders without changing the linphone-cmake-builder repository =
474
475 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.
476 The //CMakeLists.txt// file located in this directory will then get included.
477
478 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:
479
480 {{code language="cmake"}}
481 lcb_builder_dependencies("ms2" "libcaca")
482 {{/code}}
483
484 Doing this the Linphone CMake Builder will load the //libcaca.cmake// builder file located in the external builders path.
485
486 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:
487
488 {{code language="cmake"}}
489 lcb_define_target("myliblinphonebasedproject" "linphone")
490 {{/code}}
491
492 It will have the effect to load the //myliblinphonebasedproject.cmake// builder file located in the external builders path.
493
494 To see a full example of this external builders path mechanism, you can clone the [[git:~~/~~/git.linphone.org/external-builders-example.git>>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.