Debian Codegraph @

subprojects/meson-docs/docs/markdown/Dependencies.md

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