1--- 2short-description: Dependencies for external libraries and frameworks 3... 4 5# Dependencies 6 7Very few applications are fully self-contained, but rather they use 8external libraries and frameworks to do their work. Meson makes it 9very easy to find and use external dependencies. Here is how one would 10use the zlib compression library. 11 12```meson 13zdep = dependency('zlib', version : '>=1.2.8') 14exe = executable('zlibprog', 'prog.c', dependencies : zdep) 15``` 16 17First Meson is told to find the external library `zlib` and error out 18if it is not found. The `version` keyword is optional and specifies a 19version requirement for the dependency. Then an executable is built 20using the specified dependency. Note how the user does not need to 21manually handle compiler or linker flags or deal with any other 22minutiae. 23 24If you have multiple dependencies, pass them as an array: 25 26```meson 27executable('manydeps', 'file.c', dependencies : [dep1, dep2, dep3, dep4]) 28``` 29 30If the dependency is optional, you can tell Meson not to error out if 31the dependency is not found and then do further configuration. 32 33```meson 34opt_dep = dependency('somedep', required : false) 35if opt_dep.found() 36 # Do something. 37else 38 # Do something else. 39endif 40``` 41 42You can pass the `opt_dep` variable to target construction functions 43whether the actual dependency was found or not. Meson will ignore 44non-found dependencies. 45 46Meson also allows to get variables that are defined in the 47`pkg-config` file. This can be done by using the 48`get_pkgconfig_variable` function. 49 50```meson 51zdep_prefix = zdep.get_pkgconfig_variable('prefix') 52``` 53 54These variables can also be redefined by passing the `define_variable` 55parameter, which might be useful in certain situations: 56 57```meson 58zdep_prefix = zdep.get_pkgconfig_variable('libdir', define_variable: ['prefix', '/tmp']) 59``` 60 61The dependency detector works with all libraries that provide a 62`pkg-config` file. Unfortunately several packages don't provide 63pkg-config files. Meson has autodetection support for some of these, 64and they are described [later in this 65page](#dependencies-with-custom-lookup-functionality). 66 67# Arbitrary variables from dependencies that can be found multiple ways 68 69*Note* new in 0.51.0 70*new in 0.54.0, the `internal` keyword* 71 72When you need to get an arbitrary variables from a dependency that can 73be found multiple ways and you don't want to constrain the type you 74can use the generic `get_variable` method. This currently supports 75cmake, pkg-config, and config-tool based variables. 76 77```meson 78foo_dep = dependency('foo') 79var = foo_dep.get_variable(cmake : 'CMAKE_VAR', pkgconfig : 'pkg-config-var', configtool : 'get-var', default_value : 'default') 80``` 81 82It accepts the keywords 'cmake', 'pkgconfig', 'pkgconfig_define', 83'configtool', 'internal', and 'default_value'. 'pkgconfig_define' 84works just like the 'define_variable' argument to 85`get_pkgconfig_variable`. When this method is invoked the keyword 86corresponding to the underlying type of the dependency will be used to 87look for a variable. If that variable cannot be found or if the caller 88does not provide an argument for the type of dependency, one of the 89following will happen: If 'default_value' was provided that value will 90be returned, if 'default_value' was not provided then an error will be 91raised. 92 93# Declaring your own 94 95You can declare your own dependency objects that can be used 96interchangeably with dependency objects obtained from the system. The 97syntax is straightforward: 98 99```meson 100my_inc = include_directories(...) 101my_lib = static_library(...) 102my_dep = declare_dependency(link_with : my_lib, 103 include_directories : my_inc) 104``` 105 106This declares a dependency that adds the given include directories and 107static library to any target you use it in. 108 109# Building dependencies as subprojects 110 111Many platforms do not provide a system package manager. On these 112systems dependencies must be compiled from source. Meson's subprojects 113make it simple to use system dependencies when they are available and 114to build dependencies manually when they are not. 115 116To make this work, the dependency must have Meson build definitions 117and it must declare its own dependency like this: 118 119```meson 120 foo_dep = declare_dependency(...) 121``` 122 123Then any project that wants to use it can write out the following 124declaration in their main `meson.build` file. 125 126```meson 127 foo_dep = dependency('foo', fallback : ['foo', 'foo_dep']) 128``` 129 130What this declaration means is that first Meson tries to look up the 131dependency from the system (such as by using pkg-config). If it is not 132available, then it builds subproject named `foo` and from that 133extracts a variable `foo_dep`. That means that the return value of 134this function is either an external or an internal dependency object. 135Since they can be used interchangeably, the rest of the build 136definitions do not need to care which one it is. Meson will take care 137of all the work behind the scenes to make this work. 138 139# Dependency detection method 140 141You can use the keyword `method` to let Meson know what method to use 142when searching for the dependency. The default value is `auto`. 143Additional methods are `pkg-config`, `config-tool`, `cmake`, 144`builtin`, `system`, `sysconfig`, `qmake`, `extraframework` and `dub`. 145 146```meson 147cups_dep = dependency('cups', method : 'pkg-config') 148``` 149 150For dependencies without [specific detection 151logic](#dependencies-with-custom-lookup-functionality), the dependency method 152order for `auto` is: 153 154 1. `pkg-config` 155 2. `cmake` 156 3. `extraframework` (OSX only) 157 158## System 159 160Some dependencies provide no valid methods for discovery, or do so only in 161some cases. Some examples of this are Zlib, which provides both pkg-config 162and cmake, except when it is part of the base OS image (such as in FreeBSD 163and macOS); OpenGL which has pkg-config on Unices from glvnd or mesa, but has 164no pkg-config on macOS and Windows. 165 166In these cases Meson provides convenience wrappers in the form of `system` 167dependencies. Internally these dependencies do exactly what a user would do 168in the build system DSL or with a script, likely calling 169`compiler.find_library()`, setting `link_with` and `include_directories`. By 170putting these in Meson upstream the barrier of using them is lowered, as 171projects using Meson don't have to re-implement the logic. 172 173## Builtin 174 175Some dependencies provide no valid methods for discovery on some systems, 176because they are provided internally by the language. One example of this is 177intl, which is built into GNU or musl libc but otherwise comes as a `system` 178dependency. 179 180In these cases Meson provides convenience wrappers for the `system` dependency, 181but first checks if the functionality is usable by default. 182 183## CMake 184 185Meson can use the CMake `find_package()` function to detect 186dependencies with the builtin `Find<NAME>.cmake` modules and exported 187project configurations (usually in `/usr/lib/cmake`). Meson is able to 188use both the old-style `<NAME>_LIBRARIES` variables as well as 189imported targets. 190 191It is possible to manually specify a list of CMake targets that should 192be used with the `modules` property. However, this step is optional 193since Meson tries to automatically guess the correct target based on 194the name of the dependency. 195 196Depending on the dependency it may be necessary to explicitly specify 197a CMake target with the `modules` property if Meson is unable to guess 198it automatically. 199 200```meson 201 cmake_dep = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB']) 202``` 203 204Support for adding additional `COMPONENTS` for the CMake 205`find_package` lookup is provided with the `components` kwarg 206(*introduced in 0.54.0*). All specified componets will be passed 207directly to `find_package(COMPONENTS)`. 208 209Support for packages which require a specified version for CMake 210`find_package` to succeed is provided with the `cmake_package_version` 211kwarg (*introduced in 0.57.0*). The specified `cmake_package_version` 212will be passed directly as the second parameter to `find_package`. 213 214It is also possible to reuse existing `Find<name>.cmake` files with 215the `cmake_module_path` property. Using this property is equivalent to 216setting the `CMAKE_MODULE_PATH` variable in CMake. The path(s) given 217to `cmake_module_path` should all be relative to the project source 218directory. Absolute paths should only be used if the CMake files are 219not stored in the project itself. 220 221Additional CMake parameters can be specified with the `cmake_args` 222property. 223 224## Dub 225 226Please understand that Meson is only able to find dependencies that 227exist in the local Dub repository. You need to manually fetch and 228build the target dependencies. 229 230For `urld`. 231``` 232dub fetch urld 233dub build urld 234``` 235 236Other thing you need to keep in mind is that both Meson and Dub need 237to be using the same compiler. This can be achieved using Dub's 238`-compiler` argument and/or manually setting the `DC` environment 239variable when running Meson. 240``` 241dub build urld --compiler=dmd 242DC="dmd" meson builddir 243``` 244 245## Config tool 246 247[CUPS](#cups), [LLVM](#llvm), [pcap](#pcap), [WxWidgets](#wxwidgets), 248[libwmf](#libwmf), [GCrypt](#libgcrypt), [GPGME](#gpgme), and GnuStep either do not provide pkg-config 249modules or additionally can be detected via a config tool 250(cups-config, llvm-config, libgcrypt-config, etc). Meson has native support for these 251tools, and they can be found like other dependencies: 252 253```meson 254pcap_dep = dependency('pcap', version : '>=1.0') 255cups_dep = dependency('cups', version : '>=1.4') 256llvm_dep = dependency('llvm', version : '>=4.0') 257libgcrypt_dep = dependency('libgcrypt', version: '>= 1.8') 258gpgme_dep = dependency('gpgme', version: '>= 1.0') 259``` 260 261*Since 0.55.0* Meson won't search $PATH any more for a config tool 262binary when cross compiling if the config tool did not have an entry 263in the cross file. 264 265# Dependencies with custom lookup functionality 266 267Some dependencies have specific detection logic. 268 269Generic dependency names are case-sensitive<sup>[1](#footnote1)</sup>, 270but these dependency names are matched case-insensitively. The 271recommended style is to write them in all lower-case. 272 273In some cases, more than one detection method exists, and the `method` 274keyword may be used to select a detection method to use. The `auto` 275method uses any checking mechanisms in whatever order Meson thinks is 276best. 277 278e.g. libwmf and CUPS provide both pkg-config and config-tool support. 279You can force one or another via the `method` keyword: 280 281```meson 282cups_dep = dependency('cups', method : 'pkg-config') 283wmf_dep = dependency('libwmf', method : 'config-tool') 284``` 285 286## AppleFrameworks 287 288Use the `modules` keyword to list frameworks required, e.g. 289 290```meson 291dep = dependency('appleframeworks', modules : 'foundation') 292``` 293 294These dependencies can never be found for non-OSX hosts. 295 296## Blocks 297 298Enable support for Clang's blocks extension. 299 300```meson 301dep = dependency('blocks') 302``` 303 304*(added 0.52.0)* 305 306## Boost 307 308Boost is not a single dependency but rather a group of different 309libraries. To use Boost headers-only libraries, simply add Boost as a 310dependency. 311 312```meson 313boost_dep = dependency('boost') 314exe = executable('myprog', 'file.cc', dependencies : boost_dep) 315``` 316 317To link against boost with Meson, simply list which libraries you 318would like to use. 319 320```meson 321boost_dep = dependency('boost', modules : ['thread', 'utility']) 322exe = executable('myprog', 'file.cc', dependencies : boost_dep) 323``` 324 325You can call `dependency` multiple times with different modules and 326use those to link against your targets. 327 328If your boost headers or libraries are in non-standard locations you 329can set the `BOOST_ROOT`, or the `BOOST_INCLUDEDIR` and 330`BOOST_LIBRARYDIR` environment variables. *(added in 0.56.0)* You can 331also set these parameters as `boost_root`, `boost_include`, and 332`boost_librarydir` in your native or cross machine file. Note that 333machine file variables are preferred to environment variables, and 334that specifying any of these disables system-wide search for boost. 335 336You can set the argument `threading` to `single` to use boost 337libraries that have been compiled for single-threaded use instead. 338 339## CUDA 340 341*(added 0.53.0)* 342 343Enables compiling and linking against the CUDA Toolkit. The `version` 344and `modules` keywords may be passed to request the use of a specific 345CUDA Toolkit version and/or additional CUDA libraries, correspondingly: 346 347```meson 348dep = dependency('cuda', version : '>=10', modules : ['cublas']) 349``` 350 351Note that explicitly adding this dependency is only necessary if you are 352using CUDA Toolkit from a C/C++ file or project, or if you are utilizing 353additional toolkit libraries that need to be explicitly linked to. 354 355## CUPS 356 357`method` may be `auto`, `config-tool`, `pkg-config`, `cmake` or `extraframework`. 358 359## Curses 360 361*(Since 0.54.0)* 362 363Curses (and ncurses) are a cross platform pain in the butt. Meson 364wraps up these dependencies in the `curses` dependency. This covers 365both `ncurses` (preferred) and other curses implementations. 366 367`method` may be `auto`, `pkg-config`, `config-tool`, or `system`. 368 369*New in 0.56.0* The `config-tool` and `system` methods. 370 371To define some of the the preprocessor symbols mentioned in the 372[curses autoconf documentation](http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_with_curses.m4): 373 374```meson 375conf = configuration_data() 376check_headers = [ 377 ['ncursesw/menu.h', 'HAVE_NCURSESW_MENU_H'], 378 ['ncurses/menu.h', 'HAVE_NCURSES_MENU_H'], 379 ['menu.h', 'HAVE_MENU_H'], 380 ['ncursesw/curses.h', 'HAVE_NCURSESW_CURSES_H'], 381 ['ncursesw.h', 'HAVE_NCURSESW_H'], 382 ['ncurses/curses.h', 'HAVE_NCURSES_CURSES_H'], 383 ['ncurses.h', 'HAVE_NCURSES_H'], 384 ['curses.h', 'HAVE_CURSES_H'], 385] 386 387foreach h : check_headers 388 if compiler.has_header(h.get(0)) 389 conf.set(h.get(1), 1) 390 endif 391endforeach 392``` 393 394## Fortran Coarrays 395 396*(added 0.50.0)* 397 398 Coarrays are a Fortran language intrinsic feature, enabled by 399`dependency('coarray')`. 400 401GCC will use OpenCoarrays if present to implement coarrays, while Intel and NAG 402use internal coarray support. 403 404## GPGME 405 406*(added 0.51.0)* 407 408`method` may be `auto`, `config-tool` or `pkg-config`. 409 410## GL 411 412This finds the OpenGL library in a way appropriate to the platform. 413 414`method` may be `auto`, `pkg-config` or `system`. 415 416## GTest and GMock 417 418GTest and GMock come as sources that must be compiled as part of your 419project. With Meson you don't have to care about the details, just 420pass `gtest` or `gmock` to `dependency` and it will do everything for 421you. If you want to use GMock, it is recommended to use GTest as well, 422as getting it to work standalone is tricky. 423 424You can set the `main` keyword argument to `true` to use the `main()` 425function provided by GTest: 426 427```meson 428gtest_dep = dependency('gtest', main : true, required : false) 429e = executable('testprog', 'test.cc', dependencies : gtest_dep) 430test('gtest test', e) 431``` 432 433## HDF5 434 435*(added 0.50.0)* 436 437HDF5 is supported for C, C++ and Fortran. Because dependencies are 438language-specific, you must specify the requested language using the 439`language` keyword argument, i.e., 440 * `dependency('hdf5', language: 'c')` for the C HDF5 headers and libraries 441 * `dependency('hdf5', language: 'cpp')` for the C++ HDF5 headers and libraries 442 * `dependency('hdf5', language: 'fortran')` for the Fortran HDF5 headers and libraries 443 444Meson uses pkg-config to find HDF5. The standard low-level HDF5 445function and the `HL` high-level HDF5 functions are linked for each 446language. 447 448`method` may be `auto`, `config-tool` or `pkg-config`. 449 450*New in 0.56.0* the `config-tool` method. 451*New in 0.56.0* the dependencies now return proper dependency types 452 and `get_variable` and similar methods should work as expected. 453 454## intl 455 456*(added 0.59.0)* 457 458Provides access to the `*gettext` family of C functions. On systems where this 459is not built into libc, tries to find an external library providing them 460instead. 461 462`method` may be `auto`, `builtin` or `system`. 463 464## libgcrypt 465 466*(added 0.49.0)* 467 468`method` may be `auto`, `config-tool` or `pkg-config`. 469 470## libwmf 471 472*(added 0.44.0)* 473 474`method` may be `auto`, `config-tool` or `pkg-config`. 475 476## LLVM 477 478Meson has native support for LLVM going back to version LLVM version 4793.5. It supports a few additional features compared to other 480config-tool based dependencies. 481 482As of 0.44.0 Meson supports the `static` keyword argument for LLVM. 483Before this LLVM >= 3.9 would always dynamically link, while older 484versions would statically link, due to a quirk in `llvm-config`. 485 486`method` may be `auto`, `config-tool`, or `cmake`. 487 488### Modules, a.k.a. Components 489 490Meson wraps LLVM's concept of components in it's own modules concept. 491When you need specific components you add them as modules as Meson 492will do the right thing: 493 494```meson 495llvm_dep = dependency('llvm', version : '>= 4.0', modules : ['amdgpu']) 496``` 497 498As of 0.44.0 it can also take optional modules (these will affect the arguments 499generated for a static link): 500 501```meson 502llvm_dep = dependency( 503 'llvm', version : '>= 4.0', modules : ['amdgpu'], optional_modules : ['inteljitevents'], 504) 505``` 506 507### Using LLVM tools 508 509When using LLVM as library but also needing its tools, it is often 510beneficial to use the same version. This can partially be achieved 511with the `version` argument of `find_program()`. However, 512distributions tend to package different LLVM versions in rather 513different ways. Therefore, it is often better to use the llvm 514dependency directly to retrieve the tools: 515 516```meson 517llvm_dep = dependency('llvm', version : ['>= 8', '< 9']) 518llvm_link = find_program(llvm_dep.get_variable(configtool: 'bindir') / 'llvm-link') 519``` 520 521## MPI 522 523*(added 0.42.0)* 524 525MPI is supported for C, C++ and Fortran. Because dependencies are 526language-specific, you must specify the requested language using the 527`language` keyword argument, i.e., 528 * `dependency('mpi', language: 'c')` for the C MPI headers and libraries 529 * `dependency('mpi', language: 'cpp')` for the C++ MPI headers and libraries 530 * `dependency('mpi', language: 'fortran')` for the Fortran MPI headers and libraries 531 532Meson prefers pkg-config for MPI, but if your MPI implementation does 533not provide them, it will search for the standard wrapper executables, 534`mpic`, `mpicxx`, `mpic++`, `mpifort`, `mpif90`, `mpif77`. If these 535are not in your path, they can be specified by setting the standard 536environment variables `MPICC`, `MPICXX`, `MPIFC`, `MPIF90`, or 537`MPIF77`, during configuration. It will also try to use the Microsoft 538implementation on windows via the `system` method. 539 540`method` may be `auto`, `config-tool`, `pkg-config` or `system`. 541 542*New in 0.54.0* The `config-tool` and `system` method values. Previous 543versions would always try `pkg-config`, then `config-tool`, then `system`. 544 545## NetCDF 546 547*(added 0.50.0)* 548 549NetCDF is supported for C, C++ and Fortran. Because NetCDF dependencies are 550language-specific, you must specify the requested language using the 551`language` keyword argument, i.e., 552 * `dependency('netcdf', language: 'c')` for the C NetCDF headers and libraries 553 * `dependency('netcdf', language: 'cpp')` for the C++ NetCDF headers and libraries 554 * `dependency('netcdf', language: 'fortran')` for the Fortran NetCDF headers and libraries 555 556Meson uses pkg-config to find NetCDF. 557 558## OpenMP 559 560*(added 0.46.0)* 561 562This dependency selects the appropriate compiler flags and/or libraries to use 563for OpenMP support. 564 565The `language` keyword may used. 566 567## pcap 568 569*(added 0.42.0)* 570 571`method` may be `auto`, `config-tool` or `pkg-config`. 572 573## Python3 574 575Python3 is handled specially by Meson: 5761. Meson tries to use `pkg-config`. 5772. If `pkg-config` fails Meson uses a fallback: 578 - On Windows the fallback is the current `python3` interpreter. 579 - On OSX the fallback is a framework dependency from `/Library/Frameworks`. 580 581Note that `python3` found by this dependency might differ from the one 582used in `python3` module because modules uses the current interpreter, 583but dependency tries `pkg-config` first. 584 585`method` may be `auto`, `extraframework`, `pkg-config` or `sysconfig` 586 587## Qt4 & Qt5 588 589Meson has native Qt support. Its usage is best demonstrated with an 590example. 591 592```meson 593qt5_mod = import('qt5') 594qt5widgets = dependency('qt5', modules : 'Widgets') 595 596processed = qt5_mod.preprocess( 597 moc_headers : 'mainWindow.h', # Only headers that need moc should be put here 598 moc_sources : 'helperFile.cpp', # must have #include"moc_helperFile.cpp" 599 ui_files : 'mainWindow.ui', 600 qresources : 'resources.qrc', 601) 602 603q5exe = executable('qt5test', 604 sources : ['main.cpp', 605 'mainWindow.cpp', 606 processed], 607 dependencies: qt5widgets) 608``` 609 610Here we have an UI file created with Qt Designer and one source and 611header file each that require preprocessing with the `moc` tool. We 612also define a resource file to be compiled with `rcc`. We just have to 613tell Meson which files are which and it will take care of invoking all 614the necessary tools in the correct order, which is done with the 615`preprocess` method of the `qt5` module. Its output is simply put in 616the list of sources for the target. The `modules` keyword of 617`dependency` works just like it does with Boost. It tells which 618subparts of Qt the program uses. 619 620You can set the `main` keyword argument to `true` to use the 621`WinMain()` function provided by qtmain static library (this argument 622does nothing on platforms other than Windows). 623 624Setting the optional `private_headers` keyword to true adds the 625private header include path of the given module(s) to the compiler 626flags. (since v0.47.0) 627 628**Note** using private headers in your project is a bad idea, do so at 629your own risk. 630 631`method` may be `auto`, `pkg-config` or `qmake`. 632 633## SDL2 634 635SDL2 can be located using `pkg-confg`, the `sdl2-config` config tool, 636or as an OSX framework. 637 638`method` may be `auto`, `config-tool`, `extraframework` or 639`pkg-config`. 640 641## Shaderc 642 643*(added 0.51.0)* 644 645Shaderc currently does not ship with any means of detection. 646Nevertheless, Meson can try to detect it using `pkg-config`, but will 647default to looking for the appropriate library manually. If the 648`static` keyword argument is `true`, `shaderc_combined` is preferred. 649Otherwise, `shaderc_shared` is preferred. Note that it is not possible 650to obtain the shaderc version using this method. 651 652`method` may be `auto`, `pkg-config` or `system`. 653 654## Threads 655 656This dependency selects the appropriate compiler flags and/or 657libraries to use for thread support. 658 659See [threads](Threads.md). 660 661## Valgrind 662 663Meson will find valgrind using `pkg-config`, but only uses the 664compilation flags and avoids trying to link with it's non-PIC static 665libs. 666 667## Vulkan 668 669*(added 0.42.0)* 670 671Vulkan can be located using `pkg-config`, or the `VULKAN_SDK` 672environment variable. 673 674`method` may be `auto`, `pkg-config` or `system`. 675 676## WxWidgets 677 678Similar to [Boost](#boost), WxWidgets is not a single library but rather 679a collection of modules. WxWidgets is supported via `wx-config`. 680Meson substitutes `modules` to `wx-config` invocation, it generates 681- `compile_args` using `wx-config --cxxflags $modules...` 682- `link_args` using `wx-config --libs $modules...` 683 684### Example 685 686```meson 687wx_dep = dependency( 688 'wxwidgets', version : '>=3.0.0', modules : ['std', 'stc'], 689) 690``` 691 692```shell 693# compile_args: 694$ wx-config --cxxflags std stc 695 696# link_args: 697$ wx-config --libs std stc 698``` 699 700## Zlib 701 702Zlib ships with pkg-config and cmake support, but on some operating 703systems (windows, macOs, FreeBSD, dragonflybsd), it is provided as 704part of the base operating system without pkg-config support. The new 705System finder can be used on these OSes to link with the bundled 706version. 707 708`method` may be `auto`, `pkg-config`, `cmake`, or `system`. 709 710*New in 0.54.0* the `system` method. 711 712<hr> 713<a name="footnote1">1</a>: They may appear to be case-insensitive, if the 714 underlying file system happens to be case-insensitive. 715