mirror/vcpkg
1
0
Fork 0
mirror of https://github.com/microsoft/vcpkg.git synced 2024-11-24 03:00:19 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

[docs] Rewrite doc for vcpkg_cmake_configure. Move up into docs/maintainers/. (#25255)

Browse Source 
* [docs] Rewrite doc for vcpkg_cmake_configure. Move up into docs/maintainers/.

* [docs] CR

* PR comment
This commit is contained in:
Robert Schumacher 2022-06-29 07:09:02 -07:00 committed by GitHub
parent 4a7ba299f6
commit 3f71620c2b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 146 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/examples/packaging-github-repos.md
View File

@ -37,7 +37,7 @@ vcpkg_cmake_install()
file(INSTALL "${SOURCE_PATH}/COPYING" DESTINATION "${CURRENT_PACKAGES_DIR}/share/libogg" RENAME copyright)
```
Check the documentation for [`vcpkg_cmake_configure`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md) if your package needs additional options.
Check the documentation for [`vcpkg_cmake_configure`](../maintainers/vcpkg_cmake_configure.md) and [`vcpkg_cmake_install`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md) if your package needs additional options.
Now you can run `vcpkg install libogg` to build and install the package.

6
docs/maintainers/maintainer-guide.md
View File

@ -47,9 +47,9 @@ At this time, the following helpers are deprecated:
- `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))
- `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)
- `vcpkg_copy_tool_dependencies()` should be replaced by [`vcpkg_copy_tools()`](vcpkg_copy_tools.md)
- `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))
- `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))
- `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))
- `vcpkg_configure_cmake` should be replaced by [`vcpkg_cmake_configure()`](vcpkg_cmake_configure.md) after removing `PREFER_NINJA` (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md))
- `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_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_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

4
docs/maintainers/portfile-functions.md
View File

@ -18,7 +18,7 @@
- [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\_cmake](vcpkg_configure_cmake.md) (deprecated, use [vcpkg\_cmake\_configure](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)
@ -71,7 +71,7 @@
### [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\_configure](vcpkg_cmake_configure.md)
- [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
### [vcpkg-gn](ports/vcpkg-gn.md)

8
docs/maintainers/ports/vcpkg-cmake.md
View File

@ -1,7 +1,7 @@
# vcpkg-cmake
This port contains cmake functions for dealing with a CMake buildsystem.
This port contains portfile helper 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.
- [`vcpkg_cmake_configure()`](../vcpkg_cmake_configure.md)
- [`vcpkg_cmake_install()`](vcpkg-cmake/vcpkg_cmake_install.md)
- [`vcpkg_cmake_build()`](vcpkg-cmake/vcpkg_cmake_build.md)

93
docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md
View File

@ -1,93 +0,0 @@
# 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)

134
docs/maintainers/vcpkg_cmake_configure.md Normal file
View File

@ -0,0 +1,134 @@
# vcpkg_cmake_configure
The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_configure.md).
Configure a CMake-based project.
This command replaces [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
## Usage
```cmake
vcpkg_cmake_configure(
SOURCE_PATH <source-path>
[DISABLE_PARALLEL_CONFIGURE]
[NO_CHARSET_FLAG]
[WINDOWS_USE_MSBUILD]
[GENERATOR <generator>]
[LOGFILE_BASE <logname-base>]
[OPTIONS
<configure-setting>...]
[OPTIONS_RELEASE
<configure-setting>...]
[OPTIONS_DEBUG
<configure-setting>...]
[MAYBE_UNUSED_VARIABLES
<option-name>...]
)
```
To use this function, you must depend on the helper port [`vcpkg-cmake`](ports/vcpkg-cmake.md):
```no-highlight
"dependencies": [
{
"name": "vcpkg-cmake",
"host": true
}
]
```
## Parameters
### SOURCE_PATH
Specifies the directory containing the `CMakeLists.txt`.
This value is usually obtained as a result of calling a source acquisition command like [`vcpkg_from_github()`](vcpkg_from_github.md).
### DISABLE_PARALLEL_CONFIGURE
Disables running the CMake configure step in parallel.
By default vcpkg disables writing back to the source directory (via the undocumented CMake flag `CMAKE_DISABLE_SOURCE_CHANGES`) and (on Windows) configures Release and Debug in parallel. This flag instructs vcpkg to allow source directory writes and to execute the configure steps sequentially.
### NO_CHARSET_FLAG
Disables passing `/utf-8` when using the [built-in Windows toolchain][VCPKG_CHAINLOAD_TOOLCHAIN_FILE].
This is needed for libraries that set their own source code's character set when targeting MSVC. See the [MSVC documentation for `/utf-8`](https://docs.microsoft.com/cpp/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8) for more information.
### WINDOWS_USE_MSBUILD
Use MSBuild instead of [Ninja][ninja] when targeting a Windows platform.
By default vcpkg prefers to use Ninja as the CMake Generator for all platforms. However, there are edge cases where MSBuild has different behavior than Ninja. This flag should only be passed if the project requires MSBuild to build correctly.
### GENERATOR
Specifies the Generator to use.
This is useful if the 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 `"Ninja"`.
This should not be passed alongside [`WINDOWS_USE_MSBUILD`](#windows_use_msbuild).
### LOGFILE_BASE
An alternate root name for the configure logs.
Defaults to `config-${TARGET_TRIPLET}`. It should not contain any path separators. Logs will be generated matching the pattern `${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-<suffix>.log`
### OPTIONS
Additional options to pass to CMake during the configuration.
See also [Implicit Options](#implicit-options).
### OPTIONS_RELEASE
Additional options to pass to CMake during the Release configuration.
These are in addition to `OPTIONS`.
### OPTIONS_DEBUG
Additional options to pass to CMake during the Debug configuration.
These are in addition to `OPTIONS`.
### MAYBE_UNUSED_VARIABLES
List of CMake options that may not be read during the configure step.
vcpkg will warn about any options outside this list that were not read during the CMake configure step. This list should contain options that are only read during certain configurations (such as when `VCPKG_LIBRARY_LINKAGE` is `"static"` or when certain features are enabled).
## Implicit Options
This command automatically provides several options to CMake.
- [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) is set to `"Release"` or `"Debug"` as appropriate.
- [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) is set according to the value of [`VCPKG_LIBRARY_LINKAGE`](../users/triplets.md#vcpkg_library_linkage).
- [`CMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}</debug>`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) as appropriate to the configuration
- [`CMAKE_TOOLCHAIN_FILE`](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html) and `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` are set to include the [vcpkg toolchain file](../users/buildsystems/cmake-integration.md#cmake_toolchain_file) and the [triplet toolchain][VCPKG_CHAINLOAD_TOOLCHAIN_FILE].
- [`CMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}`](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_NAME.html). If `VCPKG_CMAKE_SYSTEM_NAME` is unset, defaults to `"Windows"`.
- [`CMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION}`](https://cmake.org/cmake/help/latest/variable/CMAKE_SYSTEM_VERSION.html) if `VCPKG_CMAKE_SYSTEM_VERSION` is set.
- [`CMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.html)
- [`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.html)
- [`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.html)
- [`CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=TRUE`](https://cmake.org/cmake/help/latest/module/InstallRequiredSystemLibraries.html)
- [`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION=ON`](https://cmake.org/cmake/help/latest/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.html)
- [`CMAKE_INSTALL_LIBDIR:STRING=lib`](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html)
- [`CMAKE_INSTALL_BINDIR:STRING=bin`](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html)
This command also passes all options in [`VCPKG_CMAKE_CONFIGURE_OPTIONS`](../users/triplets.md#vcpkg_cmake_configure_options) and the configuration-specific options from `VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE` or `VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG`.
Finally, there are additional internal options passed in (with a `VCPKG_` prefix) that should not be depended upon.
## Examples
```cmake
vcpkg_from_github(OUT_SOURCE_PATH source_path ...)
vcpkg_cmake_configure(
SOURCE_PATH "${source_path}"
OPTIONS
-DBUILD_EXAMPLES=OFF
-DBUILD_TESTS=OFF
)
vcpkg_cmake_install()
```
[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_configure+path%3A%2Fports)
## Source
[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)
[ninja]: https://ninja-build.org/
[VCPKG_CHAINLOAD_TOOLCHAIN_FILE]: ../users/triplets.md#VCPKG_CHAINLOAD_TOOLCHAIN_FILE

2
docs/maintainers/vcpkg_configure_cmake.md
View File

@ -1,6 +1,6 @@
# 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.**
**This function has been deprecated in favor of [`vcpkg_cmake_configure`](vcpkg_cmake_configure.md) from the [`vcpkg-cmake`](ports/vcpkg-cmake.md) 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).

2
docs/users/triplets.md
View File

@ -94,7 +94,7 @@ This option also has forms for configuration-specific flags:
- `VCPKG_LINKER_FLAGS_RELEASE`
### VCPKG_CMAKE_CONFIGURE_OPTIONS
Set additional CMake configure options that are appended to the configure command (in [`vcpkg_cmake_configure`](../maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md)).
Set additional CMake configure options that are appended to the configure command (in [`vcpkg_cmake_configure`](../maintainers/vcpkg_cmake_configure.md)).
This field is optional.