mirror of https://github.com/microsoft/vcpkg.git synced 2024-11-25 01:51:39 +08:00

[vcpkg docs] Check for documentation generation in CI (#14614 )

* [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

2020-12-01 13:37:26 -08:00

4.0 KiB

Raw Blame History

vcpkg_check_features

Check if one or more features are a part of a package installation.

Usage

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

$ ./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

$ ./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

$ ./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

$ ./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

Source

scripts/cmake/vcpkg_check_features.cmake

4.0 KiB Raw Blame History