hdkv/yuzu
1
Fork 0
Code Issues Pull Requests Releases 1 Activity

early-access version 2853

Browse Source
This commit is contained in:
pineappleEA
2022-07-23 03:01:36 +02:00
parent 1f2b5081b5
commit 1f111bb69c
8955 changed files with 418777 additions and 999 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
externals/vcpkg/docs/maintainers/authoring-script-ports.md vendored Executable file
View File

@@ -0,0 +1,45 @@
# Authoring Script Ports
Ports can expose functions for other ports to consume during their build. For
example, the `vcpkg-cmake` helper port exposes the `vcpkg_cmake_configure()`
helper function. Packaging common scripts into a shared helper port makes
maintenance easier because all consumers can be updated from a single place.
Because the scripts come from a port, they can be versioned and depended upon
via all the same mechanisms as any other port.
Script ports are implemented via the `vcpkg-port-config.cmake` extension
mechanism. Before invoking the `portfile.cmake` of a port, vcpkg will first
import `share/<port>/vcpkg-port-config.cmake` from each direct dependency. If
the direct dependency is a host dependency, the import will be performed in the
host installed tree (e.g.
`${HOST_INSTALLED_DIR}/share/<port>/vcpkg-port-config.cmake`).
Only direct dependencies are considered for `vcpkg-port-config.cmake` inclusion.
This means that if a script port relies on another script port, it must
explicitly import the `vcpkg-port-config.cmake` of its dependency.
Script-to-script dependencies should not be marked as host. The dependency from
a target port to a script should be marked host, which means that scripts should
always already be natively compiling. By making script-to-script dependencies
`"host": false`, it ensures that one script can depend upon the other being in
its same install directory.
Ports should never provide a `vcpkg-port-config.cmake` file under a different
`share/` subdirectory than the current port (`${PORT}`).
## Example
```cmake
# ${CURRENT_PACKAGES_DIR}/share/my-helper/vcpkg-port-config.cmake
# This include guard ensures the file will be loaded only once
include_guard(GLOBAL)
# This is how you could pull in a transitive dependency
include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake")
# Finally, it is convention to put each public function into a separate file with a matching name
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_01.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_02.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function_03.cmake")
```

166
externals/vcpkg/docs/maintainers/cmake-guidelines.md vendored Executable file
View File

@@ -0,0 +1,166 @@
# CMake Guidelines
We expect that all CMake scripts that are either:
- In the `scripts/` directory, or
- In a `vcpkg-*` port
should follow the guidelines laid out in this document.
Existing scripts may not follow these guidelines yet;
it is expected that we will continue to update old scripts
to fall in line with these guidelines.
These guidelines are intended to create stability in our scripts.
We hope that they will make both forwards and backwards compatibility easier.
## The Guidelines
- Except for out-parameters, we always use `cmake_parse_arguments()`
rather than function parameters or referring to `${ARG<N>}`.
- This doesn't necessarily need to be followed for "script-local helper functions"
- In this case, positional parameters should be put in the function
declaration (rather than using `${ARG<N>}`),
and should be named according to local rules (i.e. `snake_case`).
- Exception: positional parameters that are optional should be
given a name via `set(argument_name "${ARG<N>}")`, after checking `ARGC`.
- Out-parameters should be the first parameter to a function. Example:
```cmake
function(format out_var)
cmake_parse_arguments(PARSE_ARGV 1 "arg" ...)
# ... set(buffer "output")
set("${out_var}" "${buffer}" PARENT_SCOPE)
endfunction()
```
- There are no unparsed or unused arguments.
Always check for `ARGN` or `arg_UNPARSED_ARGUMENTS`.
`FATAL_ERROR` when possible, `WARNING` if necessary for backwards compatibility.
- All `cmake_parse_arguments` must use `PARSE_ARGV`.
- All `foreach` loops must use `IN LISTS`, `IN ITEMS`, or `RANGE`.
- The variables `${ARGV}` and `${ARGN}` are unreferenced,
except in helpful messages to the user.
- (i.e., `message(FATAL_ERROR "blah was passed extra arguments: ${ARGN}")`)
- We always use functions, not macros or top level code.
- Exception: "script-local helper macros". It is sometimes helpful to define a small macro.
This should be done sparingly, and functions should be preferred.
- Exception: `vcpkg.cmake`'s `find_package`.
- Scripts in the scripts tree should not be expected to need observable changes
as part of normal operation.
- Example violation: `vcpkg_acquire_msys()` has hard-coded packages and versions
that need updating over time due to the MSYS project dropping old packages.
- Example exception: `vcpkg_from_sourceforge()` has a list of mirrors which
needs maintenance, but does not have an observable behavior impact on the callers.
- Rules for quoting: there are three kinds of arguments in CMake -
unquoted (`foo(BAR)`), quoted (`foo("BAR")`), and bracketed (`foo([[BAR]])`).
Follow these rules to quote correctly:
- If an argument contains a variable expansion `${...}`,
it must be quoted.
- Exception: a "splat" variable expansion, when one variable will be
passed to a function as multiple arguments. In this case, the argument
should simply be `${foo}`:
```cmake
vcpkg_list(SET working_directory)
if(DEFINED "arg_WORKING_DIRECTORY")
vcpkg_list(SET working_directory WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
endif()
# calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY,
# else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
do_the_thing(${working_directory})
```
- Otherwise, if the argument contains any escape sequences that are not
`\\`, `\"`, or `\$`, that argument must be a quoted argument.
- For example: `"foo\nbar"` must be quoted.
- Otherwise, if the argument contains a `\`, a `"`, or a `$`,
that argument should be bracketed.
- Example:
```cmake
set(x [[foo\bar]])
set(y [=[foo([[bar\baz]])]=])
```
- Otherwise, if the argument contains characters that are
not alphanumeric or `_`, that argument should be quoted.
- Otherwise, the argument should be unquoted.
- Exception: arguments to `if()` of type `<variable|string>` should always be quoted:
- Both arguments to the comparison operators -
`EQUAL`, `STREQUAL`, `VERSION_LESS`, etc.
- The first argument to `MATCHES` and `IN_LIST`
- Example:
```cmake
if("${FOO}" STREQUAL "BAR") # ...
if("${BAZ}" EQUAL "0") # ...
if("FOO" IN_LIST list_variable) # ...
if("${bar}" MATCHES [[a[bcd]+\.[bcd]+]]) # ...
```
- For single expressions and for other types of predicates that do not
take `<variable|string>`, use the normal rules.
- There are no "pointer" or "in-out" parameters
(where a user passes a variable name rather than the contents),
except for simple out-parameters.
- Variables are not assumed to be empty.
If the variable is intended to be used locally,
it must be explicitly initialized to empty with `set(foo "")` if it is a string variable,
and `vcpkg_list(SET foo)` if it is a list variable.
- `set(var)` should not be used. Use `unset(var)` to unset a variable,
`set(var "")` to set it to the empty string,
and `vcpkg_list(SET var)` to set it to the empty list.
_Note: the empty string and the empty list are the same value;_
_this is a notational difference rather than a difference in result_
- All variables expected to be inherited from the parent scope across an API boundary
(i.e. not a file-local function) should be documented.
Note that all variables mentioned in triplets.md are considered documented.
- Out parameters are only set in `PARENT_SCOPE` and are never read.
See also the helper `z_vcpkg_forward_output_variable()` to forward out parameters through a function scope.
- `CACHE` variables are used only for global variables which are shared internally among strongly coupled
functions and for internal state within a single function to avoid duplicating work.
These should be used extremely sparingly and should use the `Z_VCPKG_` prefix to avoid
colliding with any local variables that would be defined by any other code.
- Examples:
- `vcpkg_cmake_configure`'s `Z_VCPKG_CMAKE_GENERATOR`
- `z_vcpkg_get_cmake_vars`'s `Z_VCPKG_GET_CMAKE_VARS_FILE`
- `include()`s are only allowed in `ports.cmake` or `vcpkg-port-config.cmake`.
- `foreach(RANGE)`'s arguments _must always be_ natural numbers,
and `<start>` _must always be_ less than or equal to `<stop>`.
- This must be checked by something like:
```cmake
if("${start}" LESS_EQUAL "${end}")
foreach(RANGE "${start}" "${end}")
...
endforeach()
endif()
```
- All port-based scripts must use `include_guard(GLOBAL)`
to avoid being included multiple times.
### CMake Versions to Require
- All CMake scripts, except for `vcpkg.cmake`,
may assume the version of CMake that is present in the
`cmake_minimum_required` of `ports.cmake`.
- This `cmake_minimum_required` should be bumped every time a new version
of CMake is added to `vcpkgTools.xml`, as should the
`cmake_minimum_required` in all of the helper `CMakeLists.txt` files.
- `vcpkg.cmake` must assume a version of CMake back to 3.7.2 in general
- Specific functions and options may assume a greater CMake version;
if they do, make sure to comment that function or option
with the required CMake version.
### Changing Existing Functions
- Never remove arguments in non-internal functions;
if they should no longer do anything, just take them as normal and warn on use.
- Never add a new mandatory argument.
### Naming Variables
- `cmake_parse_arguments`: set prefix to `"arg"`
- Local variables are named with `snake_case`
- Internal global variable names are prefixed with `Z_VCPKG_`.
- External experimental global variable names are prefixed with `X_VCPKG_`.
- Internal functions are prefixed with `z_vcpkg_`
- Functions which are internal to a single function (i.e., helper functions)
are named `[z_]<func>_<name>`, where `<func>` is the name of the function they are
a helper to, and `<name>` is what the helper function does.
- `z_` should be added to the front if `<func>` doesn't have a `z_`,
but don't name a helper function `z_z_foo_bar`.
- Public global variables are named `VCPKG_`.

205
externals/vcpkg/docs/maintainers/control-files.md vendored Executable file
View File

@@ -0,0 +1,205 @@
# CONTROL files
**CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
all new features are added only to [vcpkg.json manifest files](manifest-files.md), and we recommend using vcpkg.json for any newly authored port.
Use `./vcpkg format-manifest ports/<portname>/CONTROL` to convert an existing CONTROL file to a vcpkg.json file.**
The `CONTROL` file contains metadata about the port. The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here.
Field names are case-sensitive and start the line without leading whitespace. Paragraphs are separated by one or more empty lines.
[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html
## Source Paragraph
The first paragraph in a `CONTROL` file is the Source paragraph. It must have a `Source`, `Version`, and `Description` field. The full set of fields is documented below.
### Examples:
```no-highlight
Source: ace
Version: 6.5.5
Description: The ADAPTIVE Communication Environment
```
```no-highlight
Source: vtk
Version: 8.2.0
Port-Version: 2
Description: Software system for 3D computer graphics, image processing, and visualization
Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
```
### Recognized fields
#### Source
The name of the port.
When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections.
Package collections to check for conflicts:
+ [Repology](https://repology.org/projects/)
+ [Debian packages](https://www.debian.org/distrib/packages)
+ [Packages search](https://pkgs.org/)
#### Version
The library version.
This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings and are only evaluated for equality.
For tagged-release ports, we follow the following convention:
1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
For example, given:
1. The latest commit was made on 2019-04-19
2. The current version string is `2019-02-14-1`
3. Today's date is 2019-06-01.
Then if you update the source version today, you should give it version `2019-06-01`.
#### Port-Version
The version of the port.
This field is a non-negative integer. It allows one to version the port file separately from the version of the underlying library; if you make a change to a port, without changing the underlying version of the library, you should increment this field by one (starting at `0`, which is equivalent to no `Port-Version` field). When the version of the underlying library is upgraded, this field should be set back to `0` (i.e., delete the `Port-Version` field).
##### Examples:
```no-highlight
Version: 1.0.5
Port-Version: 2
```
```no-highlight
Version: 2019-03-21
```
#### Description
A description of the library.
By convention the first line of the description is a summary of the library. An optional detailed description follows. The detailed description can be multiple lines, all starting with whitespace.
##### Examples:
```no-highlight
Description: C++ header-only JSON library
```
```no-highlight
Description: Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.
MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model. This makes it suitable for "machine
to machine" messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino.
```
#### Homepage
The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
Example:
```no-highlight
Homepage: https://github.com/Microsoft/vcpkg
```
#### Build-Depends
Comma separated list of vcpkg ports the library has a dependency on.
Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified.
*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies*
If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax. If the port does not require any features from the dependency, this should be specified as `portname[core]`.
Dependencies can be filtered based on the target triplet to support differing requirements. These filters use the same syntax as the Supports field below and are surrounded in parentheses following the portname and feature list.
##### Example:
```no-highlight
Build-Depends: rapidjson, curl[core,openssl] (!windows), curl[core,winssl] (windows)
```
#### Default-Features
Comma separated list of optional port features to install by default.
This field is optional.
##### Example:
```no-highlight
Default-Features: dynamodb, s3, kinesis
```
<a name="Supports"></a>
#### Supports
Expression that evaluates to true when the port is expected to build successfully for a triplet.
Currently, this field is only used in the CI testing to skip ports. In the future, this mechanism is intended to warn users in advance that a given install tree is not expected to succeed. Therefore, this field should be used optimistically; in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
The grammar for the supports expression uses standard operators:
- `!expr` - negation
- `expr|expr` - or (`||` is also supported)
- `expr&expr` - and (`&&` is also supported)
- `(expr)` - grouping/precedence
The predefined expressions are computed from standard triplet settings:
- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`
- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
These predefined expressions can be overridden in the triplet file via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option.
This field is optional and defaults to true.
> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
##### Example:
```no-highlight
Supports: !(uwp|arm)
```
## Feature Paragraphs
Multiple optional features can be specified in the `CONTROL` files. It must have a `Feature` and `Description` field. It can optionally have a `Build-Depends` field. It must be separated from other paragraphs by one or more empty lines.
### Example:
```no-highlight
Source: vtk
Version: 8.2.0-2
Description: Software system for 3D computer graphics, image processing, and visualization
Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype, expat, hdf5, libjpeg-turbo, proj4, lz4, libtheora, atlmfc (windows), eigen3, double-conversion, pugixml, libharu, sqlite3, netcdf-c
Feature: openvr
Description: OpenVR functionality for VTK
Build-Depends: sdl2, openvr
Feature: qt
Description: Qt functionality for VTK
Build-Depends: qt5
Feature: mpi
Description: MPI functionality for VTK
Build-Depends: mpi, hdf5[parallel]
Feature: python
Description: Python functionality for VTK
Build-Depends: python3
```
### Recognized fields
#### Feature
The name of the feature.
#### Description
A description of the feature using the same syntax as the port `Description` field.
#### Build-Depends
The list of dependencies required to build and use this feature.
On installation the dependencies from all selected features are combined to produce the full dependency list for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph.

11
externals/vcpkg/docs/maintainers/execute_process.md vendored Executable file
View File

@@ -0,0 +1,11 @@
# execute_process
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/execute_process.md).
Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
is enabled.
In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
## Source
[scripts/cmake/execute\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)

14
externals/vcpkg/docs/maintainers/internal/vcpkg_catalog_release_process.md vendored Executable file
View File

@@ -0,0 +1,14 @@
# vcpkg_catalog_release_process
This document describes the acceptance criteria / process we use when doing a vcpkg release.
1. Generate a new GitHub Personal Access Token with repo permissions.
2. Using the PAT, invoke $/scripts/Get-Changelog.ps1 `-StartDate (previous release date) -EndDate (Get-Date) -OutFile path/to/results.md`
3. Create a new GitHub release in this repo.
4. Submit a vcpkg.ci (full tree rebuild) run with the same SHA as that release.
5. Use the "auto-generate release notes". Copy the "new contributors" and "full changelog" parts to the end of `path/to/results.md`.
6. Change `## New Contributors` to `#### New Contributors`
7. In `path/to/results.md`, update `LINK TO BUILD` with the most recent link to vcpkg.ci run.
8. In `path/to/results.md`, fill out the tables for number of existing ports and successful ports.
9. Replace the contents of the release notes with the contents of `path/to/results.md`
10. After the full rebuild submission completes, update the link to the one for the exact SHA, the counts, and remove "(tentative)".

42
externals/vcpkg/docs/maintainers/internal/vcpkg_tool_release_process.md vendored Executable file
View File

@@ -0,0 +1,42 @@
# vcpkg_tool_release_process
This document describes the acceptance criteria / process we use when doing a vcpkg-tool update,
such as https://github.com/microsoft/vcpkg/pull/23757
1. Verify that all tests etc. are passing in the vcpkg-tool repo's `main` branch, and that the
contents therein are acceptable for release. (Steps after this will sign code there, so this
review is responsible gating what has access to code signing.)
2. Check that the changes there are in fact the changes that we want in that release. (Be aware,
you are responsible for what is about to be signed with a Microsoft code signing certificate by
proceeding)
3. Submit a new full tree rebuild by https://dev.azure.com/vcpkg/public/_build?definitionId=29
(microsoft.vcpkg.ci as of this writing) and queue a new build with the vcpkg-tool SHA overridden
to the one you wish to use. Example:
https://dev.azure.com/vcpkg/public/_build/results?buildId=73664&view=results
4. (Probably the next day) Check over the failures and ensure any differences with the most recent
full rebuild using the previous tool version are understood.
5. On your machine, in a prompt changed to the vcpkg-tool repo,
`git fetch https://github.com/microsoft/vcpkg-tool main && git switch -d FETCH_HEAD`
6. `git push https://devdiv.visualstudio.com/DevDiv/_git/vcpkg FETCH_HEAD:main`
7. Monitor the resulting signed build at:
https://devdiv.visualstudio.com/DefaultCollection/DevDiv/_build?definitionId=13610
and/or manually submit one. (The push is supposed to automatically submit a build but that
has been somewhat unstable at the time of this writing.)
8. The signed build will automatically create a draft GitHub release at
https://github.com/microsoft/vcpkg-tool/releases . Erase the contents filled in there and press
the "auto generate release notes" button. Manually remove any entries created by the automated
localization tools which will start with `* LEGO: Pull request from juno/`.
9. Publish that draft release as "pre-release".
10. Smoke test the 'one liner' installer: (Where 2022-06-15 is replaced with the right release name)
* Powershell:
`iex (iwr https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1)`
* Batch:
`curl -L -o vcpkg-init.cmd https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init.ps1 && .\vcpkg-init.cmd`
* Bash:
`. <(curl https://github.com/microsoft/vcpkg-tool/releases/download/2022-06-15/vcpkg-init -L)`
11. In the vcpkg repo, draft a PR which updates `bootstrap-vcpkg.sh` and `boostrap-vcpkg.ps1`
with the new release date, and update SHAs as appropriate in the .sh script. (For example, see
https://github.com/microsoft/vcpkg/pull/23757)
12. Merge the tool update PR.
13. Change the github release in vcpkg-tool from "prerelease" to "release". (This automatically
updates the aka.ms links)

32
externals/vcpkg/docs/maintainers/internal/z_vcpkg_apply_patches.md vendored Executable file
View File

@@ -0,0 +1,32 @@
# z_vcpkg_apply_patches
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Apply a set of patches to a source tree.
```cmake
z_vcpkg_apply_patches(
SOURCE_PATH <path-to-source>
[QUIET]
PATCHES <patch>...
)
```
The `<path-to-source>` should be set to `${SOURCE_PATH}` by convention,
and is the path to apply the patches in.
`z_vcpkg_apply_patches` will take the list of `<patch>`es,
which are by default relative to the port directory,
and apply them in order using `git apply`.
Generally, these `<patch>`es take the form of `some.patch`
to select patches in the port directory.
One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`.
If `QUIET` is not passed, it is a fatal error for a patch to fail to apply;
otherwise, if `QUIET` is passed, no message is printed.
This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
## Source
[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake)

38
externals/vcpkg/docs/maintainers/internal/z_vcpkg_forward_output_variable.md vendored Executable file
View File

@@ -0,0 +1,38 @@
# z_vcpkg_forward_output_variable
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
This macro helps with forwarding values from inner function calls,
through a local function scope, into pointer out parameters.
```cmake
z_vcpkg_forward_output_variable(ptr_to_parent_var var_to_forward)
```
is equivalent to
```cmake
if(DEFINED ptr_to_parent_var)
if(DEFINED value_var)
set("${ptr_to_parent_var}" "${value_var}" PARENT_SCOPE)
else()
unset("${ptr_to_parent_var}" PARENT_SCOPE)
endif()
endif()
```
Take note that the first argument should be a local variable that has a value of the parent variable name.
Most commonly, this local is the result of a pointer-out parameter to a function.
If the variable in the first parameter is not defined, this function does nothing,
simplifying functions with optional out parameters.
Most commonly, this should be used in cases like:
```cmake
function(my_function out_var)
file(SHA512 "somefile.txt" local_var)
z_vcpkg_forward_output_variable(out_var local_var)
endfunction()
```
## Source
[scripts/cmake/z\_vcpkg\_forward\_output\_variable.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_forward_output_variable.cmake)

29
externals/vcpkg/docs/maintainers/internal/z_vcpkg_function_arguments.md vendored Executable file
View File

@@ -0,0 +1,29 @@
# z_vcpkg_function_arguments
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Get a list of the arguments which were passed in.
Unlike `ARGV`, which is simply the arguments joined with `;`,
so that `(A B)` is not distinguishable from `("A;B")`,
this macro gives `"A;B"` for the first argument list,
and `"A\;B"` for the second.
```cmake
z_vcpkg_function_arguments(<out-var> [<N>])
```
`z_vcpkg_function_arguments` gets the arguments between `ARGV<N>` and the last argument.
`<N>` defaults to `0`, so that all arguments are taken.
## Example:
```cmake
function(foo_replacement)
z_vcpkg_function_arguments(ARGS)
foo(${ARGS})
...
endfunction()
```
## Source
[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)

36
externals/vcpkg/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md vendored Executable file
View File

@@ -0,0 +1,36 @@
# z_vcpkg_get_cmake_vars
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Runs a cmake configure with a dummy project to extract certain cmake variables
## Usage
```cmake
z_vcpkg_get_cmake_vars(<out-var>)
```
`z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `<out-var>` to
a path to a generated CMake file, with the detected `CMAKE_*` variables
re-exported as `VCPKG_DETECTED_*`.
## Notes
Avoid usage in portfiles.
All calls to `z_vcpkg_get_cmake_vars` will result in the same output file;
the output file is not generated multiple times.
## Examples
* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
### Basic Usage
```cmake
z_vcpkg_get_cmake_vars(cmake_vars_file)
include("${cmake_vars_file}")
message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}")
```
## Source
[scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake)

21
externals/vcpkg/docs/maintainers/internal/z_vcpkg_prettify_command_line.md vendored Executable file
View File

@@ -0,0 +1,21 @@
# z_vcpkg_prettify_command_line
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
Turn a command line into a formatted string.
```cmake
z_vcpkg_prettify_command_line(<out-var> <argument>...)
```
This command is for internal use, when printing out to a message.
## Examples
* `scripts/cmake/vcpkg_execute_build_process.cmake`
* `scripts/cmake/vcpkg_execute_required_process.cmake`
* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
## Source
[scripts/cmake/z\_vcpkg\_prettify\_command\_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)

11
externals/vcpkg/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.cmake.md vendored Executable file
View File

@@ -0,0 +1,11 @@
# z_vcpkg_setup_pkgconfig_path
Setup the generated pkgconfig file path to PKG_CONFIG_PATH environment variable or restore PKG_CONFIG_PATH environment variable.
```cmake
z_vcpkg_setup_pkgconfig_path(BASE_DIRS <"${CURRENT_INSTALLED_DIR}" ...>)
z_vcpkg_restore_pkgconfig_path()
```
`z_vcpkg_setup_pkgconfig_path` prepends `lib/pkgconfig` and `share/pkgconfig` directories for the given `BASE_DIRS` to the `PKG_CONFIG_PATH` environment variable. It creates or updates a backup of the previous value.
`z_vcpkg_restore_pkgconfig_path` shall be called when leaving the scope which called `z_vcpkg_setup_pkgconfig_path` in order to restore the original value from the backup.

16
externals/vcpkg/docs/maintainers/internal/z_vcpkg_setup_pkgconfig_path.md vendored Executable file
View File

@@ -0,0 +1,16 @@
# z_vcpkg_setup_pkgconfig_path
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
`z_vcpkg_setup_pkgconfig_path` sets up environment variables to use `pkgconfig`, such as `PKG_CONFIG` and `PKG_CONFIG_PATH`.
The original values are restored with `z_vcpkg_restore_pkgconfig_path`. `BASE_DIRS` indicates the base directories to find `.pc` files; typically `${CURRENT_INSTALLED_DIR}`, or `${CURRENT_INSTALLED_DIR}/debug`.
```cmake
z_vcpkg_setup_pkgconfig_path(BASE_DIRS <"${CURRENT_INSTALLED_DIR}" ...>)
# Build process that may transitively invoke pkgconfig
z_vcpkg_restore_pkgconfig_path()
```
## Source
[scripts/cmake/z\_vcpkg\_setup\_pkgconfig\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_setup_pkgconfig_path.cmake)

418
externals/vcpkg/docs/maintainers/maintainer-guide.md vendored Executable file
View File

@@ -0,0 +1,418 @@
# Maintainer Guidelines and Policies
This document lists a set of policies that you should apply when adding or updating a port recipe.
It is intended to serve the role of
[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/),
[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and
[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
## PR Structure
### Make separate Pull Requests per port
Whenever possible, separate changes into multiple PRs.
This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
### Avoid trivial changes in untouched files
For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand.
However, if you need to modify the file for the primary purpose of the PR (updating the library),
then obviously beneficial changes like fixing typos are appreciated!
### Check names against other repositories
A good service to check many at once is [Repology](https://repology.org/).
If the library you are adding could be confused with another one,
consider renaming to make it clear. We prefer when names are longer and/or
unlikely to conflict with any future use of the same name. If the port refers
to a library on GitHub, a good practice is to prefix the name with the organization
if there is any chance of confusion.
### Use GitHub Draft PRs
GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge.
Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
More information about GitHub Draft PRs:
https://github.blog/2019-02-14-introducing-draft-pull-requests/
## Portfiles
### Avoid deprecated helper functions
At this time, the following helpers are deprecated:
1. `vcpkg_extract_source_archive()` should be replaced by [`vcpkg_extract_source_archive_ex()`](vcpkg_extract_source_archive_ex.md)
2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
4. `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
5. `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](ports/vcpkg-cmake/vcpkg_cmake_configure.md#vcpkg_cmake_configure) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
6. `vcpkg_build_cmake` should be replaced by [`vcpkg_cmake_build()`](ports/vcpkg-cmake/vcpkg_cmake_build.md#vcpkg_cmake_build) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
7. `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](ports/vcpkg-cmake/vcpkg_cmake_install.md#vcpkg_cmake_install) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md#vcpkg-cmake))
8. `vcpkg_fixup_cmake_targets` should be replaced by [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md#vcpkg_cmake_config_fixup) (from port [`vcpkg-cmake-config`](ports/vcpkg-cmake-config.md#vcpkg-cmake-config))
Some of the replacement helper functions are in "tools ports" to allow consumers to pin their
behavior at specific versions, to allow locking the behavior of the helpers at a particular
version. Tools ports need to be added to your port's `"dependencies"`, like so:
```json
{
"name": "vcpkg-cmake",
"host": true
},
{
"name": "vcpkg-cmake-config",
"host": true
}
```
### Avoid excessive comments in portfiles
Ideally, portfiles should be short, simple, and as declarative as possible.
Remove any boiler plate comments introduced by the `create` command before submitting a PR.
### Ports must not be path dependent
Ports must not change their behavior based on which ports are already installed in a form that would change which contents that port installs. For example, given:
```
> vcpkg install a
> vcpkg install b
> vcpkg remove a
```
and
```
> vcpkg install b
```
the files installed by `b` must be the same, regardless of influence by the previous installation of `a`. This means that ports must not try to detect whether something is provided in the installed tree by another port before taking some action. A specific and common cause of such "path dependent" behavior is described below in "When defining features, explicitly control dependencies."
### Unique port attribution rule
In the entire vcpkg system, no two ports a user is expected to use concurrently may provide the same file. If a port tries to install a file already provided by another file, installation will fail. If a port wants to use an extremely common name for a header, for example, it should place those headers in a subdirectory rather than in `include`.
### Add CMake exports in an unofficial- namespace
A core design ideal of vcpkg is to not create "lock-in" for customers. In the build system, there should be no difference between depending on a library from the system, and depending on a library from vcpkg. To that end, we avoid adding CMake exports or targets to existing libraries with "the obvious name", to allow upstreams to add their own official CMake exports without conflicting with vcpkg.
To that end, any CMake configs that the port exports, which are not in the upstream library, should have `unofficial-` as a prefix. Any additional targets should be in the `unofficial::<port>::` namespace.
This means that the user should see:
* `find_package(unofficial-<port> CONFIG)` as the way to get at the unique-to-vcpkg package
* `unofficial::<port>::<target>` as an exported target from that port.
Examples:
* [`brotli`](https://github.com/microsoft/vcpkg/blob/4f0a640e4c5b74166b759a862d7527c930eff32e/ports/brotli/install.patch) creates the `unofficial-brotli` package, producing target `unofficial::brotli::brotli`.
## Features
### Do not use features to implement alternatives
Features must be treated as additive functionality. If port[featureA] installs and port[featureB] installs, then port[featureA,featureB] must install. Moreover, if a second port depends on [featureA] and a third port depends on [featureB], installing both the second and third ports should have their dependencies satisfied.
Libraries in this situation must choose one of the available options as expressed in vcpkg, and users who want a different setting must use overlay ports at this time.
Existing examples we would not accept today retained for backwards compatibility:
* `libgit2`, `libzip`, `open62541` all have features for selecting a TLS or crypto backend. Note that `curl` has different crypto backend options but allows selecting between them at runtime, meaning the above tenet is maintained.
* `darknet` has `opencv2`, `opencv3`, features to control which version of opencv to use for its dependencies.
### A feature may engage preview or beta functionality
Notwithstanding the above, if there is a preview branch or similar where the preview functionality has a high probability of not disrupting the non-preview functionality (for example, no API removals), a feature is acceptable to model this setting.
Examples:
* The Azure SDKs (of the form `azure-Xxx`) have a `public-preview` feature.
* `imgui` has an `experimental-docking` feature which engages their preview docking branch which uses a merge commit attached to each of their public numbered releases.
### Default features should enable behaviors, not APIs
If a consumer is depending directly upon a library, they can list out any desired features easily (`library[feature1,feature2]`). However, if a consumer _does not know_ they are using a library, they cannot list out those features. If that hidden library is like `libarchive` where features are adding additional compression algorithms (and thus behaviors) to an existing generic interface, default features offer a way to ensure a reasonably functional transitive library is built even if the final consumer doesn't name it directly.
If the feature adds additional APIs (or executables, or library binaries) and doesn't modify the behavior of existing APIs, it should be left off by default. This is because any consumer which might want to use those APIs can easily require it via their direct reference.
If in doubt, do not mark a feature as default.
### Do not use features to control alternatives in published interfaces
If a consumer of a port depends on only the core functionality of that port, with high probability they must not be broken by turning on the feature. This is even more important when the alternative is not directly controlled by the consumer, but by compiler settings like `/std:c++17` / `-std=c++17`.
Existing examples we would not accept today retained for backwards compatibility:
* `redis-plus-plus[cxx17]` controls a polyfill but does not bake the setting into the installed tree.
* `ace[wchar]` changes all APIs to accept `const wchar_t*` rather than `const char*`.
### A feature may replace polyfills with aliases provided that replacement is baked into the installed tree
Notwithstanding the above, ports may remove polyfills with a feature, as long as:
1. Turning on the feature changes the polyfills to aliases of the polyfilled entity
2. The state of the polyfill is baked into the installed headers, such that ABI mismatch "impossible" runtime errors are unlikely
3. It is possible for a consumer of the port to write code which works in both modes, for example by using a typedef which is either polyfilled or not
Example:
* `abseil[cxx17]` changes `absl::string_view` to a replacement or `std::string_view`; the patch
https://github.com/microsoft/vcpkg/blob/981e65ce0ac1f6c86e5a5ded7824db8780173c76/ports/abseil/fix-cxx-standard.patch implements the baking requirement
### Recommended solutions
If it's critical to expose the underlying alternatives, we recommend providing messages at build time to instruct the user on how to copy the port into a private overlay:
```cmake
set(USING_DOG 0)
message(STATUS "This version of LibContosoFrobnicate uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")
```
## Build Techniques
### Do not use vendored dependencies
Do not use embedded copies of libraries.
All dependencies should be split out and packaged separately so they can be updated and maintained.
### Prefer using CMake
When multiple buildsystems are available, prefer using CMake.
Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
Examples: [abseil](../../ports/abseil/portfile.cmake)
### Choose either static or shared binaries
By default, `vcpkg_cmake_configure()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`,
however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
```cmake
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
-DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
-DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)
```
### When defining features, explicitly control dependencies
When defining a feature that captures an optional dependency,
ensure that the dependency will not be used accidentally when the feature is not explicitly enabled.
```cmake
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
-DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
-DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)
```
The snippet below using `vcpkg_check_features()` is equivalent, [see the documentation](vcpkg_check_features.md).
```cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
FEATURES
"zlib" CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
INVERTED_FEATURES
"zlib" CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
OPTIONS
${FEATURE_OPTIONS}
)
```
Note that `ZLIB` in the above is case-sensitive. See the [CMAKE_DISABLE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) and [CMAKE_REQUIRE_FIND_PACKAGE_PackageName](https://cmake.org/cmake/help/v3.22/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.html) documnetation for more details.
### Place conflicting libs in a `manual-link` directory
A lib is considered conflicting if it does any of the following:
+ Define `main`
+ Define malloc
+ Define symbols that are also declared in other libraries
Conflicting libs are typically by design and not considered a defect. Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.
## Manifests and CONTROL files
When adding a new port, use the new manifest syntax for defining a port;
you may also change over to manifests when modifying an existing port.
You may do so easily by running the `vcpkg format-manifest` command, which will convert existing CONTROL
files into manifest files. Do not convert CONTROL files that have not been modified.
## Versioning
### Follow common conventions for the `"version"` field
See our [versioning documentation](../users/versioning.md#version-schemes) for a full explanation of our conventions.
### Update the `"port-version"` field in the manifest file of any modified ports
Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.
Our convention is to use the `"port-version"` field for changes to the port that don't change the upstream version, and to reset the `"port-version"` back to zero when an update to the upstream version is made.
For Example:
- Zlib's package version is currently `1.2.1`, with no explicit `"port-version"` (equivalent to a `"port-version"` of `0`).
- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.
- You should update the `"port-version"` field in the manifest file to `1`.
See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions.
### Update the version files in `versions/` of any modified ports
Vcpkg uses a set of metadata files to power its versioning feature.
These files are located in the following locations:
* `${VCPKG_ROOT}/versions/baseline.json`, (this file is common to all ports) and
* `${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json` (one per port).
For example, for `zlib` the relevant files are:
* `${VCPKG_ROOT}/versions/baseline.json`
* `${VCPKG_ROOT}/versions/z-/zlib.json`
We expect that each time you update a port, you also update its version files.
**The recommended method to update these files is to run the `x-add-version` command, e.g.:**
```
vcpkg x-add-version zlib
```
If you're updating multiple ports at the same time, instead you can run:
```
vcpkg x-add-version --all
```
To update the files for all modified ports at once.
_NOTE: These commands require you to have committed your changes to the ports before running them. The reason is that the Git SHA of the port directory is required in these version files. But don't worry, the `x-add-version` command will warn you if you have local changes that haven't been committed._
See our [versioning specification](../specifications/versioning.md) and [registries specification](../specifications/registries-2.md) to learn how vcpkg interacts with these files.
## Patching
### Prefer options over patching
It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.
Common options that allow avoiding patching:
1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overridden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
### Prefer patching over overriding `VCPKG_<VARIABLE>` values
Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.
However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).
Consider the following example:
```cmake
set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")
```
Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG_<LANG>_FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them.
Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.
### Minimize patches
When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
Don't add patches if the port is outdated and updating the port to a newer released version would solve the same issue. vcpkg prefers updating ports over patching outdated versions unless the version bump breaks a considerable amount of dependent ports.
This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions.
### Do not implement features in patches
The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc).
## Do not build tests/docs/examples by default
When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user.
Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.
## Enable existing users of the library to switch to vcpkg
### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`
Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`.
### Do not rename binaries outside the names given by upstream
This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name.
Important caveat:
- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available.
Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs.
Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.
## Code format
### Vcpkg internal code
We require the C++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification:
- Use Visual Studio:
1. Configure your [clang-format tools](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/).
2. Open the modified file.
3. Use shortcut keys Ctrl+K, Ctrl+D to format the current file.
- Use tools:
1. Install [llvm clang-format](https://releases.llvm.org/download.html#10.0.0)
2. Run command:
```cmd
> LLVM_PATH/bin/clang-format.exe -style=file -i changed_file.cpp
```
### Manifests
We require that the manifest file be formatted. Use the following command to format all manifest files:
```cmd
> vcpkg format-manifest --all
```
## Useful implementation notes
### Portfiles are run in Script Mode
While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs, portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Build Mode" (unofficial term). The most important difference between these two modes is that "Script Mode" does not have a concept of "Target" -- any behaviors that depend on the "target" machine (`CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`, etc) will not be correct.
Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
```no-highlight
+----------------------------+ +------------------------------------+
| CMake.exe | | CMake.exe |
+----------------------------+ +------------------------------------+
| Triplet file | ====> | Toolchain file |
| (x64-windows.cmake) | | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+ +------------------------------------+
| Portfile | ====> | CMakeLists.txt |
| (ports/foo/portfile.cmake) | | (buildtrees/../CMakeLists.txt) |
+----------------------------+ +------------------------------------+
```
To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).
To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).
See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.

551
externals/vcpkg/docs/maintainers/manifest-files.md vendored Executable file
View File

@@ -0,0 +1,551 @@
# Manifest files - `vcpkg.json`
The `vcpkg.json` file contains metadata about the port.
It's a JSON file, and replaces the existing CONTROL file metadata structure.
It must have a top level object, and all fields are case sensitive.
## Examples:
The most important fields in a manifest, the ones which are required for all ports,
are the `"name"` field, and a version field (for now, just `"version-string"`).
There's more information about these fields below.
```json
{
"name": "ace",
"version-string": "6.5.5"
}
```
```json
{
"name": "vtk",
"version-string": "8.2.0",
"port-version": 2,
"description": "Software system for 3D computer graphics, image processing, and visualization",
"dependencies": [
{
"name": "atlmfc",
"platform": "windows"
},
"double-conversion",
"eigen3",
"expat",
"freetype",
"glew",
"hdf5",
"jsoncpp",
"libharu",
"libjpeg-turbo",
"libpng",
"libtheora",
"libxml2",
"lz4",
"netcdf-c",
"proj4",
"pugixml",
"sqlite3",
"tiff",
"zlib"
]
}
```
## Fields
### `"name"`
The name of the port.
When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg. For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique. Verify there are no conflicts on a search engine as well as on other package collections.
Package collections to check for conflicts:
+ [Repology](https://repology.org/projects/)
+ [Debian packages](https://www.debian.org/distrib/packages)
+ [Packages search](https://pkgs.org/)
A name must be an identifier: i.e., it must only consist of lowercase ascii alphabetic characters,
numbers, and hyphens, and it must not begin nor end with a hyphen.
### Version fields
Currently there are different fields for special versioning. Namely:
Manifest property | Versioning scheme
------------------|------------------------------------
`version` | For dot-separated numeric versions
`version-semver` | For SemVer compliant versions
`version-date` | For dates in the format YYYY-MM-DD
`version-string` | For arbitrary strings
See https://github.com/microsoft/vcpkg/blob/master/docs/specifications/versioning.md#22-package-versions for more details.
Additionally, `"port-version"` is used to differentiate between port changes that don't change the underlying library version.
#### `"version-string"`
This field is an ascii string, and may contain alphanumeric characters, `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as byte strings and are only evaluated for equality.
For tagged-release ports, we follow the following convention:
1. If the library follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
2. If the library includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
3. If the library is versioned by dates, format the resulting version string just like the upstream library;
for example, Abseil formats their dates `lts_2020_02_25`, so the `"version-string"` should be `"lts_2020_02_25"`.
For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
For example, given:
1. The latest commit was made on 2019-04-19
2. The current version string is `2019-02-14`
3. Today's date is 2019-06-01.
Then if you update the source version today, you should give it version `2019-06-01`.
#### `"port-version"`
The version of the port, aside from the library version.
This field is a non-negative integer.
It allows one to version the port file separately from the version of the underlying library;
if you make a change to a port, without changing the underlying version of the library,
you should increment this field by one (starting at `0`, which is equivalent to no `"port-version"` field).
When the version of the underlying library is upgraded,
this field should be set back to `0` (i.e., delete the `"port-version"` field).
#### Examples:
```json
{
"version": "1.0.5",
"port-version": 2
}
```
```json
{
"version": "2019-03-21"
}
```
### `"description"`
A description of the library.
This field can either be a single string, which should be a summary of the library,
or can be an array, with the first line being a summary and the remaining lines being the detailed description -
one string per line.
#### Examples:
```json
{
"description": "C++ header-only JSON library"
}
```
```json
{
"description": [
"Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.",
"MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model."
"This makes it suitable for 'machine to machine' messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino."
]
}
```
### `"homepage"`
The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
### `"documentation"`
The URL where a user would be able to find official documentation for the library. Optional.
### `"maintainers"`
A list of strings that define the set of maintainers of a package.
It's recommended that these take the form of `Givenname Surname <email>`,
but this field is not checked for consistency.
Optional.
#### Example:
```json
{
"homepage": "https://github.com/microsoft/vcpkg"
}
```
### `"dependencies"`
An array of ports the library has a dependency on.
vcpkg does not distinguish between build-only dependencies and runtime dependencies.
The complete list of dependencies needed to successfully use the library should be specified.
For example: websocketpp is a header only library, and thus does not require any dependencies at install time.
However, downstream users need boost and openssl to make use of the library.
Therefore, websocketpp lists boost and openssl as dependencies.
Each dependency may be either an identifier, or an object.
For many dependencies, just listing the name of the library should be fine;
however, if one needs to add extra information to that dependency, one may use the dependency object.
For a dependency object, the `"name"` field is used to designate the library;
for example the dependency object `{ "name": "zlib" }` is equivalent to just writing `"zlib"`.
If the port is dependent on optional features of another library,
those can be specified using the `"features"` field of the dependency object.
If the port does not require any features from the dependency,
this should be specified with the `"default-features"` fields set to `false`.
Dependencies can also be filtered based on the target triplet to support differing requirements.
These filters use the same syntax as the `"supports"` field below,
and are specified in the `"platform"` field.
#### Example:
```json
{
"dependencies": [
{
"name": "curl",
"default-features": false,
"features": [
"winssl"
],
"platform": "windows"
},
{
"name": "curl",
"default-features": false,
"features": [
"openssl"
],
"platform": "!windows"
},
"rapidjson"
]
}
```
### `"features"`
Multiple optional features can be specified in manifest files, in the `"features"` object field.
This field is a map from the feature name, to the feature's information.
Each one must have a `"description"` field, and may also optionally have a `"dependencies"` field.
A feature's name must be an identifier -
in other words, lowercase alphabetic characters, digits, and hyphens,
neither starting nor ending with a hyphen.
A feature's `"description"` is a description of the feature,
and is the same kind of thing as the port `"description"` field.
A feature's `"dependencies"` field contains the list of extra dependencies required to build and use this feature;
this field isn't required if the feature doesn't require any extra dependencies.
On installation the dependencies from all selected features are combined to produce the full dependency list for the build.
#### Example:
```json
{
"name": "vtk",
"version-string": "8.2.0",
"port-version": 2,
"description": "Software system for 3D computer graphics, image processing, and visualization",
"dependencies": [
{
"name": "atlmfc",
"platform": "windows"
},
"double-conversion",
"eigen3",
"expat",
"freetype",
"glew",
"hdf5",
"jsoncpp",
"libharu",
"libjpeg-turbo",
"libpng",
"libtheora",
"libxml2",
"lz4",
"netcdf-c",
"proj4",
"pugixml",
"sqlite3",
"tiff",
"zlib"
],
"features": {
"mpi": {
"description": "MPI functionality for VTK",
"dependencies": [
{
"name": "hdf5",
"features": [
"parallel"
]
},
"mpi"
]
},
"openvr": {
"description": "OpenVR functionality for VTK",
"dependencies": [
"openvr",
"sdl2"
]
},
"python": {
"description": "Python functionality for VTK",
"dependencies": [
"python3"
]
},
"qt": {
"description": "Qt functionality for VTK",
"dependencies": [
"qt5"
]
}
}
}
```
### `"default-features"`
An array of feature names that the library uses by default, if nothing else is specified.
#### Example:
```json
{
"default-features": [
"kinesis"
],
"features": {
"dynamodb": {
"description": "Build dynamodb support",
"dependencies": [
"dynamodb"
]
},
"kinesis": {
"description": "build kinesis support"
}
}
}
```
### `"supports"`
A string, formatted as a platform expression,
that evaluates to true when the port should build successfully for a triplet.
This field is used in the CI testing to skip ports,
and warns users in advance that a given install tree is not expected to succeed.
Therefore, this field should be used optimistically;
in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
The grammar for this top-level platform expression, in [EBNF], is as follows:
```ebnf
whitespace-character =
| ? U+0009 "CHARACTER TABULATION" ?
| ? U+000A "LINE FEED" ?
| ? U+000D "CARRIAGE RETURN" ?
| ? U+0020 "SPACE" ? ;
optional-whitespace = { whitespace-character } ;
required-whitespace = whitespace-character, { optional-whitespace } ;
lowercase-alpha =
| "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m"
| "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
digit =
| "0" | "1" | "2" | "3" | "4"
| "5" | "6" | "7" | "8" | "9" ;
identifier-character =
| lowercase-alpha
| digit ;
platform-expression-list =
| platform-expression { ",", optional-whitespace, platform-expression } ;
platform-expression =
| platform-expression-not
| platform-expression-and
| platform-expression-or ;
platform-expression-identifier =
| identifier-character, { identifier-character }, optional-whitespace ;
platform-expression-grouped =
| "(", optional-whitespace, platform-expression, ")", optional-whitespace ;
platform-expression-simple =
| platform-expression-identifier
| platform-expression-grouped ;
platform-expression-unary-keyword-operand =
| required-whitespace, platform-expression-simple
| optional-whitespace, platform-expression-grouped ;
platform-expression-not =
| platform-expression-simple
| "!", optional-whitespace, platform-expression-simple
| "not", platform-expression-unary-keyword-operand ;
platform-expression-binary-keyword-first-operand =
| platform-expression-not, required-whitespace
| platform-expression-grouped ;
platform-expression-binary-keyword-second-operand =
| required-whitespace, platform-expression-not
| platform-expression-grouped ;
platform-expression-and =
| platform-expression-not, { "&", optional-whitespace, platform-expression-not }
| platform-expression-binary-keyword-first-operand, { "and", platform-expression-binary-keyword-second-operand } ;
platform-expression-or =
| platform-expression-not, { "|", optional-whitespace, platform-expression-not }
| platform-expression-binary-keyword-first-operand, { "or", platform-expression-binary-keyword-second-operand } (* to allow for future extension *) ;
top-level-platform-expression = optional-whitespace, platform-expression-list ;
```
Basically, there are four kinds of expressions -- identifiers, negations, ands, and ors.
Negations may only negate an identifier or a grouped expression.
Ands and ors are a list of `&` or `|` separated identifiers, negated expressions, and grouped expressions.
One may not mix `&` and `|` without parentheses for grouping.
These predefined identifier expressions are computed from standard triplet settings:
- `native` - `TARGET_TRIPLET` == `HOST_TRIPLET`;
useful for ports which depend on their own built binaries in their build.
- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `mingw` - `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
- `staticcrt` - `VCPKG_CRT_LINKAGE` == `"static"`
These predefined identifier expressions can be overridden in the triplet file,
via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option,
and new identifier expressions can be added via the same mechanism.
This field is optional and defaults to true.
> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
#### Example:
```json
{
"supports": "!uwp & !(arm & !arm64)"
}
```
This means "doesn't support uwp, nor arm32 (but does support arm64)".
### `"license"`
The license of the port. This is an [SPDX license expression],
or `null` for proprietary licenses and other licenses for which
one should "just read the `copyright` file" (e.g., Qt).
[SPDX license expression]: https://spdx.dev/ids/#how
Additionally, you can find the list of [recognized license IDs]
and [recognized license exception IDs] in Annex A of the SPDX specification.
[recognized license IDs]: https://spdx.github.io/spdx-spec/SPDX-license-list/#a1-licenses-with-short-identifiers
[recognized license exception IDs]: https://spdx.github.io/spdx-spec/SPDX-license-list/#a2-exceptions-list
The following is an EBNF conversion of the ABNF located at
<https://spdx.github.io/spdx-spec/SPDX-license-expressions/>,
and this is what we actually parse in vcpkg.
Note that vcpkg does not support DocumentRefs.
```ebnf
idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;
(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;
with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;
simple-expression = [ whitespace ], (
| license-id
| license-id, "+"
| license-ref
), [ whitespace ] ;
(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
| simple-expression
| [ whitespace ], "(", or-expression, ")", [ whitespace ] ;
with-expression =
| parenthesized-expression
| simple-expression, with, license-exception-id, [ whitespace ] ;
(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;
license-expression = or-expression ;
```
#### Examples
For libraries with simple licensing,
only one license identifier may be needed;
vcpkg, for example, would use this since it uses the MIT license:
```json
{
"license": "MIT"
}
```
Many GPL'd projects allow either the GPL 2 or any later versions:
```json
{
"license": "GPL-2.0-or-later"
}
```
Many Rust projects, in order to make certain they're useable with GPL,
but also desiring the MIT license, will allow licensing under either
the MIT license or Apache 2.0:
```json
{
"license": "Apache-2.0 OR MIT"
}
```
Some major projects include exceptions;
the Microsoft C++ standard library, and the LLVM project,
are licensed under Apache 2.0 with the LLVM exception:
```json
{
"license": "Apache-2.0 WITH LLVM-exception"
}
```

100
externals/vcpkg/docs/maintainers/portfile-functions.md vendored Executable file
View File

@@ -0,0 +1,100 @@
<!-- Run regenerate.ps1 to extract scripts documentation -->
# Portfile helper functions
- [execute\_process](execute_process.md)
- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
- [vcpkg\_backup\_restore\_env\_vars](vcpkg_backup_restore_env_vars.md)
- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md))
- [vcpkg\_build\_make](vcpkg_build_make.md)
- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
- [vcpkg\_build\_ninja](vcpkg_build_ninja.md)
- [vcpkg\_build\_nmake](vcpkg_build_nmake.md)
- [vcpkg\_build\_qmake](vcpkg_build_qmake.md)
- [vcpkg\_buildpath\_length\_warning](vcpkg_buildpath_length_warning.md)
- [vcpkg\_check\_features](vcpkg_check_features.md)
- [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
- [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md)
- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) (deprecated, use [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md))
- [vcpkg\_configure\_gn](vcpkg_configure_gn.md) (deprecated, use [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md))
- [vcpkg\_configure\_make](vcpkg_configure_make.md)
- [vcpkg\_configure\_meson](vcpkg_configure_meson.md)
- [vcpkg\_configure\_qmake](vcpkg_configure_qmake.md)
- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
- [vcpkg\_copy\_tools](vcpkg_copy_tools.md)
- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)
- [vcpkg\_execute\_in\_download\_mode](vcpkg_execute_in_download_mode.md)
- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
- [vcpkg\_execute\_required\_process\_repeat](vcpkg_execute_required_process_repeat.md)
- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
- [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md) (deprecated)
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
- [vcpkg\_find\_fortran](vcpkg_find_fortran.md)
- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md) (deprecated, use [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md))
- [vcpkg\_fixup\_pkgconfig](vcpkg_fixup_pkgconfig.md)
- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
- [vcpkg\_from\_git](vcpkg_from_git.md)
- [vcpkg\_from\_github](vcpkg_from_github.md)
- [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)
- [vcpkg\_from\_sourceforge](vcpkg_from_sourceforge.md)
- [vcpkg\_get\_program\_files\_platform\_bitness](vcpkg_get_program_files_platform_bitness.md)
- [vcpkg\_get\_windows\_sdk](vcpkg_get_windows_sdk.md)
- [vcpkg\_host\_path\_list](vcpkg_host_path_list.md)
- [vcpkg\_install\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md))
- [vcpkg\_install\_gn](vcpkg_install_gn.md) (deprecated, use [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md))
- [vcpkg\_install\_make](vcpkg_install_make.md)
- [vcpkg\_install\_meson](vcpkg_install_meson.md)
- [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)
- [vcpkg\_install\_nmake](vcpkg_install_nmake.md)
- [vcpkg\_install\_qmake](vcpkg_install_qmake.md)
- [vcpkg\_list](vcpkg_list.md)
- [vcpkg\_minimum\_required](vcpkg_minimum_required.md)
- [vcpkg\_replace\_string](vcpkg_replace_string.md)
## Internal Functions
- [z\_vcpkg\_apply\_patches](internal/z_vcpkg_apply_patches.md)
- [z\_vcpkg\_forward\_output\_variable](internal/z_vcpkg_forward_output_variable.md)
- [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md)
- [z\_vcpkg\_get\_cmake\_vars](internal/z_vcpkg_get_cmake_vars.md)
- [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
- [z\_vcpkg\_setup\_pkgconfig\_path](internal/z_vcpkg_setup_pkgconfig_path.md)
## Scripts from Ports
### [vcpkg-cmake](ports/vcpkg-cmake.md)
- [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md)
- [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md)
- [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
### [vcpkg-gn](ports/vcpkg-gn.md)
- [vcpkg\_gn\_configure](ports/vcpkg-gn/vcpkg_gn_configure.md)
- [vcpkg\_gn\_install](ports/vcpkg-gn/vcpkg_gn_install.md)
### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
- [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)
### [vcpkg-cmake-get-vars](ports/vcpkg-cmake-get-vars.md)
- [vcpkg\_cmake\_get\_vars](ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md)
### [vcpkg-pkgconfig-get-modules](ports/vcpkg-pkgconfig-get-modules.md)
- [x\_vcpkg\_pkgconfig\_get\_modules](ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md)
### [vcpkg-get-python-packages](ports/vcpkg-get-python-packages.md)
- [x\_vcpkg\_get\_python\_packages](ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md)
### [vcpkg-qmake](ports/vcpkg-qmake.md)
- [vcpkg\_qmake\_configure](ports/vcpkg-qmake/vcpkg_qmake_configure.md)

10
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-config.md vendored Executable file
View File

@@ -0,0 +1,10 @@
# vcpkg-cmake-config
`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`,
a function which both:
- Fixes common mistakes in port build systems, like using absolute paths
- Merges the debug and release config files.
This function should almost always be used when a port has `*config.cmake` files,
even when the buildsystem of the project is not CMake.

54
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md vendored Executable file
View File

@@ -0,0 +1,54 @@
# vcpkg_cmake_config_fixup
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md).
Merge release and debug CMake targets and configs to support multiconfig generators.
Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
```cmake
vcpkg_cmake_config_fixup(
[PACKAGE_NAME <name>]
[CONFIG_PATH <config-directory>]
[TOOLS_PATH <tools/${PORT}>]
[DO_NOT_DELETE_PARENT_CONFIG_PATH]
[NO_PREFIX_CORRECTION]
)
```
For many ports, `vcpkg_cmake_config_fixup()` on its own should work,
as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`.
For ports where the package name passed to `find_package` is distinct from the port name,
`PACKAGE_NAME` should be changed to be that name instead.
For ports where the directory of the `*config.cmake` files cannot be set,
use the `CONFIG_PATH` to change the directory where the files come from.
By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior,
as it is convenient for ports that install
more than one CMake package configuration file.
The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX`
done by vcpkg due to moving the config files.
Currently the correction does not take into account how the files are moved,
and applies a rather simply correction which in some cases will yield the wrong results.
## How it Works
1. Moves `/debug/<CONFIG_PATH>/*targets-debug.cmake` to `/share/${PACKAGE_NAME}`.
2. Transforms all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows.
3. Transforms all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms.
4. Fixes `${_IMPORT_PREFIX}` in auto generated targets.
5. Replaces `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs.
6. Merges INTERFACE_LINK_LIBRARIES of release and debug configurations.
7. Replaces `${CURRENT_INSTALLED_DIR}` with `${VCPKG_IMPORT_PREFIX}` in targets.
8. Removes `/debug/<CONFIG_PATH>/*config.cmake`.
## Examples
* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
## Source
[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake)

3
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-get-vars.md vendored Executable file
View File

@@ -0,0 +1,3 @@
# vcpkg-cmake-get-vars
This port contains a helper function to extract CMake variables into the scope of the portfile or other scripts

41
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md vendored Executable file
View File

@@ -0,0 +1,41 @@
# vcpkg_cmake_get_vars
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md).
Runs a cmake configure with a dummy project to extract certain cmake variables
## Usage
```cmake
vcpkg_cmake_get_vars(<out-var>)
```
`vcpkg_cmake_get_vars(<out-var>)` sets `<out-var>` to
a path to a generated CMake file, with the detected `CMAKE_*` variables
re-exported as `VCPKG_DETECTED_CMAKE_*`.
Additionally sets, for `RELEASE` and `DEBUG`:
- VCPKG_COMBINED_CXX_FLAGS_<config>
- VCPKG_COMBINED_C_FLAGS_<config>
- VCPKG_COMBINED_SHARED_LINKER_FLAGS_<config>
- VCPKG_COMBINED_STATIC_LINKER_FLAGS_<config>
- VCPKG_COMBINED_EXE_LINKER_FLAGS_<config>
Most users should use these pre-combined flags instead of attempting
to read the `VCPKG_DETECTED_*` flags directly.
## Notes
Avoid usage in portfiles.
All calls to `vcpkg_cmake_get_vars` will result in the same output file;
the output file is not generated multiple times.
### Basic Usage
```cmake
vcpkg_cmake_get_vars(cmake_vars_file)
include("${cmake_vars_file}")
message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CMAKE_CXX_FLAGS}")
```
## Source
[ports/vcpkg-cmake-get-vars/vcpkg\_cmake\_get\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.cmake)

7
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake.md vendored Executable file
View File

@@ -0,0 +1,7 @@
# vcpkg-cmake
This port contains cmake functions for dealing with a CMake buildsystem.
In the common case, `vcpkg_cmake_configure()` (with appropriate arguments)
followed by `vcpkg_cmake_install()` will be enough to build and install a port.
`vcpkg_cmake_build()` is provided for more complex cases.

38
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md vendored Executable file
View File

@@ -0,0 +1,38 @@
# vcpkg_cmake_build
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md).
Build a cmake project.
```cmake
vcpkg_cmake_build(
[TARGET <target>]
[LOGFILE_BASE <base>]
[DISABLE_PARALLEL]
[ADD_BIN_TO_PATH]
)
```
`vcpkg_cmake_build` builds an already-configured cmake project.
You can use the alias [`vcpkg_cmake_install()`] function
if your CMake build system supports the `install` TARGET,
and this is something we recommend doing whenever possible.
Otherwise, you can use `TARGET` to set the target to build.
This function defaults to not passing a target to cmake.
[`vcpkg_cmake_install()`]: vcpkg_cmake_install.md
`LOGFILE_BASE` is used to set the base of the logfile names;
by default, this is `build`, and thus the logfiles end up being something like
`build-x86-windows-dbg.log`; if you use `vcpkg_cmake_install`,
this is set to `install`, so you'll get log names like `install-x86-windows-dbg.log`.
For build systems that are buggy when run in parallel,
using `DISABLE_PARALLEL` will run the build with only one job.
Finally, `ADD_BIN_TO_PATH` adds the appropriate (either release or debug)
`bin/` directories to the path during the build,
such that executables run during the build will be able to access those DLLs.
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake)

93
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md vendored Executable file
View File

@@ -0,0 +1,93 @@
# vcpkg_cmake_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md).
Configure a CMake buildsystem.
```cmake
vcpkg_cmake_configure(
SOURCE_PATH <source-path>
[LOGFILE_BASE <logname-base>]
[DISABLE_PARALLEL_CONFIGURE]
[NO_CHARSET_FLAG]
[WINDOWS_USE_MSBUILD]
[GENERATOR <generator>]
[OPTIONS
<configure-setting>...]
[OPTIONS_RELEASE
<configure-setting>...]
[OPTIONS_DEBUG
<configure-setting>...]
[MAYBE_UNUSED_VARIABLES
<option-name>...]
)
```
`vcpkg_cmake_configure` configures a CMake build system for use with
`vcpkg_cmake_buildsystem_build` and `vcpkg_cmake_buildsystem_install`.
`source-path` is where the source is located; by convention,
this is usually `${SOURCE_PATH}`, which is set by one of the `vcpkg_from_*` functions.
This function configures the build system for both Debug and Release builds by default,
assuming that `VCPKG_BUILD_TYPE` is not set; if it is, then it will only configure for
that build type.
Use the `OPTIONS` argument to set the configure settings for both release and debug,
and use `OPTIONS_RELEASE` and `OPTIONS_DEBUG` to set the configure settings for
release only and debug only respectively.
By default, when possible, `vcpkg_cmake_configure` uses [ninja-build]
as its build system. If the `WINDOWS_USE_MSBUILD` argument is passed, then
`vcpkg_cmake_configure` will use a Visual Studio generator on Windows;
on every other platform, `vcpkg_cmake_configure` just uses Ninja.
[ninja-build]: https://ninja-build.org/
Additionally, one may pass the specific generator a port should use with `GENERATOR`.
This is useful if some project-specific buildsystem
has been wrapped in a CMake build system that doesn't perform an actual build.
If used for this purpose, it should be set to `"NMake Makefiles"`.
`vcpkg_cmake_buildsystem_build` and `install` do not support this being set to anything
except for NMake.
For libraries which cannot be configured in parallel,
pass the `DISABLE_PARALLEL_CONFIGURE` flag. This is needed, for example,
if the library's build system writes back into the source directory during configure.
This also disables the `CMAKE_DISABLE_SOURCE_CHANGES` option.
By default, this function adds flags to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`
which set the default character set to utf-8 for MSVC.
If the library sets its own code page, pass the `NO_CHARSET_FLAG` option.
This function makes certain that all options passed in are used by the
underlying CMake build system. If there are options that might be unused,
perhaps on certain platforms, pass those variable names to
`MAYBE_UNUSED_VARIABLES`. For example:
```cmake
vcpkg_cmake_configure(
...
OPTIONS
-DBUILD_EXAMPLE=OFF
...
MAYBE_UNUSED_VARIABLES
BUILD_EXAMPLE
)
```
`LOGFILE_BASE` is used to set the base of the logfile names;
by default, this is `config`, and thus the logfiles end up being something like
`config-x86-windows-dbg.log`. You can set it to anything you like;
if you set it to `config-the-first`,
you'll get something like `config-the-first-x86-windows.dbg.log`.
## Notes
This command supplies many common arguments to CMake. To see the full list, examine the source.
## Examples
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv4](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv4/portfile.cmake)
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)

25
externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md vendored Executable file
View File

@@ -0,0 +1,25 @@
# vcpkg_cmake_install
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md).
Build and install a cmake project.
```cmake
vcpkg_cmake_install(
[DISABLE_PARALLEL]
[ADD_BIN_TO_PATH]
)
```
`vcpkg_cmake_install` transparently forwards to [`vcpkg_cmake_build()`],
with additional parameters to set the `TARGET` to `install`,
and to set the `LOGFILE_ROOT` to `install` as well.
[`vcpkg_cmake_build()`]: vcpkg_cmake_build.md
## Examples:
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake)

6
externals/vcpkg/docs/maintainers/ports/vcpkg-get-python-packages.md vendored Executable file
View File

@@ -0,0 +1,6 @@
# vcpkg-get-python-packages
**Experimental: will change or be removed at any time**
`vcpkg-get-python-packages` provides `x_vcpkg_get_python_packages()`, a function which simplifies getting
python packages.

38
externals/vcpkg/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md vendored Executable file
View File

@@ -0,0 +1,38 @@
# x_vcpkg_get_python_packages
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md).
Experimental
Retrieve needed python packages
## Usage
```cmake
x_vcpkg_get_python_packages(
[PYTHON_VERSION (2|3)]
PYTHON_EXECUTABLE <path to python binary>
REQUIREMENTS_FILE <file-path>
PACKAGES <packages to aqcuire>...
[OUT_PYTHON_VAR somevar]
)
```
## Parameters
### PYTHON_VERSION
Python version to be used. Either 2 or 3
### PYTHON_EXECUTABLE
Full path to the python executable
### REQUIREMENTS_FILE
Requirement file with the list of python packages
### PACKAGES
List of python packages to acquire
### OUT_PYTHON_VAR
Variable to store the path to the python binary inside the virtual environment
## Source
[ports/vcpkg-get-python-packages/x\_vcpkg\_get\_python\_packages.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.cmake)

12
externals/vcpkg/docs/maintainers/ports/vcpkg-gn.md vendored Executable file
View File

@@ -0,0 +1,12 @@
# vcpkg-gn
This port contains cmake functions for dealing with a GN buildsystem.
## Example
```cmake
vcpkg_gn_configure(
SOURCE_PATH "${SOURCE_PATH}"
)
vcpkg_gn_install()
```

32
externals/vcpkg/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md vendored Executable file
View File

@@ -0,0 +1,32 @@
# vcpkg_gn_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md).
Generate Ninja (GN) targets
## Usage:
```cmake
vcpkg_gn_configure(
SOURCE_PATH <SOURCE_PATH>
[OPTIONS <OPTIONS>]
[OPTIONS_DEBUG <OPTIONS_DEBUG>]
[OPTIONS_RELEASE <OPTIONS_RELEASE>]
)
```
## Parameters:
### SOURCE_PATH (required)
The path to the GN project.
### OPTIONS
Options to be passed to both the debug and release targets.
Note: Must be provided as a space-separated string.
### OPTIONS_DEBUG (space-separated string)
Options to be passed to the debug target.
### OPTIONS_RELEASE (space-separated string)
Options to be passed to the release target.
## Source
[ports/vcpkg-gn/vcpkg\_gn\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_configure.cmake)

29
externals/vcpkg/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md vendored Executable file
View File

@@ -0,0 +1,29 @@
# vcpkg_gn_install
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md).
Installs a GN project.
In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
## Usage:
```cmake
vcpkg_gn_install(
SOURCE_PATH <SOURCE_PATH>
[TARGETS <target>...]
)
```
## Parameters:
### SOURCE_PATH
The path to the source directory
### TARGETS
Only install the specified targets.
Note: includes must be handled separately
[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
## Source
[ports/vcpkg-gn/vcpkg\_gn\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-gn/vcpkg_gn_install.cmake)

6
externals/vcpkg/docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md vendored Executable file
View File

@@ -0,0 +1,6 @@
# vcpkg-pkgconfig-get-modules
**Experimental: will change or be removed at any time**
`vcpkg-pkgconfig-get-modules` provides `x_vcpkg_pkgconfig_get_modules()`, a function which simplifies calling
`pkg-config` in portfiles in order to gather dependencies for exotic buildsystems.

45
externals/vcpkg/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md vendored Executable file
View File

@@ -0,0 +1,45 @@
# x_vcpkg_pkgconfig_get_modules
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md).
Experimental
Retrieve required module information from pkgconfig modules
## Usage
```cmake
x_vcpkg_pkgconfig_get_modules(
PREFIX <prefix>
MODULES <pkgconfig_modules>...
[CFLAGS]
[LIBS]
[LIBRARIES]
[LIBRARIES_DIRS]
[INCLUDE_DIRS]
)
```
## Parameters
### PREFIX
Used variable prefix to use
### MODULES
List of pkgconfig modules to retrieve information for.
### LIBS
Returns `"${PKGCONFIG}" --libs` in <prefix>_LIBS_(DEBUG|RELEASE)
### LIBRARIES
Returns `"${PKGCONFIG}" --libs-only-l` in <prefix>_LIBRARIES_(DEBUG|RELEASE)
### LIBRARIES_DIRS
Returns `"${PKGCONFIG}" --libs-only-L` in <prefix>_LIBRARIES_DIRS_(DEBUG|RELEASE)
### INCLUDE_DIRS
Returns `"${PKGCONFIG}" --cflags-only-I` in <prefix>_INCLUDE_DIRS_(DEBUG|RELEASE)
## Examples
* [qt5-base](https://github.com/microsoft/vcpkg/blob/master/ports/qt5-base/portfile.cmake)
## Source
[ports/vcpkg-pkgconfig-get-modules/x\_vcpkg\_pkgconfig\_get\_modules.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.cmake)

7
externals/vcpkg/docs/maintainers/ports/vcpkg-qmake.md vendored Executable file
View File

@@ -0,0 +1,7 @@
# vcpkg-qmake
This port contains qmake functions for dealing with a QMake buildsystem.
In the common case, `vcpkg_qmake_configure()` (with appropriate arguments)
followed by `vcpkg_install_qmake()` will be enough to build and install a port.

36
externals/vcpkg/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md vendored Executable file
View File

@@ -0,0 +1,36 @@
# vcpkg_qmake_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md).
Configure a qmake-based project.
###User setable triplet variables:
VCPKG_OSX_DEPLOYMENT_TARGET: Determines QMAKE_MACOSX_DEPLOYMENT_TARGET
VCPKG_QMAKE_COMMAND: Path to qmake. (default: "${CURRENT_HOST_INSTALLED_DIR}/tools/Qt6/bin/qmake${VCPKG_HOST_EXECUTABLE_SUFFIX}")
VCPKG_QT_CONF_(RELEASE|DEBUG): Path to qt.config being used for RELEASE/DEBUG. (default: "${CURRENT_INSTALLED_DIR}/tools/Qt6/qt_(release|debug).conf")
VCPKG_QMAKE_OPTIONS(_RELEASE|_DEBUG)?: Extra options to pass to QMake
```cmake
vcpkg_qmake_configure(
SOURCE_PATH <pro_file_path>
[QMAKE_OPTIONS arg1 [arg2 ...]]
[QMAKE_OPTIONS_RELEASE arg1 [arg2 ...]]
[QMAKE_OPTIONS_DEBUG arg1 [arg2 ...]]
[OPTIONS arg1 [arg2 ...]]
[OPTIONS_RELEASE arg1 [arg2 ...]]
[OPTIONS_DEBUG arg1 [arg2 ...]]
)
```
### SOURCE_PATH
The path to the *.pro qmake project file.
### QMAKE_OPTIONS, QMAKE_OPTIONS\_RELEASE, QMAKE_OPTIONS\_DEBUG
options directly passed to qmake with the form QMAKE_X=something or CONFIG=something
### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
The options passed after -- to qmake.
## Source
[ports/vcpkg-qmake/vcpkg\_qmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-qmake/vcpkg_qmake_configure.cmake)

115
externals/vcpkg/docs/maintainers/pr-review-checklist.md vendored Executable file
View File

@@ -0,0 +1,115 @@
Vcpkg PR Checklist
=====================
Revision: 1
## Overview
This document provides an annotated checklist which vcpkg team members use to apply the "reviewed" label on incoming pull requests. If a pull request violates any of these points, we may ask contributors to make necessary changes before we can merge the changeset.
Feel free to create an issue or pull request if you feel that this checklist can be improved. Please increment the revision number when modifying the checklist content.
## Checklist
You can link any of these checklist items in a GitHub comment by copying the link address attached to each item code.
<details id="c000001">
<summary><a href="#c000001">c000001</a>: No deprecated helper functions are used</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-deprecated-helper-functions) for more information.
</details>
<details id="c000002">
<summary><a href="#c000002">c000002</a>: `"port-version"` field is updated</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#versioning) for more information.
</details>
<details id="c000003">
<summary><a href="#c000003">c000003</a>: New ports contain a `"description"` field written in English</summary>
A description only one or a few sentences long is helpful. Consider using the library's official description from their `README.md` or similar if possible. Automatic translations are acceptable and we are happy to clean up translations to English for our contributors.
See our [manifest file documentation](manifest-files.md#description) for more information.
</details>
<details id="c000004">
<summary><a href="#c000004">c000004</a>: No unnecessary comments are present in the changeset</summary>
See our [Maintainer Guidelines and Policies](maintainer-guide.md#avoid-excessive-comments-in-portfiles) for more information.
</details>
<details id="c000005">
<summary><a href="#c000005">c000005</a>: Downloaded archives are versioned if available</summary
To ensure archive content does not change, archives downloaded preferably have an associated version tag that can be incremented alongside the port's `"version"`.
</details>
<details id="c000006">
<summary><a href="#c000006">c000006</a>: New ports pass CI checks for triplets that the library officially supports</summary>
To ensure vcpkg ports are of a high quality, we ask that incoming ports support the official platforms for the library in question.
</details>
<details id="c000007">
<summary><a href="#c000007">c000007</a>: Patches fix issues that are vcpkg-specific only</summary>
If possible, patches to the library source code should be upstreamed to the library's official repository. Opening up a pull request on the library's repository will help to improve the library for everyone, not just vcpkg users.
</details>
<details id="c000008">
<summary><a href="#c000008">c000008</a>: New ports download source code from the official source if available</summary>
To respect library authors and keep code secure, please have ports download source code from the official source. We may make exceptions if the original source code is not available and there is substantial community interest in maintaining the library in question.
</details>
<details id="c000009">
<summary><a href="#c000009">c000009</a>: Ports and port features are named correctly</summary>
For user accessibility, we prefer names of ports and port features to be intuitive and close to their counterparts in official sources and other package managers. If you are unsure about the naming of a port or port feature, we recommend checking repology.org, packages.ubuntu.com, or searching for additional information using a search engine. We can also help our contributors with this, so feel free to ask for naming suggestions if you are unsure.
</details>
<details id="c000010">
<summary><a href="#c000010">c000010</a>: Library targets are exported when appropriate</summary>
To provide users with a seamless build system integration, please be sure to export and provide a means of finding the library targets intended to be used downstream. Targets not meant to be exported should be be marked private and not exported.
</details>
<details id="c000011">
<summary><a href="#c000011">c000011</a>: Ports do not use applications which modify the user's system</summary>
Ports should uphold vcpkg's contract of not modifying the user's system by avoiding applications which do so. Examples of these applications are `sudo`, `apt`, `brew`, or `pip`. Please use an alternative to these types of programs wherever possible.
</details>
<details id="c000012">
<summary><a href="#c000012">c000012</a>: Ports with system dependencies include an information message during installation</summary>
Some ports have library and tool dependencies that do not exist within vcpkg. For these missing dependencies, we ask that contributors add a message to the top of the port's `portfile.cmake` stating the missing dependencies and how to acquire them. We ask that the message is displayed before any major work is done to ensure that users can "early out" of the installation process as soon as possible in case they are missing the dependency.
Example:
```cmake
message(
"${PORT} currently requires the following libraries from the system package manager:
autoconf libtool
These can be installed on Ubuntu systems via sudo apt install autoconf libtool"
)
```
</details>
<details id="c000013">
<summary><a href="#c000013">c000013</a>: Manifest files are used instead of CONTROL files for new ports</summary>
Many existing ports use the CONTROL file syntax; while this syntax will be supported for some time to come,
new ports should not use these. Any newly added port _must_ use the manifest files.
We also recommend, when significant modifications are made to ports, that one switches to manifest files;
however, this is not required. You may find `vcpkg format-manifest` useful.

365
externals/vcpkg/docs/maintainers/registries.md vendored Executable file
View File

@@ -0,0 +1,365 @@
# Creating Registries
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/maintainers/registries.md).**
There are two parts to using registries; this documents the creation side of
the relationship. In order to learn more about using registries that others
have created, please read [this documentation](../users/registries.md).
## Table of Contents
- [Creating Registries](#creating-registries)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [Git Registries](#git-registries)
- [Adding a New Version](#adding-a-new-version)
- [Filesystem Registries](#filesystem-registries)
- [Adding a New Version](#adding-a-new-version-1)
- [Builtin Registries](#builtin-registries)
## Overview
Registries are collections of ports and their versions. There are two major
choices of implementation for registries, if you want to create your own -
git registries, and filesystem registries.
Git registries are simple git repositories, and can be shared publicly or
privately via normal mechanisms for git repositories. The vcpkg repository at
<https://github.com/microsoft/vcpkg>, for example, is a git registry.
Filesystem registries are designed as more of a testing ground. Given that they
literally live on your filesystem, the only way to share them is via shared
directories. However, filesystem registries can be useful as a way to represent
registries held in non-git version control systems, assuming one has some way
to get the registry onto the disk.
Note that we expect the set of registry types to grow over time; if you would
like support for registries built in your favorite public version control
system, don't hesitate to open a PR.
The basic structure of a registry is:
- The set of versions that are considered "latest" at certain times in history,
known as the "baseline".
- The set of all the versions of all the ports, and where to find each of
these in the registry.
### Git Registries
As you're following along with this documentation, it may be helpful to have
a working example to refer to. We've written one and put it here:
<https://github.com/northwindtraders/vcpkg-registry>.
All git registries must have a `versions/baseline.json` file. This file
contains the set of "latest versions" at a certain commit. It is laid out as
a top-level object containing only the `"default"` field. This field should
contain an object mapping port names to the version which is currently the
latest.
Here's an example of a valid baseline.json:
```json
{
"default": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
}
}
```
The `versions` directory contains all the information about which versions of
which packages are contained in the registry, along with where those versions
are stored. The rest of the registry just acts as a backing store, as far as
vcpkg is concerned: only things inside the `versions` directory will be used
to direct how your registry is seen by vcpkg.
Each port in a registry should exist in the versions directory as
`<first letter of port>-/<name of port>.json`; in other words, the
information about the `kitten` port would be located in
`versions/k-/kitten.json`. This should be a top-level object with only a
single field: `"versions"`. This field should contain an array of version
objects:
- The version of the port in question; should be exactly the same as the
`vcpkg.json` file, including the version fields and `"port-version"`.
- The `"git-tree"` field, which is a git tree; in other words, what you get
when you write `git rev-parse COMMIT-ID:path/to/port`.
Note that the version fields for ports with `CONTROL` files, is
`"version-string"`; we do not recommend using `CONTROL` files in new
registries, however.
_WARNING_: One very important part of registries is that versions should
_never_ be changed. Updating to a later ref should never remove or change an
existing version. It must always be safe to update a registry.
Here's an example of a valid version database for a `kitten` port with one
version:
```json
{
"versions": [
{
"version": "2.6.2",
"port-version": 0,
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
}
]
}
```
In general, it's not important where you place port directories. However, the
idiom in vcpkg is to follow what the built in vcpkg registry does: your
`kitten` port should be placed in `ports/kitten`.
_WARNING_: One other thing to keep in mind is that when you update a registry,
all previous versions should also be accessible. Since your user will set their
baseline to a commit ID, that commit ID must always exist, and be accessible
from your HEAD commit, which is what is actually fetched. This means that your
HEAD commit should be a child of all previous HEAD commits.
### Builtin Registries
Builtin registries are treated as special Git registries. Instead of fetching
from a remote url, builtin registries consult the `$VCPKG_ROOT/.git` directory
of the vcpkg clone. They use the currently checked out `$VCPKG_ROOT/versions`
directory as the source for versioning information.
#### Adding a New Version
There is some git trickery involved in creating a new version of a port. The
first thing to do is make some changes, update the `"port-version"` and regular
version field as you need to, and then test with `overlay-ports`:
`vcpkg install kitten --overlay-ports=ports/kitten`.
Once you've finished your testing, you'll need to make sure that the directory
as it is is under git's purview. You'll do this by creating a temporary commit:
```pwsh
> git add ports/kitten
> git commit -m 'temporary commit'
```
Then, get the git tree ID of the directory:
```pwsh
> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07
```
Then, you can add this version to the versions database. At the top of your
`versions/k-/kitten.json`, you can add (assuming you're adding version
`2.6.3#0`):
```json
{
"versions": [
{
"version": "2.6.3",
"port-version": 0,
"git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
},
{
"version": "2.6.2",
"port-version": 0,
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
}
]
}
```
then, you'll want to modify your `versions/baseline.json` with your new version
as well:
```json
{
"default": {
"kitten": {
"baseline": "2.6.3",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
}
}
```
and amend your current commit:
```pwsh
> git commit --amend
```
then share away!
### Filesystem Registries
As you're following along with this documentation, it may be helpful to have
a working example to refer to. We've written one and put it here:
<https://github.com/vcpkg/example-filesystem-registry>.
All filesystem registries must have a `versions/baseline.json` file. This file
contains the set of "latest versions" for a certain version of the registry.
It is laid out as a top-level object containing a map from version name to
"baseline objects", which map port names to the version which is considered
"latest" for that version of the registry.
Filesystem registries need to decide on a versioning scheme. Unlike git
registries, which have the implicit versioning scheme of refs, filesystem
registries can't rely on the version control system here. One possible option
is to do a daily release, and have your "versions" be dates.
_WARNING_: A baseline must always refer to the same set of versions. If you
want to add new versions, you need to create a new version of the registry in
the `baseline.json` file.
Here's an example of a valid `baseline.json`, for a registry that has decided
upon dates for their versions:
```json
{
"2021-04-16": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
},
"2021-04-15": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 1
}
}
}
```
The `versions` directory contains all the information about which versions of
which packages are contained in the registry, along with where those versions
are stored. The rest of the registry just acts as a backing store, as far as
vcpkg is concerned: only things inside the `versions` directory will be used
to direct how your registry is seen by vcpkg.
Each port in a registry should exist in the versions directory as
`<first letter of port>-/<name of port>.json`; in other words, the
information about the `kitten` port would be located in
`versions/k-/kitten.json`. This should be a top-level object with only a
single field: `"versions"`. This field should contain an array of version
objects:
- The version of the port in question; should be exactly the same as the
`vcpkg.json` file, including the version fields and `"port-version"`.
- The `"path"` field: a relative directory, rooted at the base of the registry
(in other words, the directory where `versions` is located), to the port
directory. It should look something like `"$/path/to/port/dir`"
Note that the version fields for ports with `CONTROL` files, is
`"version-string"`; we do not recommend using `CONTROL` files in new
registries, however.
In general, it's not important where you place port directories. However, the
idiom in vcpkg is to follow somewhat closely to what the built in vcpkg
registry does: your `kitten` port at version `x.y.z` should be placed in
`ports/kitten/x.y.z`, with port versions appended as you see fit (although
since `#` is not a good character to use for file names, perhaps use `_`).
_WARNING_: One very important part of registries is that versions should
_never_ be changed. One should never remove or change an existing version.
Your changes to your registry shouldn't change behavior to downstream users.
Here's an example of a valid version database for a `kitten` port with one
version:
```json
{
"versions": [
{
"version": "2.6.2",
"port-version": 0,
"path": "$/ports/kitten/2.6.2_0"
}
]
}
```
#### Adding a New Version
Unlike git registries, adding a new version to a filesystem registry mostly
involves a lot of copying. The first thing to do is to copy the latest
version of your port into a new version directory, update the version and
`"port-version"` fields as you need to, and then test with `overlay-ports`:
`vcpkg install kitten --overlay-ports=ports/kitten/new-version`.
Once you've finished your testing, you can add this new version to the top of
your `versions/k-/kitten.json`:
```json
{
"versions": [
{
"version": "2.6.3",
"port-version": 0,
"path": "$/ports/kitten/2.6.3_0"
},
{
"version": "2.6.2",
"port-version": 0,
"path": "$/ports/kitten/2.6.2_0"
}
]
}
```
then, you'll want to modify your `versions/baseline.json` with your new version
as well (remember not to modify existing baselines):
```json
{
"2021-04-17": {
"kitten": {
"baseline": "2.6.3",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
},
"2021-04-16": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 2
}
},
"2021-04-15": {
"kitten": {
"baseline": "2.6.2",
"port-version": 0
},
"port-b": {
"baseline": "19.00",
"port-version": 1
}
}
}
```
and you're done!

60
externals/vcpkg/docs/maintainers/vcpkg_acquire_msys.md vendored Executable file
View File

@@ -0,0 +1,60 @@
# vcpkg_acquire_msys
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_acquire_msys.md).
Download and prepare an MSYS2 instance.
## Usage
```cmake
vcpkg_acquire_msys(<MSYS_ROOT_VAR>
PACKAGES <package>...
[NO_DEFAULT_PACKAGES]
[DIRECT_PACKAGES <URL> <SHA512> <URL> <SHA512> ...]
)
```
## Parameters
### MSYS_ROOT_VAR
An out-variable that will be set to the path to MSYS2.
### PACKAGES
A list of packages to acquire in msys.
To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.16)`
### NO_DEFAULT_PACKAGES
Exclude the normal base packages.
The list of base packages includes: bash, coreutils, sed, grep, gawk, gzip, diffutils, make, and pkg-config
### DIRECT_PACKAGES
A list of URL/SHA512 pairs to acquire in msys.
This parameter can be used by a port to privately extend the list of msys packages to be acquired.
The URLs can be found on the msys2 website[1] and should be a direct archive link:
https://repo.msys2.org/mingw/i686/mingw-w64-i686-gettext-0.19.8.1-9-any.pkg.tar.zst
[1] https://packages.msys2.org/search
## Notes
A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`:
```cmake
vcpkg_acquire_msys(MSYS_ROOT)
set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
vcpkg_execute_required_process(
COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh"
WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
LOGNAME build-${TARGET_TRIPLET}-rel
)
```
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_acquire\_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)

27
externals/vcpkg/docs/maintainers/vcpkg_add_to_path.md vendored Executable file
View File

@@ -0,0 +1,27 @@
# vcpkg_add_to_path
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_add_to_path.md).
Add a directory or directories to the PATH environment variable
```cmake
vcpkg_add_to_path([PREPEND] [<path>...])
```
`vcpkg_add_to_path` adds all of the paths passed to it to the PATH environment variable.
If PREPEND is passed, then those paths are prepended to the PATH environment variable,
so that they are searched first; otherwise, those paths are appended, so they are
searched after the paths which are already in the environment variable.
The paths are added in the order received, so that the first path is always searched
before a later path.
If no paths are passed, then nothing will be done.
## Examples:
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)
* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
## Source
[scripts/cmake/vcpkg\_add\_to\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

18
externals/vcpkg/docs/maintainers/vcpkg_apply_patches.md vendored Executable file
View File

@@ -0,0 +1,18 @@
# vcpkg_apply_patches
**This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_apply_patches.md).
Apply a set of patches to a source tree.
```cmake
vcpkg_apply_patches(
SOURCE_PATH <${SOURCE_PATH}>
[QUIET]
PATCHES <patch1.patch>...
)
```
## Source
[scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)

26
externals/vcpkg/docs/maintainers/vcpkg_backup_restore_env_vars.md vendored Executable file
View File

@@ -0,0 +1,26 @@
# vcpkg_backup_restore_env_vars
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_backup_restore_env_vars.md).
Backup or restore the environment variables
## Usage:
```cmake
vcpkg_backup_env_variables(VARS [<environment-variable>...])
vcpkg_restore_env_variables(VARS [<environment-variable>...])
```
### VARS
The variables to back up or restore.
These are placed in the parent scope, so you must backup and restore
from the same scope.
## Notes
One must always call `vcpkg_backup_env_variables` before
`vcpkg_restore_env_variables`; however, `vcpkg_restore_env_variables`
does not change the back up variables, and so you may call `restore`
multiple times for one `backup`.
## Source
[scripts/cmake/vcpkg\_backup\_restore\_env\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_backup_restore_env_vars.cmake)

38
externals/vcpkg/docs/maintainers/vcpkg_build_cmake.md vendored Executable file
View File

@@ -0,0 +1,38 @@
# vcpkg_build_cmake
**This function has been deprecated in favor of [`vcpkg_cmake_build`](ports/vcpkg-cmake/vcpkg_cmake_build.md) from the vcpkg-cmake port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
Build a cmake project.
## Usage:
```cmake
vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>])
```
## Parameters:
### DISABLE_PARALLEL
The underlying buildsystem will be instructed to not parallelize
### TARGET
The target passed to the cmake build command (`cmake --build . --target <target>`). If not specified, no target will
be passed.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin` directories to the path during the build such that executables can run against the in-tree DLLs.
## Notes:
This command should be preceded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the
"install" target
## Examples:
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)

57
externals/vcpkg/docs/maintainers/vcpkg_build_make.md vendored Executable file
View File

@@ -0,0 +1,57 @@
# vcpkg_build_make
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_make.md).
Build a linux makefile project.
## Usage:
```cmake
vcpkg_build_make([BUILD_TARGET <target>]
[INSTALL_TARGET <target>]
[ADD_BIN_TO_PATH]
[ENABLE_INSTALL]
[MAKEFILE <makefileName>]
[LOGFILE_ROOT <logfileroot>]
[DISABLE_PARALLEL]
[SUBPATH <path>])
```
### BUILD_TARGET
The target passed to the make build command (`./make <target>`). If not specified, the 'all' target will
be passed.
### INSTALL_TARGET
The target passed to the make build command (`./make <target>`) if `ENABLE_INSTALL` is used. Defaults to 'install'.
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
### ENABLE_INSTALL
IF the port supports the install target use vcpkg_install_make() instead of vcpkg_build_make()
### MAKEFILE
Specifies the Makefile as a relative path from the root of the sources passed to `vcpkg_configure_make()`
### LOGFILE_ROOT
Specifies a log file prefix.
### DISABLE_PARALLEL
The underlying buildsystem will be instructed to not parallelize
### SUBPATH
Additional subdir to invoke make in. Useful if only parts of a port should be built.
## Notes:
This command should be preceded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your makefile supports the
"install" target
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)

66
externals/vcpkg/docs/maintainers/vcpkg_build_msbuild.md vendored Executable file
View File

@@ -0,0 +1,66 @@
# vcpkg_build_msbuild
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_msbuild.md).
Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
## Usage
```cmake
vcpkg_build_msbuild(
PROJECT_PATH <${SOURCE_PATH}/port.sln>
[RELEASE_CONFIGURATION <Release>]
[DEBUG_CONFIGURATION <Debug>]
[TARGET <Build>]
[TARGET_PLATFORM_VERSION <10.0.15063.0>]
[PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
[PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
[OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
[OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
[OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
[USE_VCPKG_INTEGRATION]
)
```
## Parameters
### USE_VCPKG_INTEGRATION
Apply the normal `integrate install` integration for building the project.
By default, projects built with this command will not automatically link libraries or have header paths set.
### PROJECT_PATH
The path to the solution (`.sln`) or project (`.vcxproj`) file.
### RELEASE_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
### DEBUG_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter)
used for Debug builds.
### TARGET_PLATFORM_VERSION
The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
### TARGET
The MSBuild target to build. (``/t:<TARGET>``)
### PLATFORM
The platform (``/p:Platform`` msbuild parameter) used for the build.
### PLATFORM_TOOLSET
The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
### OPTIONS
Additional options passed to msbuild for all builds.
### OPTIONS_RELEASE
Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
## Examples
* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)

19
externals/vcpkg/docs/maintainers/vcpkg_build_ninja.md vendored Executable file
View File

@@ -0,0 +1,19 @@
# vcpkg_build_ninja
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_ninja.md).
Build a ninja project
## Usage:
```cmake
vcpkg_build_ninja(
[TARGETS <target>...]
)
```
## Parameters:
### TARGETS
Only build the specified targets.
## Source
[scripts/cmake/vcpkg\_build\_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)

72
externals/vcpkg/docs/maintainers/vcpkg_build_nmake.md vendored Executable file
View File

@@ -0,0 +1,72 @@
# vcpkg_build_nmake
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_nmake.md).
Build a msvc makefile project.
## Usage:
```cmake
vcpkg_build_nmake(
SOURCE_PATH <${SOURCE_PATH}>
[NO_DEBUG]
[ENABLE_INSTALL]
[TARGET <all>]
[PROJECT_SUBPATH <${SUBPATH}>]
[PROJECT_NAME <${MAKEFILE_NAME}>]
[PRERUN_SHELL <${SHELL_PATH}>]
[PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
[PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
[TARGET <target>])
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the source files.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile.
### PROJECT_NAME
Specifies the name of msvc makefile name.
Default is `makefile.vc`
### ENABLE_INSTALL
Install binaries after build.
### PRERUN_SHELL
Script that needs to be called before build
### PRERUN_SHELL_DEBUG
Script that needs to be called before debug build
### PRERUN_SHELL_RELEASE
Script that needs to be called before release build
### OPTIONS
Additional options passed to generate during the generation.
### OPTIONS_RELEASE
Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
### TARGET
The target passed to the nmake build command (`nmake/nmake install`). If not specified, no target will
be passed.
## Notes:
You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your makefile supports the
"install" target
## Examples
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)

12
externals/vcpkg/docs/maintainers/vcpkg_build_qmake.md vendored Executable file
View File

@@ -0,0 +1,12 @@
# vcpkg_build_qmake
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_qmake.md).
Build a qmake-based project, previously configured using vcpkg_configure_qmake.
```cmake
vcpkg_build_qmake()
```
## Source
[scripts/cmake/vcpkg\_build\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)

16
externals/vcpkg/docs/maintainers/vcpkg_buildpath_length_warning.md vendored Executable file
View File

@@ -0,0 +1,16 @@
# vcpkg_buildpath_length_warning
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_buildpath_length_warning.md).
Warns the user if their vcpkg installation path might be too long for the package they're installing.
```cmake
vcpkg_buildpath_length_warning(<N>)
```
`vcpkg_buildpath_length_warning` warns the user if the number of bytes in the
path to `buildtrees` is bigger than `N`. Note that this is simply a warning,
and isn't relied on for correctness.
## Source
[scripts/cmake/vcpkg\_buildpath\_length\_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)

136
externals/vcpkg/docs/maintainers/vcpkg_check_features.md vendored Executable file
View File

@@ -0,0 +1,136 @@
# vcpkg_check_features
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_features.md).
Check if one or more features are a part of a package installation.
```cmake
vcpkg_check_features(
OUT_FEATURE_OPTIONS <out-var>
[PREFIX <prefix>]
[FEATURES
[<feature-name> <feature-var>]...
]
[INVERTED_FEATURES
[<feature-name> <feature-var>]...
]
)
```
The `<out-var>` should be set to `FEATURE_OPTIONS` by convention.
`vcpkg_check_features()` will:
- for each `<feature-name>` passed in `FEATURES`:
- if the feature is set, add `-D<feature-var>=ON` to `<out-var>`,
and set `<prefix>_<feature-var>` to ON.
- if the feature is not set, add `-D<feature-var>=OFF` to `<out-var>`,
and set `<prefix>_<feature-var>` to OFF.
- for each `<feature-name>` passed in `INVERTED_FEATURES`:
- if the feature is set, add `-D<feature-var>=OFF` to `<out-var>`,
and set `<prefix>_<feature-var>` to OFF.
- if the feature is not set, add `-D<feature-var>=ON` to `<out-var>`,
and set `<prefix>_<feature-var>` to ON.
If `<prefix>` is not passed, then the feature vars set are simply `<feature-var>`,
not `_<feature-var>`.
If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional.
This behavior is deprecated.
If the same `<feature-var>` is passed multiple times,
then `vcpkg_check_features` will cause a fatal error,
since that is a bug.
## Examples
### Example 1: Regular features
```cmake
$ ./vcpkg install mimalloc[asm,secure]
# ports/mimalloc/portfile.cmake
vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
FEATURES
asm MI_SEE_ASM
override MI_OVERRIDE
secure MI_SECURE
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
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(
INVERTED_FEATURES
brotli CPPREST_EXCLUDE_BROTLI
websockets CPPREST_EXCLUDE_WEBSOCKETS
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
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(
FEATURES
cuda WITH_CUDA
cuda BUILD_CUDA
cuda BUILD_GPU
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
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(
FEATURES
tbb WITH_TBB
INVERTED_FEATURES
tbb ROCKSDB_IGNORE_PACKAGE_TBB
)
vcpkg_cmake_configure(
SOURCE_PATH ${SOURCE_PATH}
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)

38
externals/vcpkg/docs/maintainers/vcpkg_check_linkage.md vendored Executable file
View File

@@ -0,0 +1,38 @@
# vcpkg_check_linkage
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_check_linkage.md).
Asserts the available library and CRT linkage options for the port.
## Usage
```cmake
vcpkg_check_linkage(
[ONLY_STATIC_LIBRARY | ONLY_DYNAMIC_LIBRARY]
[ONLY_STATIC_CRT | ONLY_DYNAMIC_CRT]
)
```
## Parameters
### ONLY_STATIC_LIBRARY
Indicates that this port can only be built with static library linkage.
Note: If the user requested a dynamic build ONLY_STATIC_LIBRARY will result in a note being printed, not a fatal error.
### ONLY_DYNAMIC_LIBRARY
Indicates that this port can only be built with dynamic/shared library linkage.
### ONLY_STATIC_CRT
Indicates that this port can only be built with static CRT linkage.
### ONLY_DYNAMIC_CRT
Indicates that this port can only be built with dynamic/shared CRT linkage.
## Notes
This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail, depending on what was requested by the user versus what the library supports.
## Examples
* [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_check\_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)

25
externals/vcpkg/docs/maintainers/vcpkg_clean_executables_in_bin.md vendored Executable file
View File

@@ -0,0 +1,25 @@
# vcpkg_clean_executables_in_bin
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_clean_executables_in_bin.md).
Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories.
## Usage
```cmake
vcpkg_clean_executables_in_bin(
FILE_NAMES <file1>...
)
```
## Parameters
### FILE_NAMES
A list of executable filenames without extension.
## Notes
Generally, there is no need to call this function manually. Instead, pass an extra `AUTO_CLEAN` argument when calling `vcpkg_copy_tools`.
## Examples
* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_clean\_executables\_in\_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake)

17
externals/vcpkg/docs/maintainers/vcpkg_clean_msbuild.md vendored Executable file
View File

@@ -0,0 +1,17 @@
# vcpkg_clean_msbuild
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_clean_msbuild.md).
Clean intermediate files generated by `vcpkg_install_msbuild()`.
## Usage
```cmake
vcpkg_clean_msbuild()
```
## Examples
* [python3](https://github.com/Microsoft/vcpkg/blob/master/ports/python3/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_clean\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)

36
externals/vcpkg/docs/maintainers/vcpkg_common_definitions.md vendored Executable file
View File

@@ -0,0 +1,36 @@
# vcpkg_common_definitions
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_common_definitions.md).
This file defines the following variables which are commonly needed or used in portfiles:
```cmake
VCPKG_TARGET_IS_<target> with <target> being one of the following: WINDOWS, UWP, MINGW, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
VCPKG_HOST_IS_<host> with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
VCPKG_HOST_PATH_SEPARATOR Host specific path separator (USAGE: "<something>${VCPKG_HOST_PATH_SEPARATOR}<something>"; only use and pass variables with VCPKG_HOST_PATH_SEPARATOR within "")
VCPKG_HOST_EXECUTABLE_SUFFIX executable suffix of the host
VCPKG_TARGET_EXECUTABLE_SUFFIX executable suffix of the target
VCPKG_HOST_BUNDLE_SUFFIX bundle suffix of the host
VCPKG_TARGET_BUNDLE_SUFFIX bundle suffix of the target
VCPKG_TARGET_STATIC_LIBRARY_PREFIX static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
VCPKG_TARGET_STATIC_LIBRARY_SUFFIX static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
VCPKG_TARGET_SHARED_LIBRARY_PREFIX shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
VCPKG_TARGET_SHARED_LIBRARY_SUFFIX shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
VCPKG_TARGET_IMPORT_LIBRARY_PREFIX import library prefix for target (same as CMAKE_IMPORT_LIBRARY_PREFIX)
VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX import library suffix for target (same as CMAKE_IMPORT_LIBRARY_SUFFIX)
VCPKG_FIND_LIBRARY_PREFIXES target dependent prefixes used for find_library calls in portfiles
VCPKG_FIND_LIBRARY_SUFFIXES target dependent suffixes used for find_library calls in portfiles
VCPKG_SYSTEM_LIBRARIES list of libraries are provide by the toolchain and are not managed by vcpkg
TARGET_TRIPLET the name of the current triplet to build for
CURRENT_INSTALLED_DIR the absolute path to the installed files for the current triplet
HOST_TRIPLET the name of the triplet corresponding to the host
CURRENT_HOST_INSTALLED_DIR the absolute path to the installed files for the host triplet
VCPKG_CROSSCOMPILING Whether vcpkg is cross-compiling: in other words, whether TARGET_TRIPLET and HOST_TRIPLET are different
```
CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target
Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that
portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
## Source
[scripts/cmake/vcpkg\_common\_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)

87
externals/vcpkg/docs/maintainers/vcpkg_configure_cmake.md vendored Executable file
View File

@@ -0,0 +1,87 @@
# vcpkg_configure_cmake
**This function has been deprecated in favor of [`vcpkg_cmake_configure`](ports/vcpkg-cmake/vcpkg_cmake_configure.md) from the vcpkg-cmake port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md).
Configure CMake for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_cmake(
SOURCE_PATH <${SOURCE_PATH}>
[PREFER_NINJA]
[DISABLE_PARALLEL_CONFIGURE]
[NO_CHARSET_FLAG]
[GENERATOR <"NMake Makefiles">]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
[MAYBE_UNUSED_VARIABLES <OPTION_NAME>...]
)
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `CMakeLists.txt`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PREFER_NINJA
Indicates that, when available, Vcpkg should use Ninja to perform the build.
This should be specified unless the port is known to not work under Ninja.
### DISABLE_PARALLEL_CONFIGURE
Disables running the CMake configure step in parallel.
This is needed for libraries which write back into their source directory during configure.
This also disables CMAKE_DISABLE_SOURCE_CHANGES.
### NO_CHARSET_FLAG
Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
This is needed for libraries that set their own source code's character set.
### GENERATOR
Specifies the precise generator to use.
This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
If used for this purpose, it should be set to `"NMake Makefiles"`.
### OPTIONS
Additional options passed to CMake during the configuration.
### OPTIONS_RELEASE
Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
### MAYBE_UNUSED_VARIABLES
Any CMake variables which are explicitly passed in, but which may not be used on all platforms.
For example:
```cmake
vcpkg_cmake_configure(
...
OPTIONS
-DBUILD_EXAMPLE=OFF
...
MAYBE_UNUSED_VARIABLES
BUILD_EXAMPLE
)
```
### LOGNAME
Name of the log to write the output of the configure call to.
## Notes
This command supplies many common arguments to CMake. To see the full list, examine the source.
## Examples
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_configure\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)

34
externals/vcpkg/docs/maintainers/vcpkg_configure_gn.md vendored Executable file
View File

@@ -0,0 +1,34 @@
# vcpkg_configure_gn
**This function has been deprecated in favor of [`vcpkg_gn_configure`](ports/vcpkg-gn/vcpkg_gn_configure.md) from the vcpkg-gn port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_gn.md).
Generate Ninja (GN) targets
## Usage:
```cmake
vcpkg_configure_gn(
SOURCE_PATH <SOURCE_PATH>
[OPTIONS <OPTIONS>]
[OPTIONS_DEBUG <OPTIONS_DEBUG>]
[OPTIONS_RELEASE <OPTIONS_RELEASE>]
)
```
## Parameters:
### SOURCE_PATH (required)
The path to the GN project.
### OPTIONS
Options to be passed to both the debug and release targets.
Note: Must be provided as a space-separated string.
### OPTIONS_DEBUG (space-separated string)
Options to be passed to the debug target.
### OPTIONS_RELEASE (space-separated string)
Options to be passed to the release target.
## Source
[scripts/cmake/vcpkg\_configure\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake)

94
externals/vcpkg/docs/maintainers/vcpkg_configure_make.md vendored Executable file
View File

@@ -0,0 +1,94 @@
# vcpkg_configure_make
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_make.md).
Configure configure for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_make(
SOURCE_PATH <${SOURCE_PATH}>
[AUTOCONFIG]
[USE_WRAPPERS]
[DETERMINE_BUILD_TRIPLET]
[BUILD_TRIPLET "--host=x64 --build=i686-unknown-pc"]
[NO_ADDITIONAL_PATHS]
[CONFIG_DEPENDENT_ENVIRONMENT <SOME_VAR>...]
[CONFIGURE_ENVIRONMENT_VARIABLES <SOME_ENVVAR>...]
[ADD_BIN_TO_PATH]
[DISABLE_VERBOSE_FLAGS]
[NO_DEBUG]
[SKIP_CONFIGURE]
[PROJECT_SUBPATH <${PROJ_SUBPATH}>]
[PRERUN_SHELL <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
)
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `configure`/`configure.ac`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the directory containing the ``configure`/`configure.ac`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### SKIP_CONFIGURE
Skip configure process
### USE_WRAPPERS
Use autotools ar-lib and compile wrappers (only applies to windows cl and lib)
### BUILD_TRIPLET
Used to pass custom --build/--target/--host to configure. Can be globally overwritten by VCPKG_MAKE_BUILD_TRIPLET
### DETERMINE_BUILD_TRIPLET
For ports having a configure script following the autotools rules for selecting the triplet
### NO_ADDITIONAL_PATHS
Don't pass any additional paths except for --prefix to the configure call
### AUTOCONFIG
Need to use autoconfig to generate configure file.
### PRERUN_SHELL
Script that needs to be called before configuration (do not use for batch files which simply call autoconf or configure)
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during configure such that executables can run against the in-tree DLLs.
### DISABLE_VERBOSE_FLAGS
Do not pass '--disable-silent-rules --verbose' to configure.
### OPTIONS
Additional options passed to configure during the configuration.
### OPTIONS_RELEASE
Additional options passed to configure during the Release configuration. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to configure during the Debug configuration. These are in addition to `OPTIONS`.
### CONFIG_DEPENDENT_ENVIRONMENT
List of additional configuration dependent environment variables to set.
Pass SOMEVAR to set the environment and have SOMEVAR_(DEBUG|RELEASE) set in the portfile to the appropriate values
General environment variables can be set from within the portfile itself.
### CONFIGURE_ENVIRONMENT_VARIABLES
List of additional environment variables to pass via the configure call.
## Notes
This command supplies many common arguments to configure. To see the full list, examine the source.
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_configure\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)

44
externals/vcpkg/docs/maintainers/vcpkg_configure_meson.md vendored Executable file
View File

@@ -0,0 +1,44 @@
# vcpkg_configure_meson
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_meson.md).
Configure Meson for Debug and Release builds of a project.
## Usage
```cmake
vcpkg_configure_meson(
SOURCE_PATH <${SOURCE_PATH}>
[NO_PKG_CONFIG]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
)
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `meson.build`.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### OPTIONS
Additional options passed to Meson during the configuration.
### OPTIONS_RELEASE
Additional options passed to Meson during the Release configuration. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to Meson during the Debug configuration. These are in addition to `OPTIONS`.
### NO_PKG_CONFIG
Disable pkg-config setup
## Notes
This command supplies many common arguments to Meson. To see the full list, examine the source.
## Examples
* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_configure\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)

29
externals/vcpkg/docs/maintainers/vcpkg_configure_qmake.md vendored Executable file
View File

@@ -0,0 +1,29 @@
# vcpkg_configure_qmake
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_qmake.md).
Configure a qmake-based project.
```cmake
vcpkg_configure_qmake(
SOURCE_PATH <pro_file_path>
[OPTIONS arg1 [arg2 ...]]
[OPTIONS_RELEASE arg1 [arg2 ...]]
[OPTIONS_DEBUG arg1 [arg2 ...]]
[BUILD_OPTIONS arg1 [arg2 ...]]
[BUILD_OPTIONS_RELEASE arg1 [arg2 ...]]
[BUILD_OPTIONS_DEBUG arg1 [arg2 ...]]
)
```
### SOURCE_PATH
The path to the *.pro qmake project file.
### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
The options passed to qmake to the configure step.
### BUILD\_OPTIONS, BUILD\_OPTIONS\_RELEASE, BUILD\_OPTIONS\_DEBUG
The options passed to qmake to the build step.
## Source
[scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)

29
externals/vcpkg/docs/maintainers/vcpkg_copy_pdbs.md vendored Executable file
View File

@@ -0,0 +1,29 @@
# vcpkg_copy_pdbs
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_pdbs.md).
Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
```cmake
vcpkg_copy_pdbs(
[BUILD_PATHS <glob>...])
```
The `<glob>`s are patterns which will be passed to `file(GLOB_RECURSE)`,
for locating DLLs. It defaults to using:
- `${CURRENT_PACKAGES_DIR}/bin/*.dll`
- `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`
since that is generally where DLLs are located.
## Notes
This command should always be called by portfiles after they have finished rearranging the binary output.
## Examples
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)

23
externals/vcpkg/docs/maintainers/vcpkg_copy_tool_dependencies.md vendored Executable file
View File

@@ -0,0 +1,23 @@
# vcpkg_copy_tool_dependencies
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tool_dependencies.md).
Copy all DLL dependencies of built tools into the tool folder.
## Usage
```cmake
vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
```
## Parameters
The path to the directory containing the tools.
## Notes
This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
## Examples
* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_copy\_tool\_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)

36
externals/vcpkg/docs/maintainers/vcpkg_copy_tools.md vendored Executable file
View File

@@ -0,0 +1,36 @@
# vcpkg_copy_tools
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_copy_tools.md).
Copy tools and all their DLL dependencies into the `tools` folder.
## Usage
```cmake
vcpkg_copy_tools(
TOOL_NAMES <tool1>...
[SEARCH_DIR <${CURRENT_PACKAGES_DIR}/bin>]
[DESTINATION <${CURRENT_PACKAGES_DIR}/tools/${PORT}>]
[AUTO_CLEAN]
)
```
## Parameters
### TOOL_NAMES
A list of tool filenames without extension.
### SEARCH_DIR
The path to the directory containing the tools. This will be set to `${CURRENT_PACKAGES_DIR}/bin` if omitted.
### DESTINATION
Destination to copy the tools to. This will be set to `${CURRENT_PACKAGES_DIR}/tools/${PORT}` if omitted.
### AUTO_CLEAN
Auto clean the copied executables from `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`.
## Examples
* [cpuinfo](https://github.com/microsoft/vcpkg/blob/master/ports/cpuinfo/portfile.cmake)
* [nanomsg](https://github.com/microsoft/vcpkg/blob/master/ports/nanomsg/portfile.cmake)
* [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_copy\_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)

62
externals/vcpkg/docs/maintainers/vcpkg_download_distfile.md vendored Executable file
View File

@@ -0,0 +1,62 @@
# vcpkg_download_distfile
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_download_distfile.md).
Download and cache a file needed for this port.
This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
## Usage
```cmake
vcpkg_download_distfile(
<OUT_VARIABLE>
URLS <http://mainUrl> <http://mirror1>...
FILENAME <output.zip>
SHA512 <5981de...>
[ALWAYS_REDOWNLOAD]
)
```
## Parameters
### OUT_VARIABLE
This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
### URLS
A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
### FILENAME
The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
### SHA512
The expected hash for the file.
If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
### QUIET
Suppress output on cache hit
### SKIP_SHA512
Skip SHA512 hash check for file.
This switch is only valid when building with the `--head` command line flag.
### ALWAYS_REDOWNLOAD
Avoid caching; this is a REST call or otherwise unstable.
Requires `SKIP_SHA512`.
### HEADERS
A list of headers to append to the download request. This can be used for authentication during a download.
Headers should be specified as "<header-name>: <header-value>".
## Notes
The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
## Examples
* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)

38
externals/vcpkg/docs/maintainers/vcpkg_execute_build_process.md vendored Executable file
View File

@@ -0,0 +1,38 @@
# vcpkg_execute_build_process
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_build_process.md).
Execute a required build process
## Usage
```cmake
vcpkg_execute_build_process(
COMMAND <cmd> [<args>...]
[NO_PARALLEL_COMMAND <cmd> [<args>...]]
WORKING_DIRECTORY </path/to/dir>
LOGNAME <log_name>
)
```
## Parameters
### COMMAND
The command to be executed, along with its arguments.
### NO_PARALLEL_COMMAND
Optional parameter which specifies a non-parallel command to attempt if a
failure potentially due to parallelism is detected.
### WORKING_DIRECTORY
The directory to execute the command in.
### LOGNAME
The prefix to use for the log files.
This should be a unique name for different triplets so that the logs don't
conflict when building multiple at once.
## Examples
* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_execute\_build\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)

21
externals/vcpkg/docs/maintainers/vcpkg_execute_in_download_mode.md vendored Executable file
View File

@@ -0,0 +1,21 @@
# vcpkg_execute_in_download_mode
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_in_download_mode.md).
Execute a process even in download mode.
## Usage
```cmake
vcpkg_execute_in_download_mode(
...
)
```
The signature of this function is identical to `execute_process()`.
See [`execute_process()`] for more details.
[`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
## Source
[scripts/cmake/vcpkg\_execute\_in\_download\_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)

51
externals/vcpkg/docs/maintainers/vcpkg_execute_required_process.md vendored Executable file
View File

@@ -0,0 +1,51 @@
# vcpkg_execute_required_process
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_required_process.md).
Execute a process with logging and fail the build if the command fails.
## Usage
```cmake
vcpkg_execute_required_process(
COMMAND <${PERL}> [<arguments>...]
WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
LOGNAME <build-${TARGET_TRIPLET}-dbg>
[TIMEOUT <seconds>]
[OUTPUT_VARIABLE <var>]
[ERROR_VARIABLE <var>]
)
```
## Parameters
### ALLOW_IN_DOWNLOAD_MODE
Allows the command to execute in Download Mode.
[See execute_process() override](../../scripts/cmake/execute_process.cmake).
### COMMAND
The command to be executed, along with its arguments.
### WORKING_DIRECTORY
The directory to execute the command in.
### LOGNAME
The prefix to use for the log files.
### TIMEOUT
Optional timeout after which to terminate the command.
### OUTPUT_VARIABLE
Optional variable to receive stdout of the command.
### ERROR_VARIABLE
Optional variable to receive stderr of the command.
This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)

19
externals/vcpkg/docs/maintainers/vcpkg_execute_required_process_repeat.md vendored Executable file
View File

@@ -0,0 +1,19 @@
# vcpkg_execute_required_process_repeat
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_execute_required_process_repeat.md).
Execute a process until the command succeeds, or until the COUNT is reached.
## Usage
```cmake
vcpkg_execute_required_process_repeat(
COMMAND <cmd> [<arguments>]
COUNT <num>
WORKING_DIRECTORY <directory>
LOGNAME <name>
[ALLOW_IN_DOWNLOAD_MODE]
)
```
## Source
[scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)

86
externals/vcpkg/docs/maintainers/vcpkg_extract_source_archive.md vendored Executable file
View File

@@ -0,0 +1,86 @@
# vcpkg_extract_source_archive
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive.md).
Extract an archive into the source directory.
## Usage
There are two "overloads" of this function. The first is deprecated:
```cmake
vcpkg_extract_source_archive(<${ARCHIVE}> [<${TARGET_DIRECTORY}>])
```
This overload should not be used.
The latter is suggested to use for all future `vcpkg_extract_source_archive`s.
```cmake
vcpkg_extract_source_archive(<out-var>
ARCHIVE <path>
[NO_REMOVE_ONE_LEVEL]
[SKIP_PATCH_CHECK]
[PATCHES <patch>...]
[SOURCE_BASE <base>]
[BASE_DIRECTORY <relative-path> | WORKING_DIRECTORY <absolute-path>]
)
```
`vcpkg_extract_source_archive` takes an archive and extracts it.
It replaces existing uses of `vcpkg_extract_source_archive_ex`.
The simplest use of it is:
```cmake
vcpkg_download_distfile(archive ...)
vcpkg_extract_source_archive(source_path ARCHIVE "${archive}")
```
The general expectation is that an archives are laid out with a base directory,
and all the actual files underneath that directory; in other words, if you
extract the archive, you'll get something that looks like:
```
zlib-1.2.11/
doc/
...
examples/
...
ChangeLog
CMakeLists.txt
README
zlib.h
...
```
`vcpkg_extract_source_archive` automatically removes this directory,
and gives you the items under it directly. However, this only works
when there is exactly one item in the top level of an archive.
Otherwise, you'll have to pass the `NO_REMOVE_ONE_LEVEL` argument to
prevent `vcpkg_extract_source_archive` from performing this transformation.
If the source needs to be patched in some way, the `PATCHES` argument
allows one to do this, just like other `vcpkg_from_*` functions.
Additionally, the `SKIP_PATCH_CHECK` is provided for `--head` mode -
this allows patches to fail to apply silently.
This argument should _only_ be used when installing a `--head` library,
since otherwise we want a patch failing to appply to be a hard error.
`vcpkg_extract_source_archive` extracts the files to
`${CURRENT_BUILDTREES_DIR}/<base-directory>/<source-base>-<hash>.clean`.
When in editable mode, no `.clean` is appended,
to allow for a user to modify the sources.
`base-directory` defaults to `src`,
and `source-base` defaults to the stem of `<archive>`.
You can change these via the `BASE_DIRECTORY` and `SOURCE_BASE` arguments
respectively.
If you need to extract to a location that is not based in `CURRENT_BUILDTREES_DIR`,
you can use the `WORKING_DIRECTORY` argument to do the same.
## Examples
* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)

26
externals/vcpkg/docs/maintainers/vcpkg_extract_source_archive_ex.md vendored Executable file
View File

@@ -0,0 +1,26 @@
# vcpkg_extract_source_archive_ex
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_extract_source_archive_ex.md).
Extract an archive into the source directory.
Originally replaced [`vcpkg_extract_source_archive()`],
but new ports should instead use the second overload of
[`vcpkg_extract_source_archive()`].
## Usage
```cmake
vcpkg_extract_source_archive_ex(
[OUT_SOURCE_PATH <source_path>]
...
)
```
See the documentation for [`vcpkg_extract_source_archive()`] for other parameters.
Additionally, `vcpkg_extract_source_archive_ex()` adds the `REF` and `WORKING_DIRECTORY`
parameters, which are wrappers around `SOURCE_BASE` and `BASE_DIRECTORY`
respectively.
[`vcpkg_extract_source_archive()`]: vcpkg_extract_source_archive.md
## Source
[scripts/cmake/vcpkg\_extract\_source\_archive\_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)

45
externals/vcpkg/docs/maintainers/vcpkg_fail_port_install.md vendored Executable file
View File

@@ -0,0 +1,45 @@
# vcpkg_fail_port_install
**This function has been deprecated in favor of the `supports` field in [`manifest file`](manifest-files.md#supports) et al.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fail_port_install.md).
Checks common requirements and fails the current portfile with a (default) error message
## Usage
```cmake
vcpkg_fail_port_install(
[ALWAYS]
[MESSAGE <"Reason for failure">]
[ON_TARGET <Windows> [<OSX> ...]]
[ON_ARCH <x64> [<arm> ...]]
[ON_CRT_LINKAGE <static> [<dynamic> ...]])
[ON_LIBRARY_LINKAGE <static> [<dynamic> ...]]
)
```
## Parameters
### MESSAGE
Additional failure message. If none is given, a default message will be displayed depending on the failure condition.
### ALWAYS
Will always fail early
### ON_TARGET
Targets for which the build should fail early. Valid targets are `<target>` from `VCPKG_IS_TARGET_<target>` (see `vcpkg_common_definitions.cmake`).
### ON_ARCH
Architecture for which the build should fail early.
### ON_CRT_LINKAGE
CRT linkage for which the build should fail early.
### ON_LIBRARY_LINKAGE
Library linkage for which the build should fail early.
## Examples
* [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_fail\_port\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)

51
externals/vcpkg/docs/maintainers/vcpkg_find_acquire_program.md vendored Executable file
View File

@@ -0,0 +1,51 @@
# vcpkg_find_acquire_program
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_find_acquire_program.md).
Download or find a well-known tool.
## Usage
```cmake
vcpkg_find_acquire_program(<program>)
```
## Parameters
### program
This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
## Notes
The current list of programs includes:
* 7Z
* ARIA2 (Downloader)
* BISON
* CLANG
* DARK
* DOXYGEN
* FLEX
* GASPREPROCESSOR
* GPERF
* PERL
* PYTHON2
* PYTHON3
* GIT
* GN
* GO
* JOM
* MESON
* NASM
* NINJA
* NUGET
* SCONS
* SWIG
* YASM
Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
## Examples
* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_find\_acquire\_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)

25
externals/vcpkg/docs/maintainers/vcpkg_find_fortran.md vendored Executable file
View File

@@ -0,0 +1,25 @@
# vcpkg_find_fortran
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_find_fortran.md).
Checks if a Fortran compiler can be found.
Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran
and return required cmake args for building.
## Usage
```cmake
vcpkg_find_fortran(<out_var>)
```
## Example
```cmake
vcpkg_find_fortran(fortran_args)
# ...
vcpkg_cmake_configure(...
OPTIONS
${fortran_args}
)
```
## Source
[scripts/cmake/vcpkg\_find\_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake)

62
externals/vcpkg/docs/maintainers/vcpkg_fixup_cmake_targets.md vendored Executable file
View File

@@ -0,0 +1,62 @@
# vcpkg_fixup_cmake_targets
**This function has been deprecated in favor of [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md) from the vcpkg-cmake-config port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_cmake_targets.md).
Merge release and debug CMake targets and configs to support multiconfig generators.
Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
## Usage
```cmake
vcpkg_fixup_cmake_targets([CONFIG_PATH <share/${PORT}>]
[TARGET_PATH <share/${PORT}>]
[TOOLS_PATH <tools/${PORT}>]
[DO_NOT_DELETE_PARENT_CONFIG_PATH])
```
## Parameters
### CONFIG_PATH
Subpath currently containing `*.cmake` files subdirectory (like `lib/cmake/${PORT}`). Should be relative to `${CURRENT_PACKAGES_DIR}`.
Defaults to `share/${PORT}`.
### TARGET_PATH
Subpath to which the above `*.cmake` files should be moved. Should be relative to `${CURRENT_PACKAGES_DIR}`.
This needs to be specified if the port name differs from the `find_package()` name.
Defaults to `share/${PORT}`.
### DO_NOT_DELETE_PARENT_CONFIG_PATH
By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
Passing this option disable such behavior, as it is convenient for ports that install
more than one CMake package configuration file.
### NO_PREFIX_CORRECTION
Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets.
Currently the correction does not take into account how the files are moved and applies
I rather simply correction which in some cases will yield the wrong results.
### TOOLS_PATH
Define the base path to tools. Default: `tools/<PORT>`
## Notes
Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.
Transform all references matching `/bin/*.exe` to `/${TOOLS_PATH}/*.exe` on Windows.
Transform all references matching `/bin/*` to `/${TOOLS_PATH}/*` on other platforms.
Fix `${_IMPORT_PREFIX}` in auto generated targets to be one folder deeper.
Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
## Examples
* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_fixup\_cmake\_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)

49
externals/vcpkg/docs/maintainers/vcpkg_fixup_pkgconfig.md vendored Executable file
View File

@@ -0,0 +1,49 @@
# vcpkg_fixup_pkgconfig
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_pkgconfig.md).
Fix common paths in *.pc files and make everything relative to $(prefix).
Additionally, on static triplets, private entries are merged with their non-private counterparts,
allowing pkg-config to be called without the ``--static`` flag.
Note that vcpkg is designed to never have to call pkg-config with the ``--static`` flag,
since a consumer cannot know if a dependent library has been built statically or not.
## Usage
```cmake
vcpkg_fixup_pkgconfig(
[RELEASE_FILES <PATHS>...]
[DEBUG_FILES <PATHS>...]
[SKIP_CHECK]
)
```
## Parameters
### RELEASE_FILES
Specifies a list of files to apply the fixes for release paths.
Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR} without ${CURRENT_PACKAGES_DIR}/debug/
### DEBUG_FILES
Specifies a list of files to apply the fixes for debug paths.
Defaults to every *.pc file in the folder ${CURRENT_PACKAGES_DIR}/debug/
### SKIP_CHECK
Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself has unhandled cases.
### SYSTEM_PACKAGES (deprecated)
This argument has been deprecated and has no effect.
### SYSTEM_LIBRARIES (deprecated)
This argument has been deprecated and has no effect.
### IGNORE_FLAGS (deprecated)
This argument has been deprecated and has no effect.
## Notes
Still work in progress. If there are more cases which can be handled here feel free to add them
## Examples
* [brotli](https://github.com/Microsoft/vcpkg/blob/master/ports/brotli/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_fixup\_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)

60
externals/vcpkg/docs/maintainers/vcpkg_from_bitbucket.md vendored Executable file
View File

@@ -0,0 +1,60 @@
# vcpkg_from_bitbucket
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_bitbucket.md).
Download and extract a project from Bitbucket.
## Usage:
```cmake
vcpkg_from_bitbucket(
OUT_SOURCE_PATH <SOURCE_PATH>
REPO <Microsoft/cpprestsdk>
[REF <v2.0.0>]
[SHA512 <45d0d7f8cc350...>]
[HEAD_REF <master>]
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## Parameters:
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### REPO
The organization or user and repository on GitHub.
### REF
A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
For repositories without official releases, this can be set to the full commit id of the current latest master.
If `REF` is specified, `SHA512` must also be specified.
### SHA512
The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz).
This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
### HEAD_REF
The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
This exports the `VCPKG_HEAD_VERSION` variable during head builds.
## Examples:
* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_from\_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)

53
externals/vcpkg/docs/maintainers/vcpkg_from_git.md vendored Executable file
View File

@@ -0,0 +1,53 @@
# vcpkg_from_git
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_git.md).
Download and extract a project from git
## Usage:
```cmake
vcpkg_from_git(
OUT_SOURCE_PATH <SOURCE_PATH>
URL <https://android.googlesource.com/platform/external/fdlibm>
REF <59f7335e4d...>
[HEAD_REF <ref>]
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## Parameters:
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### URL
The url of the git repository.
### REF
The git sha of the commit to download.
### FETCH_REF
The git branch to fetch in non-HEAD mode. After this is fetched,
then `REF` is checked out. This is useful in cases where the git server
does not allow checking out non-advertised objects.
### HEAD_REF
The git branch to use when the package is requested to be built from the latest sources.
Example: `main`, `develop`, `HEAD`
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
## Notes:
`OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
## Examples:
* [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_from\_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)

78
externals/vcpkg/docs/maintainers/vcpkg_from_github.md vendored Executable file
View File

@@ -0,0 +1,78 @@
# vcpkg_from_github
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_github.md).
Download and extract a project from GitHub. Enables support for `install --head`.
This also works with Gitea by specifying the Gitea server with the `GITHUB_HOST` option.
## Usage:
```cmake
vcpkg_from_github(
OUT_SOURCE_PATH <SOURCE_PATH>
REPO <Microsoft/cpprestsdk>
[REF <v2.0.0>]
[SHA512 <45d0d7f8cc350...>]
[HEAD_REF <master>]
[PATCHES <patch1.patch> <patch2.patch>...]
[GITHUB_HOST <https://github.com>]
[AUTHORIZATION_TOKEN <${SECRET_FROM_FILE}>]
[FILE_DISAMBIGUATOR <N>]
)
```
## Parameters:
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### REPO
The organization or user and repository on GitHub.
### REF
A stable git commit-ish (ideally a tag or commit) that will not change contents. **This should not be a branch.**
For repositories without official releases, this can be set to the full commit id of the current latest master.
If `REF` is specified, `SHA512` must also be specified.
### SHA512
The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
### HEAD_REF
The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
### GITHUB_HOST
A replacement host for enterprise GitHub instances.
This field should contain the scheme, host, and port of the desired URL without a trailing slash.
### AUTHORIZATION_TOKEN
A token to be passed via the Authorization HTTP header as "token ${AUTHORIZATION_TOKEN}".
### FILE_DISAMBIGUATOR
A token to uniquely identify the resulting filename if the SHA512 changes even though a git ref does not, to avoid stepping on the same file name.
## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
This exports the `VCPKG_HEAD_VERSION` variable during head builds.
## Examples:
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
* [boost-beast](https://github.com/Microsoft/vcpkg/blob/master/ports/boost-beast/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_from\_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)

71
externals/vcpkg/docs/maintainers/vcpkg_from_gitlab.md vendored Executable file
View File

@@ -0,0 +1,71 @@
# vcpkg_from_gitlab
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_gitlab.md).
Download and extract a project from Gitlab instances. Enables support for `install --head`.
## Usage:
```cmake
vcpkg_from_gitlab(
GITLAB_URL <https://gitlab.com>
OUT_SOURCE_PATH <SOURCE_PATH>
REPO <gitlab-org/gitlab-ce>
[REF <v10.7.3>]
[SHA512 <45d0d7f8cc350...>]
[HEAD_REF <master>]
[PATCHES <patch1.patch> <patch2.patch>...]
[FILE_DISAMBIGUATOR <N>]
)
```
## Parameters:
### GITLAB_URL
The URL of the Gitlab instance to use.
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### REPO
The organization or user plus the repository name on the Gitlab instance.
### REF
A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.**
For repositories without official releases, this can be set to the full commit id of the current latest master.
If `REF` is specified, `SHA512` must also be specified.
### SHA512
The SHA512 hash that should match the archive (${GITLAB_URL}/${REPO}/-/archive/${REF}/${REPO_NAME}-${REF}.tar.gz).
The REPO_NAME variable is parsed from the value of REPO.
This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
### HEAD_REF
The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
### FILE_DISAMBIGUATOR
A token to uniquely identify the resulting filename if the SHA512 changes even though a git ref does not, to avoid stepping on the same file name.
## Notes:
At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present.
This exports the `VCPKG_HEAD_VERSION` variable during head builds.
## Examples:
* [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
* [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
* [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
## Source
[scripts/cmake/vcpkg\_from\_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)

73
externals/vcpkg/docs/maintainers/vcpkg_from_sourceforge.md vendored Executable file
View File

@@ -0,0 +1,73 @@
# vcpkg_from_sourceforge
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_from_sourceforge.md).
Download and extract a project from sourceforge.
This function automatically checks a set of sourceforge mirrors.
Additional mirrors can be injected through the `VCPKG_SOURCEFORGE_EXTRA_MIRRORS`
list variable in the triplet.
## Usage:
```cmake
vcpkg_from_sourceforge(
OUT_SOURCE_PATH SOURCE_PATH
REPO <cunit/CUnit>
[REF <2.1-3>]
SHA512 <547b417109332...>
FILENAME <CUnit-2.1-3.tar.bz2>
[DISABLE_SSL]
[NO_REMOVE_ONE_LEVEL]
[PATCHES <patch1.patch> <patch2.patch>...]
)
```
## Parameters:
### OUT_SOURCE_PATH
Specifies the out-variable that will contain the extracted location.
This should be set to `SOURCE_PATH` by convention.
### REPO
The organization or user and repository (optional) on sourceforge.
### REF
A stable version number that will not change contents.
### FILENAME
The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
For example, we can get the download link:
https://sourceforge.net/settings/mirror_choices?projectname=mad&filename=libmad/0.15.1b/libmad-0.15.1b.tar.gz&selected=nchc
So the REPO is `mad/libmad`, the REF is `0.15.1b`, and the FILENAME is `libmad-0.15.1b.tar.gz`
For some special links:
https://sourceforge.net/settings/mirror_choices?projectname=soxr&filename=soxr-0.1.3-Source.tar.xz&selected=nchc
The REPO is `soxr`, REF is not exist, and the FILENAME is `soxr-0.1.3-Source.tar.xz`
### SHA512
The SHA512 hash that should match the archive.
This is most easily determined by first setting it to `0`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
### WORKING_DIRECTORY
If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`).
### PATCHES
A list of patches to be applied to the extracted sources.
Relative paths are based on the port directory.
### NO_REMOVE_ONE_LEVEL
Specifies that the default removal of the top level folder should not occur.
## Examples:
* [cunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cunit/portfile.cmake)
* [polyclipping](https://github.com/Microsoft/vcpkg/blob/master/ports/polyclipping/portfile.cmake)
* [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_from\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)

15
externals/vcpkg/docs/maintainers/vcpkg_get_program_files_platform_bitness.md vendored Executable file
View File

@@ -0,0 +1,15 @@
# vcpkg_get_program_files_platform_bitness
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_get_program_files_platform_bitness.md).
Get the Program Files directory of the current platform's bitness:
either `$ENV{ProgramW6432}` on 64-bit windows,
or `$ENV{PROGRAMFILES}` on 32-bit windows.
## Usage:
```cmake
vcpkg_get_program_files_platform_bitness(<variable>)
```
## Source
[scripts/cmake/vcpkg\_get\_program\_files\_platform\_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)

13
externals/vcpkg/docs/maintainers/vcpkg_get_windows_sdk.md vendored Executable file
View File

@@ -0,0 +1,13 @@
# vcpkg_get_windows_sdk
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_get_windows_sdk.md).
Get the Windows SDK number.
## Usage:
```cmake
vcpkg_get_windows_sdk(<variable>)
```
## Source
[scripts/cmake/vcpkg\_get\_windows\_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)

29
externals/vcpkg/docs/maintainers/vcpkg_host_path_list.md vendored Executable file
View File

@@ -0,0 +1,29 @@
# vcpkg_host_path_list
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_host_path_list.md).
Modify a host path list variable (PATH, INCLUDE, LIBPATH, etc.)
```cmake
vcpkg_host_path_list(PREPEND <list-var> [<path>...])
vcpkg_host_path_list(APPEND <list-var> [<path>...])
vcpkg_host_path_list(SET <list-var> [<path>...])
```
`<list-var>` may be either a regular variable name, or `ENV{variable-name}`,
in which case `vcpkg_host_path_list` will modify the environment.
`vcpkg_host_path_list` adds all of the paths passed to it to `<list-var>`;
`PREPEND` puts them before the existing list, so that they are searched first;
`APPEND` places them after the existing list,
so they would be searched after the paths which are already in the variable,
and `SET` replaces the value of the existing list.
For all of `APPEND`, `PREPEND`, and `SET`,
the paths are added (and thus searched) in the order received.
If no paths are passed to `APPEND` or `PREPEND`, nothing will be done;
for `SET`, the variable will be set to the empty string.
## Source
[scripts/cmake/vcpkg\_host\_path\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_host_path_list.cmake)

29
externals/vcpkg/docs/maintainers/vcpkg_install_cmake.md vendored Executable file
View File

@@ -0,0 +1,29 @@
# vcpkg_install_cmake
**This function has been deprecated in favor of [`vcpkg_cmake_install`](ports/vcpkg-cmake/vcpkg_cmake_install.md) from the vcpkg-cmake port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md).
Build and install a cmake project.
## Usage:
```cmake
vcpkg_install_cmake(...)
```
## Parameters:
See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md).
## Notes:
This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install`
parameter.
## Examples:
* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_install\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)

31
externals/vcpkg/docs/maintainers/vcpkg_install_gn.md vendored Executable file
View File

@@ -0,0 +1,31 @@
# vcpkg_install_gn
**This function has been deprecated in favor of [`vcpkg_gn_install`](ports/vcpkg-gn/vcpkg_gn_install.md) from the vcpkg-gn port.**
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_gn.md).
Installs a GN project.
In order to build a GN project without installing, use [`vcpkg_build_ninja()`].
## Usage:
```cmake
vcpkg_install_gn(
SOURCE_PATH <SOURCE_PATH>
[TARGETS <target>...]
)
```
## Parameters:
### SOURCE_PATH
The path to the source directory
### TARGETS
Only install the specified targets.
Note: includes must be handled separately
[`vcpkg_build_ninja()`]: vcpkg_build_ninja.md
## Source
[scripts/cmake/vcpkg\_install\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)

26
externals/vcpkg/docs/maintainers/vcpkg_install_make.md vendored Executable file
View File

@@ -0,0 +1,26 @@
# vcpkg_install_make
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_make.md).
Build and install a make project.
## Usage:
```cmake
vcpkg_install_make(...)
```
## Parameters:
See [`vcpkg_build_make()`](vcpkg_build_make.md).
## Notes:
This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.md), adding `ENABLE_INSTALL`
## Examples
* [x264](https://github.com/Microsoft/vcpkg/blob/master/ports/x264/portfile.cmake)
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
* [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_install\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)

22
externals/vcpkg/docs/maintainers/vcpkg_install_meson.md vendored Executable file
View File

@@ -0,0 +1,22 @@
# vcpkg_install_meson
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_meson.md).
Builds a meson project previously configured with `vcpkg_configure_meson()`.
## Usage
```cmake
vcpkg_install_meson([ADD_BIN_TO_PATH])
```
## Parameters:
### ADD_BIN_TO_PATH
Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs.
## Examples
* [fribidi](https://github.com/Microsoft/vcpkg/blob/master/ports/fribidi/portfile.cmake)
* [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_install\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)

95
externals/vcpkg/docs/maintainers/vcpkg_install_msbuild.md vendored Executable file
View File

@@ -0,0 +1,95 @@
# vcpkg_install_msbuild
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_msbuild.md).
Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
## Usage
```cmake
vcpkg_install_msbuild(
SOURCE_PATH <${SOURCE_PATH}>
PROJECT_SUBPATH <port.sln>
[INCLUDES_SUBPATH <include>]
[LICENSE_SUBPATH <LICENSE>]
[RELEASE_CONFIGURATION <Release>]
[DEBUG_CONFIGURATION <Debug>]
[TARGET <Build>]
[TARGET_PLATFORM_VERSION <10.0.15063.0>]
[PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
[PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
[OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
[OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
[OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
[USE_VCPKG_INTEGRATION]
[ALLOW_ROOT_INCLUDES | REMOVE_ROOT_INCLUDES]
)
```
## Parameters
### SOURCE_PATH
The path to the root of the source tree.
Because MSBuild uses in-source builds, the source tree will be copied into a temporary location for the build. This
parameter is the base for that copy and forms the base for all XYZ_SUBPATH options.
### USE_VCPKG_INTEGRATION
Apply the normal `integrate install` integration for building the project.
By default, projects built with this command will not automatically link libraries or have header paths set.
### PROJECT_SUBPATH
The subpath to the solution (`.sln`) or project (`.vcxproj`) file relative to `SOURCE_PATH`.
### LICENSE_SUBPATH
The subpath to the license file relative to `SOURCE_PATH`.
### INCLUDES_SUBPATH
The subpath to the includes directory relative to `SOURCE_PATH`.
This parameter should be a directory and should not end in a trailing slash.
### ALLOW_ROOT_INCLUDES
Indicates that top-level include files (e.g. `include/zlib.h`) should be allowed.
### REMOVE_ROOT_INCLUDES
Indicates that top-level include files (e.g. `include/Makefile.am`) should be removed.
### SKIP_CLEAN
Indicates that the intermediate files should not be removed.
Ports using this option should later call [`vcpkg_clean_msbuild()`](vcpkg_clean_msbuild.md) to manually clean up.
### RELEASE_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
### DEBUG_CONFIGURATION
The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
### TARGET_PLATFORM_VERSION
The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
### TARGET
The MSBuild target to build. (``/t:<TARGET>``)
### PLATFORM
The platform (``/p:Platform`` msbuild parameter) used for the build.
### PLATFORM_TOOLSET
The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
### OPTIONS
Additional options passed to msbuild for all builds.
### OPTIONS_RELEASE
Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
## Examples
* [libirecovery](https://github.com/Microsoft/vcpkg/blob/master/ports/libirecovery/portfile.cmake)
* [libfabric](https://github.com/Microsoft/vcpkg/blob/master/ports/libfabric/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_install\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)

68
externals/vcpkg/docs/maintainers/vcpkg_install_nmake.md vendored Executable file
View File

@@ -0,0 +1,68 @@
# vcpkg_install_nmake
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_nmake.md).
Build and install a msvc makefile project.
## Usage:
```cmake
vcpkg_install_nmake(
SOURCE_PATH <${SOURCE_PATH}>
[NO_DEBUG]
[TARGET <all>]
PROJECT_SUBPATH <${SUBPATH}>
PROJECT_NAME <${MAKEFILE_NAME}>
[PRERUN_SHELL <${SHELL_PATH}>]
[PRERUN_SHELL_DEBUG <${SHELL_PATH}>]
[PRERUN_SHELL_RELEASE <${SHELL_PATH}>]
[OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
[OPTIONS_RELEASE <-DOPTIMIZE=1>...]
[OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the source files.
By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
### PROJECT_SUBPATH
Specifies the sub directory containing the `makefile.vc`/`makefile.mak`/`makefile.msvc` or other msvc makefile.
### PROJECT_NAME
Specifies the name of msvc makefile name.
Default is makefile.vc
### NO_DEBUG
This port doesn't support debug mode.
### PRERUN_SHELL
Script that needs to be called before build
### PRERUN_SHELL_DEBUG
Script that needs to be called before debug build
### PRERUN_SHELL_RELEASE
Script that needs to be called before release build
### OPTIONS
Additional options passed to generate during the generation.
### OPTIONS_RELEASE
Additional options passed to generate during the Release generation. These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options passed to generate during the Debug generation. These are in addition to `OPTIONS`.
## Parameters:
See [`vcpkg_build_nmake()`](vcpkg_build_nmake.md).
## Notes:
This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake.md), adding `ENABLE_INSTALL`
## Examples
* [tcl](https://github.com/Microsoft/vcpkg/blob/master/ports/tcl/portfile.cmake)
* [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_install\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)

26
externals/vcpkg/docs/maintainers/vcpkg_install_qmake.md vendored Executable file
View File

@@ -0,0 +1,26 @@
# vcpkg_install_qmake
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_qmake.md).
Build and install a qmake project.
## Usage:
```cmake
vcpkg_install_qmake(...)
```
## Parameters:
See [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
## Notes:
This command transparently forwards to [`vcpkg_build_qmake()`](vcpkg_build_qmake.md).
Additionally, this command will copy produced .libs/.dlls/.as/.dylibs/.sos to the appropriate
staging directories.
## Examples
* [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
## Source
[scripts/cmake/vcpkg\_install\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)

94
externals/vcpkg/docs/maintainers/vcpkg_list.md vendored Executable file
View File

@@ -0,0 +1,94 @@
# vcpkg_list
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_list.md).
A replacement for CMake's `list()` function, which correctly handles elements
with internal semicolons (in other words, escaped semicolons).
Use `vcpkg_list()` instead of `list()` whenever possible.
```cmake
vcpkg_list(SET <out-var> [<element>...])
vcpkg_list(<COMMAND> <list-var> [<other-arguments>...])
```
In addition to all of the commands from `list()`, `vcpkg_list` adds
a `vcpkg_list(SET)` command.
This command takes its arguments, escapes them, and then concatenates
them into a list; this should be used instead of `set()` for setting any
list variable.
Otherwise, the `vcpkg_list()` function is the same as the built-in
`list()` function, with the following restrictions:
- `GET`, `REMOVE_ITEM`, and `REMOVE_AT` support only one index/value
- `POP_BACK` and `POP_FRONT` do not support getting the value into
another out variable. Use C++ style `GET` then `POP_(BACK|FRONT)`.
- `FILTER` and `TRANSFORM` are unsupported.
See the [CMake documentation for `list()`](https://cmake.org/cmake/help/latest/command/list.html)
for more information.
## Notes: Some Weirdnesses
The most major weirdness is due to `""` pulling double-duty as "list of zero elements",
and "list of one element, which is empty". `vcpkg_list` always uses the former understanding.
This can cause weird behavior, for example:
```cmake
set(lst "")
vcpkg_list(APPEND lst "" "")
# lst = ";"
```
This is because you're appending two elements to the empty list.
One very weird behavior that comes out of this would be:
```cmake
set(lst "")
vcpkg_list(APPEND lst "")
# lst = ""
```
since `""` is the empty list, we append the empty element and end up with a list
of one element, which is empty. This does not happen for non-empty lists;
for example:
```cmake
set(lst "a")
vcpkg_list(APPEND lst "")
# lst = "a;"
```
only the empty list has this odd behavior.
## Examples
### Creating a list
```cmake
vcpkg_list(SET foo_param)
if(DEFINED arg_FOO)
vcpkg_list(SET foo_param FOO "${arg_FOO}")
endif()
```
### Appending to a list
```cmake
set(OPTIONS -DFOO=BAR)
if(VCPKG_TARGET_IS_WINDOWS)
vcpkg_list(APPEND OPTIONS "-DOS=WINDOWS;FOO")
endif()
```
### Popping the end off a list
```cmake
if(NOT list STREQUAL "")
vcpkg_list(GET list end -1)
vcpkg_list(POP_BACK list)
endif()
```
## Source
[scripts/cmake/vcpkg\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_list.cmake)

17
externals/vcpkg/docs/maintainers/vcpkg_minimum_required.md vendored Executable file
View File

@@ -0,0 +1,17 @@
# vcpkg_minimum_required
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_minimum_required.md).
Asserts that the version of the vcpkg program being used to build a port is later than the supplied date, inclusive.
## Usage
```cmake
vcpkg_minimum_required(VERSION 2021-01-13)
```
## Parameters
### VERSION
The date-version to check against.
## Source
[scripts/cmake/vcpkg\_minimum\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake)

12
externals/vcpkg/docs/maintainers/vcpkg_replace_string.md vendored Executable file
View File

@@ -0,0 +1,12 @@
# vcpkg_replace_string
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_replace_string.md).
Replace a string in a file.
```cmake
vcpkg_replace_string(<filename> <match> <replace>)
```
## Source
[scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)