early-access version 2853

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-config.md

@@ -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.

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-get-vars.md

@@ -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

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake-get-vars/vcpkg_cmake_get_vars.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake.md

@@ -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.

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-get-python-packages.md

@@ -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. 

externals/vcpkg/docs/maintainers/ports/vcpkg-get-python-packages/x_vcpkg_get_python_packages.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-gn.md

@@ -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()
+```

externals/vcpkg/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_configure.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-gn/vcpkg_gn_install.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-pkgconfig-get-modules.md

@@ -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.

externals/vcpkg/docs/maintainers/ports/vcpkg-pkgconfig-get-modules/x_vcpkg_pkgconfig_get_modules.md

@@ -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)

externals/vcpkg/docs/maintainers/ports/vcpkg-qmake.md

@@ -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.
+

externals/vcpkg/docs/maintainers/ports/vcpkg-qmake/vcpkg_qmake_configure.md

@@ -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)