From d9363cc5b7281bf49087ddd20735eb57e9105229 Mon Sep 17 00:00:00 2001 From: Leander Schulten Date: Tue, 25 Jul 2023 15:59:45 +0200 Subject: [PATCH 1/4] Add docs for requested features with platform expressions --- vcpkg/reference/vcpkg-json.md | 46 ++++++++++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index 6c3f0b57..38974a15 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -35,7 +35,7 @@ This example demonstrates a manifest for an application using `boost-system`, `c | Name | Required | Type | Description | |------|----------|--------|-------------| | [builtin-baseline](#builtin-baseline) | No | string | Version pins to use when building as top-level | -| [default-features](#default-features) | No | bool | Require the [features](../users/manifests.md#features) listed as on-by-default | +| [default-features](#default-features) | No | string\|[Feature Object][][] | Require the [features](../users/manifests.md#features) listed as on-by-default | | [dependencies](#dependencies) | No | [Dependency][][] | List of dependencies required to build and use this project | | [description](#description) | Libraries | string or string[] | The project description | | [documentation](#documentation) | No | string | URI to the upstream project's documentation | @@ -77,6 +77,22 @@ The default features are automatically selected if either: Default features handle the specific case of providing a "default" configuration for transitive dependencies that the top-level project may not know about. Ports used by others should almost always use `"default-features": false` for their dependencies. +You can also specify that a default features is only activated on a specific platform by using a [Feature Object][]: + +```json +{ + "name": "my-port", + "default-features": [ + "png", + { + "name": "winssl", + "platform": "windows" + } + ] +} +``` + + See [`"features"`](#features) for more information about features. ### `"description"` @@ -98,7 +114,13 @@ This field lists all the dependencies needed to build and use your library or ap { "name": "arrow", "default-features": false, - "features": [ "json" ] + "features": [ + "json", + { + "name": "mimalloc", + "platform": "windows" + } + ] }, "boost-asio", "openssl", @@ -281,7 +303,7 @@ Each dependency is a string or an object with the following fields: | Name | Required | Type | Description | |------|----------|--------|-------------| | [default-features](#dependency-default-features) | No | bool | Require the features listed as on-by-default | -| [features](#dependency-features) | No | string[] | The list of additional features to require | +| [features](#dependency-features) | No | string\|[Feature Object][][] | The list of additional features to require | | [host](#dependency-host) | No | bool | Require the dependency for the host machine instead of the target | | [name](#dependency-name) | Yes | string | The name of the dependency | | [platform](#dependency-platform) | No | [Platform Expression][] | Qualifier for which platforms to use the dependency | @@ -299,7 +321,13 @@ In most cases, this should be defined to `false` and any needed features should ### [Dependency][]: `"features"` -The list of additional features to require. An array of strings. Optional. +The list of additional features to require. An array of strings and Feature Objects. Optional. + +A [Feature Object][] is an object with the following fields: +- `name` - The name of the feature. A string. Required. +- `platform` - A [Platform Expression][] that limits the platforms where the feature is required. Optional. + +[Feature Object]: #feature-object For example, @@ -307,11 +335,17 @@ For example, { "name": "ffmpeg", "default-features": false, - "features": [ "mp3lame" ] + "features": [ + "mp3lame", + { + "name": "avisynthplus", + "platform": "windows" + } + ] } ``` -Uses the `ffmpeg` library but only requires mp3 encoding support. +Uses the `ffmpeg` library but only requires mp3 encoding support and on windows avisynthplus support. ### [Dependency][]: `"host"` From 0501ac6bc01ddf6e594809d53fbafd60ebb2fba7 Mon Sep 17 00:00:00 2001 From: autoantwort <41973254+autoantwort@users.noreply.github.com> Date: Tue, 25 Jul 2023 21:19:54 +0200 Subject: [PATCH 2/4] Update vcpkg/reference/vcpkg-json.md Co-authored-by: Victor Romero --- vcpkg/reference/vcpkg-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index 38974a15..c0c586f2 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -77,7 +77,7 @@ The default features are automatically selected if either: Default features handle the specific case of providing a "default" configuration for transitive dependencies that the top-level project may not know about. Ports used by others should almost always use `"default-features": false` for their dependencies. -You can also specify that a default features is only activated on a specific platform by using a [Feature Object][]: +You can define platform-specific default features by using a [Feature Object][]: ```json { From e148fbb75eb410c1207df2247f215d4d7eb8fd28 Mon Sep 17 00:00:00 2001 From: autoantwort <41973254+autoantwort@users.noreply.github.com> Date: Tue, 25 Jul 2023 21:21:02 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Victor Romero --- vcpkg/reference/vcpkg-json.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index c0c586f2..963102c9 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -303,7 +303,7 @@ Each dependency is a string or an object with the following fields: | Name | Required | Type | Description | |------|----------|--------|-------------| | [default-features](#dependency-default-features) | No | bool | Require the features listed as on-by-default | -| [features](#dependency-features) | No | string\|[Feature Object][][] | The list of additional features to require | +| [features](#dependency-features) | No | [Feature Object][][] | The list of additional features to require | | [host](#dependency-host) | No | bool | Require the dependency for the host machine instead of the target | | [name](#dependency-name) | Yes | string | The name of the dependency | | [platform](#dependency-platform) | No | [Platform Expression][] | Qualifier for which platforms to use the dependency | @@ -321,12 +321,14 @@ In most cases, this should be defined to `false` and any needed features should ### [Dependency][]: `"features"` -The list of additional features to require. An array of strings and Feature Objects. Optional. +The list of additional features to require. An array of Feature objects. Optional. A [Feature Object][] is an object with the following fields: - `name` - The name of the feature. A string. Required. - `platform` - A [Platform Expression][] that limits the platforms where the feature is required. Optional. +A simple string is also a valid `Feature Object` equivalent to `{ "name": "" }`. + [Feature Object]: #feature-object For example, @@ -345,7 +347,7 @@ For example, } ``` -Uses the `ffmpeg` library but only requires mp3 encoding support and on windows avisynthplus support. +Uses the `ffmpeg` library with mp3 encoding support. On Windows only, `avisynthplus` support is also enabled. ### [Dependency][]: `"host"` From b775da6e5c3f3916baf7b345333d36c70e7a4619 Mon Sep 17 00:00:00 2001 From: Victor Romero Date: Thu, 27 Jul 2023 10:06:33 -0700 Subject: [PATCH 4/4] Update type for `default-features` --- vcpkg/reference/vcpkg-json.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index 963102c9..40d84894 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -35,7 +35,7 @@ This example demonstrates a manifest for an application using `boost-system`, `c | Name | Required | Type | Description | |------|----------|--------|-------------| | [builtin-baseline](#builtin-baseline) | No | string | Version pins to use when building as top-level | -| [default-features](#default-features) | No | string\|[Feature Object][][] | Require the [features](../users/manifests.md#features) listed as on-by-default | +| [default-features](#default-features) | No | [Feature Object][][] | Require the [features](../users/manifests.md#features) listed as on-by-default | | [dependencies](#dependencies) | No | [Dependency][][] | List of dependencies required to build and use this project | | [description](#description) | Libraries | string or string[] | The project description | | [documentation](#documentation) | No | string | URI to the upstream project's documentation |