diff --git a/docs/examples/packaging-github-repos.md b/docs/examples/packaging-github-repos.md index f85a4b1fdb..769f75455f 100644 --- a/docs/examples/packaging-github-repos.md +++ b/docs/examples/packaging-github-repos.md @@ -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/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/vcpkg_cmake_install.md) if your package needs additional options. Now you can run `vcpkg install libogg` to build and install the package. diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md index 5aed050e24..d02da50546 100644 --- a/docs/maintainers/maintainer-guide.md +++ b/docs/maintainers/maintainer-guide.md @@ -48,8 +48,8 @@ At this time, the following helpers are deprecated: - `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()`](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_build_cmake` should be replaced by [`vcpkg_cmake_build()`](vcpkg_cmake_build.md) (from port [`vcpkg-cmake`](ports/vcpkg-cmake.md)) +- `vcpkg_install_cmake` should be replaced by [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) (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 diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index ec6fb536c9..60beddb790 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -1,12 +1,10 @@ - - # 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\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](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) @@ -46,7 +44,7 @@ - [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\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](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\_copyright](vcpkg_install_copyright.md) - [vcpkg\_install\_make](vcpkg_install_make.md) @@ -71,9 +69,9 @@ ### [vcpkg-cmake](ports/vcpkg-cmake.md) -- [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md) +- [vcpkg\_cmake\_build](vcpkg_cmake_build.md) - [vcpkg\_cmake\_configure](vcpkg_cmake_configure.md) -- [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md) +- [vcpkg\_cmake\_install](vcpkg_cmake_install.md) ### [vcpkg-gn](ports/vcpkg-gn.md) diff --git a/docs/maintainers/ports/vcpkg-cmake.md b/docs/maintainers/ports/vcpkg-cmake.md index 7566ee0299..52f6c1fcd4 100644 --- a/docs/maintainers/ports/vcpkg-cmake.md +++ b/docs/maintainers/ports/vcpkg-cmake.md @@ -3,5 +3,5 @@ This port contains portfile helper functions for dealing with a CMake buildsystem. - [`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) +- [`vcpkg_cmake_install()`](../vcpkg_cmake_install.md) +- [`vcpkg_cmake_build()`](../vcpkg_cmake_build.md) diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md deleted file mode 100644 index b8f9c3b8ab..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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 ] - [LOGFILE_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) diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md deleted file mode 100644 index 1d708d3a13..0000000000 --- a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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) diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md index 485a8c9184..4163c6cc86 100644 --- a/docs/maintainers/vcpkg_build_cmake.md +++ b/docs/maintainers/vcpkg_build_cmake.md @@ -1,6 +1,6 @@ # 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.** +**This function has been deprecated in favor of [`vcpkg_cmake_build`](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). diff --git a/docs/maintainers/vcpkg_cmake_build.md b/docs/maintainers/vcpkg_cmake_build.md new file mode 100644 index 0000000000..047290ec16 --- /dev/null +++ b/docs/maintainers/vcpkg_cmake_build.md @@ -0,0 +1,68 @@ +# vcpkg_cmake_build + +**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_build.md).** + +Build a cmake project with a custom install target. + +Conventionally, CMake uses the target `install` to build and copy binaries into the [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). In rare circumstances, a project might have more specific targets that should be used instead. + +Ports should prefer calling [`vcpkg_cmake_install()`](vcpkg_cmake_install.md) when possible. + +## Usage + +```cmake +vcpkg_cmake_build( + [TARGET ] + [LOGFILE_BASE ] + [DISABLE_PARALLEL] + [ADD_BIN_TO_PATH] +) +``` + +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 + +All supported parameters to [`vcpkg_cmake_install()`] are supported by `vcpkg_cmake_build()`. See [`vcpkg_cmake_install()`] for additional parameter documentation. + +[`vcpkg_cmake_install()`]: vcpkg_cmake_install.md#parameters + +### TARGET +The CMake target to build. + +If this parameter is not passed, no target will be passed to the build. + +### LOGFILE_BASE +An alternate root name for the logs. + +Defaults to `build-${TARGET_TRIPLET}`. It should not contain any path separators. Logs will be generated matching the pattern `${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-.log` + +## 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_build(TARGET my.install.target) +``` + +[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_build+path%3A%2Fports) + +## Remarks + +This command replaces [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). + +## Source +[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake) diff --git a/docs/maintainers/vcpkg_cmake_configure.md b/docs/maintainers/vcpkg_cmake_configure.md index 4ad2ad178e..c3ef188b61 100644 --- a/docs/maintainers/vcpkg_cmake_configure.md +++ b/docs/maintainers/vcpkg_cmake_configure.md @@ -1,11 +1,9 @@ # 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). +**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 @@ -128,6 +126,10 @@ vcpkg_cmake_install() [Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_configure+path%3A%2Fports) +## Remarks + +This command replaces [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). + ## Source [ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake) diff --git a/docs/maintainers/vcpkg_cmake_install.md b/docs/maintainers/vcpkg_cmake_install.md new file mode 100644 index 0000000000..5845fecc3f --- /dev/null +++ b/docs/maintainers/vcpkg_cmake_install.md @@ -0,0 +1,53 @@ +# vcpkg_cmake_install + +**The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_cmake_install.md).** + +Build and install a cmake project. + +## Usage + +```cmake +vcpkg_cmake_install( + [DISABLE_PARALLEL] + [ADD_BIN_TO_PATH] +) +``` + +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 + +### DISABLE_PARALLEL +Disables running the build in parallel. + +By default builds are run with up to [VCPKG_MAX_CONCURRENCY](../users/config-environment.md#VCPKG_MAX_CONCURRENCY) jobs. This option limits the build to a single job and should be used only if the underlying build is unable to run correctly with concurrency. + +### ADD_BIN_TO_PATH +Adds the configuration-specific `bin/` directory to the `PATH` during the build. + +When building for a Windows dynamic triplet, newly built executables may not be immediately executable because their dependency DLLs may not be findable from the build environment. This flag instructs vcpkg to add any additional paths needed to locate those dependency DLLs to the `PATH` environment variable. This is required if the project needs to execute newly built binaries as part of the build (such as to generate code). + +## Examples: + +```cmake +vcpkg_from_github(OUT_SOURCE_PATH source_path ...) +vcpkg_cmake_configure(SOURCE_PATH "${source_path}") +vcpkg_cmake_install() +``` + +[Search microsoft/vcpkg for Examples](https://github.com/microsoft/vcpkg/search?q=vcpkg_cmake_install+path%3A%2Fports) + +## Remarks + +This command replaces [`vcpkg_install_cmake()`](vcpkg_install_cmake.md). + +## Source +[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake) diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md index f8d3b6107b..e7388783d3 100644 --- a/docs/maintainers/vcpkg_install_cmake.md +++ b/docs/maintainers/vcpkg_install_cmake.md @@ -1,6 +1,6 @@ # 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.** +**This function has been deprecated in favor of [`vcpkg_cmake_install`](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). diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md index 6cf44aa095..cb0d40b9a1 100644 --- a/docs/users/config-environment.md +++ b/docs/users/config-environment.md @@ -73,9 +73,10 @@ pass in environment variables that should cause rebuilds on change, see [`VCPKG_ Example: `FOO_SDK_DIR;BAR_SDK_DIR` + #### VCPKG_MAX_CONCURRENCY -This environment variables limits the amount of concurrency requested by underlying buildsystems. If unspecified, this defaults to logical cores + 1. +This environment variables limits the amount of concurrency used by underlying buildsystems. If unspecified, this defaults to logical cores + 1. #### VCPKG_DEFAULT_BINARY_CACHE