mirror of
https://github.com/microsoft/vcpkg.git
synced 2024-11-29 09:19:07 +08:00
6b117c9c7e
* [vcpkg docs] Change how documenting port functions works Instead of using `##`, use comment blocks for documentation. Also, add some minor docs and change RST -> MD so we actually get docs generated. * add CI stuff * regenerate docs * fix vcpkg_find_acquire_program to not use _execute_process
148 lines
4.0 KiB
Markdown
148 lines
4.0 KiB
Markdown
# vcpkg_check_features
|
|
Check if one or more features are a part of a package installation.
|
|
|
|
## Usage
|
|
```cmake
|
|
vcpkg_check_features(
|
|
OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>
|
|
[FEATURES
|
|
<cuda> <WITH_CUDA>
|
|
[<opencv> <WITH_OPENCV>]
|
|
...]
|
|
[INVERTED_FEATURES
|
|
<cuda> <IGNORE_PACKAGE_CUDA>
|
|
[<opencv> <IGNORE_PACKAGE_OPENCV>]
|
|
...]
|
|
)
|
|
```
|
|
`vcpkg_check_features()` accepts these parameters:
|
|
|
|
* `OUT_FEATURE_OPTIONS`:
|
|
An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS`
|
|
and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
|
|
|
|
This should be set to `FEATURE_OPTIONS` by convention.
|
|
|
|
* `FEATURES`:
|
|
A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.
|
|
For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
|
|
|
|
* `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
|
|
* `-D<OPTION_NAME>=OFF`, otherwise.
|
|
|
|
* `INVERTED_FEATURES`:
|
|
A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.
|
|
For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
|
|
|
|
* `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
|
|
* `-D<OPTION_NAME>=ON`, otherwise.
|
|
|
|
|
|
## Notes
|
|
|
|
The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
|
|
|
|
At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
|
|
|
|
Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.
|
|
If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists,
|
|
two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
|
|
|
|
|
|
## Examples
|
|
|
|
### Example 1: Regular features
|
|
|
|
```cmake
|
|
$ ./vcpkg install mimalloc[asm,secure]
|
|
|
|
# ports/mimalloc/portfile.cmake
|
|
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
|
|
# Keyword FEATURES is optional if INVERTED_FEATURES are not used
|
|
asm MI_SEE_ASM
|
|
override MI_OVERRIDE
|
|
secure MI_SECURE
|
|
)
|
|
|
|
vcpkg_configure_cmake(
|
|
SOURCE_PATH ${SOURCE_PATH}
|
|
PREFER_NINJA
|
|
OPTIONS
|
|
# Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
|
|
${FEATURE_OPTIONS}
|
|
)
|
|
```
|
|
|
|
### Example 2: Inverted features
|
|
|
|
```cmake
|
|
$ ./vcpkg install cpprestsdk[websockets]
|
|
|
|
# ports/cpprestsdk/portfile.cmake
|
|
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
|
|
INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
|
|
brotli CPPREST_EXCLUDE_BROTLI
|
|
websockets CPPREST_EXCLUDE_WEBSOCKETS
|
|
)
|
|
|
|
vcpkg_configure_cmake(
|
|
SOURCE_PATH ${SOURCE_PATH}
|
|
PREFER_NINJA
|
|
OPTIONS
|
|
# Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
|
|
${FEATURE_OPTIONS}
|
|
)
|
|
```
|
|
|
|
### Example 3: Set multiple options for same feature
|
|
|
|
```cmake
|
|
$ ./vcpkg install pcl[cuda]
|
|
|
|
# ports/pcl/portfile.cmake
|
|
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
|
|
cuda WITH_CUDA
|
|
cuda BUILD_CUDA
|
|
cuda BUILD_GPU
|
|
)
|
|
|
|
vcpkg_configure_cmake(
|
|
SOURCE_PATH ${SOURCE_PATH}
|
|
PREFER_NINJA
|
|
OPTIONS
|
|
# Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
|
|
${FEATURE_OPTIONS}
|
|
)
|
|
```
|
|
|
|
### Example 4: Use regular and inverted features
|
|
|
|
```cmake
|
|
$ ./vcpkg install rocksdb[tbb]
|
|
|
|
# ports/rocksdb/portfile.cmake
|
|
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
|
|
FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
|
|
tbb WITH_TBB
|
|
INVERTED_FEATURES
|
|
tbb ROCKSDB_IGNORE_PACKAGE_TBB
|
|
)
|
|
|
|
vcpkg_configure_cmake(
|
|
SOURCE_PATH ${SOURCE_PATH}
|
|
PREFER_NINJA
|
|
OPTIONS
|
|
# Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
|
|
${FEATURE_OPTIONS}
|
|
)
|
|
```
|
|
|
|
## Examples in portfiles
|
|
|
|
* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
|
|
* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
|
|
* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
|
|
|
|
## Source
|
|
[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
|