| name: dependency |
| returns: dep |
| description: | |
| Finds an external dependency (usually a library installed on your |
| system) with the given name with `pkg-config` and [with |
| CMake](Dependencies.md#cmake) if `pkg-config` fails. Additionally, |
| frameworks (OSX only) and [library-specific fallback detection |
| logic](Dependencies.md#dependencies-with-custom-lookup-functionality) |
| are also supported. |
| |
| *Since 0.60.0* more than one name can be provided, they will be tried in order |
| and the first name to be found will be used. The fallback subproject will be |
| used only if none of the names are found on the system. Once one of the name has |
| been found, all other names are added into the cache so subsequent calls for any |
| of those name will return the same value. This is useful in case a dependency |
| could have different names, such as `png` and `libpng`. |
| |
| * Since *0.64.0* a dependency fallback can be provided by WrapDB. Simply download |
| the database locally using `meson wrap update-db` command and Meson will |
| automatically fallback to subprojects provided by WrapDB if the dependency is |
| not found on the system and the project does not ship their own `.wrap` file. |
| |
| Dependencies can also be resolved in two other ways: |
| |
| * if the same name was used in a `meson.override_dependency` prior to |
| the call to `dependency`, the overriding dependency will be returned |
| unconditionally; that is, the overriding dependency will be used |
| independent of whether an external dependency is installed in the system. |
| Typically, `meson.override_dependency` will have been used by a |
| subproject. |
| |
| * by a fallback subproject which, if needed, will be brought into the current |
| build specification as if [`subproject()`](#subproject) had been called. |
| The subproject can be specified with the `fallback` argument. Alternatively, |
| if the `fallback` argument is absent, *since 0.55.0* Meson can |
| automatically identify a subproject as a fallback if a wrap file |
| [provides](Wrap-dependency-system-manual.md#provide-section) the |
| dependency, or if a subproject has the same name as the dependency. |
| In the latter case, the subproject must use `meson.override_dependency` to |
| specify the replacement, or Meson will report a hard error. See the |
| [Wrap documentation](Wrap-dependency-system-manual.md#provide-section) |
| for more details. This automatic search can be controlled using the |
| `allow_fallback` keyword argument. |
| |
| If `dependency_name` is `''`, the dependency is always not found. So |
| with `required: false`, this always returns a dependency object for |
| which the `found()` method returns `false`, and which can be passed |
| like any other dependency to the `dependencies:` keyword argument of a |
| `build_target`. This can be used to implement a dependency which is |
| sometimes not required e.g. in some branches of a conditional, or with |
| a `fallback:` kwarg, can be used to declare an optional dependency |
| that only looks in the specified subproject, and only if that's |
| allowed by `--wrap-mode`. |
| |
| The returned object [[@dep]] also has additional methods. |
| |
| notes: |
| - This function supports additional [library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality) |
| keyword arguments that may also be accepted (e.g. `modules` specifies submodules to use for |
| dependencies such as Qt5 or Boost. `components` allows the user to manually |
| add CMake `COMPONENTS` for the `find_package` lookup) |
| |
| varargs: |
| name: names |
| type: str |
| since: 0.60.0 |
| min_varargs: 1 |
| description: | |
| The names of the dependency to look up. The dependencies are looked up in |
| the order they are provided here. The first found dependency will then be |
| used. The fallback subproject will be used only if none of the names are |
| found on the system. Once one of the name has been found, all other names |
| are added into the cache so subsequent calls for any of those name will |
| return the same value. This is useful in case a dependency could have |
| different names, such as `png` and `libpng`. |
| |
| **NOTE:** Before *0.60.0* only a single dependency name was allowed. |
| |
| kwargs: |
| default_options: |
| type: list[str] | dict[str | bool | int | list[str]] |
| since: 0.38.0 |
| description: | |
| An array of default option values |
| that override those set in the subproject's `meson.options` |
| (like `default_options` in [[project]], they only have |
| effect when Meson is run for the first time, and command line |
| arguments override any default options in build files) |
| *(since 1.2.0)*: A dictionary may now be passed. |
| |
| allow_fallback: |
| type: bool |
| since: 0.56.0 |
| description: | |
| Specifies whether Meson should automatically pick a fallback subproject |
| in case the dependency |
| is not found in the system. If `true` and the dependency is not found |
| on the system, Meson will fallback to a subproject that provides this |
| dependency. If `false`, Meson will not fallback even if a subproject |
| provides this dependency. By default, Meson will do so if `required` |
| is `true` or [`enabled`](Build-options.md#features); see the [Wrap |
| documentation](Wrap-dependency-system-manual.md#provide-section) |
| for more details. |
| |
| fallback: |
| type: list[str] | str |
| description: | |
| Manually specifies a subproject fallback |
| to use in case the dependency is not found in the system. |
| This is useful if the automatic search is not applicable or if you |
| want to support versions of Meson older than 0.55.0. If the value is an |
| array `['subproj_name', 'subproj_dep']`, the first value is the name |
| of the subproject and the second is the variable name in that |
| subproject that contains a dependency object such as the return |
| value of [[declare_dependency]] or |
| [[dependency]], etc. Note that this means the |
| fallback dependency may be a not-found dependency, in which |
| case the value of the `required:` kwarg will be obeyed. |
| *Since 0.54.0* the value can be a single string, the subproject name; |
| in this case the subproject must use |
| `meson.override_dependency('dependency_name', subproj_dep)` |
| to specify the dependency object used in the superproject. |
| If the value is an empty list, it has the same effect as |
| `allow_fallback: false`. |
| |
| language: |
| type: str |
| since: 0.42.0 |
| description: | |
| Defines what language-specific dependency to find |
| if it's available for multiple languages. |
| |
| method: |
| type: str |
| since: 0.40.0 |
| default: "'auto'" |
| description: | |
| Defines the way the dependency is detected, the default is |
| `auto` but can be overridden to be e.g. `qmake` for Qt development, |
| and [different dependencies support different values]( |
| Dependencies.md#dependencies-with-custom-lookup-functionality) |
| for this (though `auto` will work on all of them) |
| |
| native: |
| type: bool |
| default: false |
| description: | |
| If set to `true`, causes Meson to find the dependency on |
| the build machine system rather than the host system (i.e. where the |
| cross compiled binary will run on), usually only needed if you build |
| a tool to be used during compilation. |
| |
| not_found_message: |
| type: str |
| since: 0.50.0 |
| description: An optional string that will be printed as a [[message]] if the dependency was not found. |
| |
| required: |
| type: bool | feature |
| default: true |
| description: | |
| When set to `false`, Meson will proceed with the build |
| even if the dependency is not found. |
| |
| When set to a [`feature`](Build-options.md#features) option, the feature |
| will control if it is searched and whether to fail if not found. |
| |
| *(since 0.47.0)* The value of a `feature` option can also be passed. |
| |
| static: |
| type: bool |
| default: false |
| description: | |
| Tells the dependency provider to try to get static |
| libraries instead of dynamic ones (note that this is not supported |
| by all dependency backends) |
| |
| *Since 0.60.0* it also sets `default_library` option accordingly on the fallback |
| subproject if it was not set explicitly in `default_options` keyword argument. |
| |
| version: |
| type: list[str] | str |
| since: 0.37.0 |
| description: | |
| Specifies the required version, |
| a string containing a |
| comparison operator followed by the version string, examples include |
| `>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching. |
| You can also specify multiple restrictions by passing a list to this |
| keyword argument, such as: `['>=3.14.0', '<=4.1.0']`. |
| These requirements are never met if the version is unknown. |
| |
| include_type: |
| type: str |
| default: "'preserve'" |
| since: 0.52.0 |
| description: | |
| An enum flag, marking how the dependency |
| flags should be converted. Supported values are `'preserve'`, `'system'` and |
| `'non-system'`. System dependencies may be handled differently on some |
| platforms, for instance, using `-isystem` instead of `-I`, where possible. |
| If `include_type` is set to `'preserve'`, no additional conversion will be |
| performed. |
| |
| disabler: |
| type: bool |
| default: false |
| since: 0.49.0 |
| description: | |
| Returns a [[disabler]] object instead of a not-found dependency |
| if this kwarg is set to `true` and the dependency couldn't be found. |