From 5deea3b975fe62990973d73a102de818d83ba20c Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Wed, 12 Feb 2020 15:58:43 -0800 Subject: [vcpkg-docs] Add documentation for `vcpkg_configure_meson()`, `vcpkg_install_meson()`, `vcpkg_fixup_cmake_targts()`, and `vcpkg_prettify_command()` (#7606) * [vcpkg-docs] Add documentation for `vcpkg_configure_meson()`, `vcpkg_install_meson()`, `vcpkg_fixup_cmake_targts()`, and `vcpkg_prettify_command()` * [docs] Address code review comments. Reformat docs for vcpkg_fail_port_install. --- scripts/cmake/vcpkg_apply_patches.cmake | 8 +- scripts/cmake/vcpkg_configure_cmake.cmake | 2 +- scripts/cmake/vcpkg_configure_meson.cmake | 44 +++++++- scripts/cmake/vcpkg_fail_port_install.cmake | 135 +++++++++++++------------ scripts/cmake/vcpkg_find_acquire_program.cmake | 6 +- scripts/cmake/vcpkg_fixup_cmake_targets.cmake | 60 +++++++---- scripts/cmake/vcpkg_install_meson.cmake | 16 ++- scripts/cmake/vcpkg_prettify_command.cmake | 2 +- 8 files changed, 172 insertions(+), 101 deletions(-) (limited to 'scripts') diff --git a/scripts/cmake/vcpkg_apply_patches.cmake b/scripts/cmake/vcpkg_apply_patches.cmake index 8957fca27..d1dba0396 100644 --- a/scripts/cmake/vcpkg_apply_patches.cmake +++ b/scripts/cmake/vcpkg_apply_patches.cmake @@ -1,6 +1,6 @@ ## # vcpkg_apply_patches ## -## Apply a set of patches to a source tree. +## Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al. ## ## ## Usage ## ```cmake @@ -27,10 +27,8 @@ ## ## ## Examples ## -## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) -## * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake) -## * [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake) - +## * [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake) +## * [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake) function(vcpkg_apply_patches) cmake_parse_arguments(_ap "QUIET" "SOURCE_PATH" "PATCHES" ${ARGN}) diff --git a/scripts/cmake/vcpkg_configure_cmake.cmake b/scripts/cmake/vcpkg_configure_cmake.cmake index 260f2471e..9766bd267 100644 --- a/scripts/cmake/vcpkg_configure_cmake.cmake +++ b/scripts/cmake/vcpkg_configure_cmake.cmake @@ -38,7 +38,7 @@ ## 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". +## If used for this purpose, it should be set to `"NMake Makefiles"`. ## ## ### OPTIONS ## Additional options passed to CMake during the configuration. diff --git a/scripts/cmake/vcpkg_configure_meson.cmake b/scripts/cmake/vcpkg_configure_meson.cmake index 6dfb266cf..bbff5e9f6 100644 --- a/scripts/cmake/vcpkg_configure_meson.cmake +++ b/scripts/cmake/vcpkg_configure_meson.cmake @@ -1,3 +1,38 @@ +## # vcpkg_configure_meson +## +## Configure Meson for Debug and Release builds of a project. +## +## ## Usage +## ```cmake +## vcpkg_configure_meson( +## SOURCE_PATH <${SOURCE_PATH}> +## [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`. +## +## ## 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) function(vcpkg_configure_meson) cmake_parse_arguments(_vcm "" "SOURCE_PATH" "OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE" ${ARGN}) @@ -5,16 +40,19 @@ function(vcpkg_configure_meson) file(REMOVE_RECURSE ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg) # use the same compiler options as in vcpkg_configure_cmake + if(NOT VCPKG_TARGET_IS_WINDOWS) + message(FATAL_ERROR "vcpkg_configure_meson() currently only supports windows targets.") + endif() set(MESON_COMMON_CFLAGS "${MESON_COMMON_CFLAGS} /DWIN32 /D_WINDOWS /W3 /utf-8") set(MESON_COMMON_CXXFLAGS "${MESON_COMMON_CXXFLAGS} /DWIN32 /D_WINDOWS /W3 /utf-8 /GR /EHsc") - if(DEFINED VCPKG_CRT_LINKAGE AND VCPKG_CRT_LINKAGE STREQUAL dynamic) + if(DEFINED VCPKG_CRT_LINKAGE AND VCPKG_CRT_LINKAGE STREQUAL "dynamic") set(MESON_DEBUG_CFLAGS "${MESON_DEBUG_CFLAGS} /D_DEBUG /MDd /Z7 /Ob0 /Od /RTC1") set(MESON_DEBUG_CXXFLAGS "${MESON_DEBUG_CXXFLAGS} /D_DEBUG /MDd /Z7 /Ob0 /Od /RTC1") set(MESON_RELEASE_CFLAGS "${MESON_RELEASE_CFLAGS} /MD /O2 /Gy /DNDEBUG /Z7") set(MESON_RELEASE_CXXFLAGS "${MESON_RELEASE_CXXFLAGS} /MD /O2 /Gy /DNDEBUG /Z7") - elseif(DEFINED VCPKG_CRT_LINKAGE AND VCPKG_CRT_LINKAGE STREQUAL static) + elseif(DEFINED VCPKG_CRT_LINKAGE AND VCPKG_CRT_LINKAGE STREQUAL "static") set(MESON_DEBUG_CFLAGS "${MESON_DEBUG_CFLAGS} /D_DEBUG /MTd /Z7 /Ob0 /Od /RTC1") set(MESON_DEBUG_CXXFLAGS "${MESON_DEBUG_CXXFLAGS} /D_DEBUG /MTd /Z7 /Ob0 /Od /RTC1") @@ -28,7 +66,7 @@ function(vcpkg_configure_meson) # select meson cmd-line options list(APPEND _vcm_OPTIONS -Dcmake_prefix_path=${CURRENT_INSTALLED_DIR}) list(APPEND _vcm_OPTIONS --buildtype plain --backend ninja --wrap-mode nodownload) - if(VCPKG_LIBRARY_LINKAGE STREQUAL dynamic) + if(VCPKG_LIBRARY_LINKAGE STREQUAL "dynamic") list(APPEND _vcm_OPTIONS --default-library shared) else() list(APPEND _vcm_OPTIONS --default-library static) diff --git a/scripts/cmake/vcpkg_fail_port_install.cmake b/scripts/cmake/vcpkg_fail_port_install.cmake index 0fdacb639..cf8777506 100644 --- a/scripts/cmake/vcpkg_fail_port_install.cmake +++ b/scripts/cmake/vcpkg_fail_port_install.cmake @@ -1,92 +1,95 @@ ## # vcpkg_fail_port_install ## -## Fails the current portfile with a (default) error message +## Checks common requirements and fails the current portfile with a (default) error message ## ## ## Usage ## ```cmake -## vcpkg_fail_port_install([MESSAGE ] [ON_TARGET [ ...]] -## [ON_ARCH [ ...]] -## [ON_CRT_LINKAGE [ ...]]) -## [ON_LIBRARY_LINKAGE [ ...]]) +## vcpkg_fail_port_install( +## [ALWAYS] +## [MESSAGE <"Reason for failure">] +## [ON_TARGET [ ...]] +## [ON_ARCH [ ...]] +## [ON_CRT_LINKAGE [ ...]]) +## [ON_LIBRARY_LINKAGE [ ...]] +## ) ## ``` ## ## ## Parameters ## ### MESSAGE -## Additional failure message. If non is given a default message will be displayed depending on the failure condition +## Additional failure message. If none is given, a default message will be displayed depending on the failure condition. ## ## ### ALWAYS -## will always fail early +## Will always fail early ## ## ### ON_TARGET -## targets for which the build should fail early. Valid targets are from VCPKG_IS_TARGET_ (see vcpkg_common_definitions.cmake) +## Targets for which the build should fail early. Valid targets are `` from `VCPKG_IS_TARGET_` (see `vcpkg_common_definitions.cmake`). ## ## ### ON_ARCH -## architecture for which the build should fail early. +## 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. +## 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) function(vcpkg_fail_port_install) - cmake_parse_arguments(PARSE_ARGV 0 _csc "ALWAYS" "MESSAGE" "ON_TARGET;ON_ARCH;ON_CRT_LINKAGE;ON_LIBRARY_LINKAGE") - if(DEFINED _csc_UNPARSED_ARGUMENTS) - message(FATAL_ERROR "Unknown arguments passed to vcpkg_fail_port_install. Please correct the portfile!") - endif() - if(DEFINED _csc_MESSAGE) - set(_csc_MESSAGE "${_csc_MESSAGE}\n") - else() - set(_csc_MESSAGE "") - endif() - - unset(_fail_port) - #Target fail check - if(DEFINED _csc_ON_TARGET) - foreach(_target ${_csc_ON_TARGET}) - string(TOUPPER ${_target} _target_upper) - if(VCPKG_TARGET_IS_${_target_upper}) - set(_fail_port TRUE) - set(_csc_MESSAGE "${_csc_MESSAGE}Target '${_target}' not supported by ${PORT}!\n") - endif() - endforeach() - endif() - - #Architecture fail check - if(DEFINED _csc_ON_ARCH) - foreach(_arch ${_csc_ON_ARCH}) - if(${VCPKG_TARGET_ARCHITECTURE} MATCHES ${_arch}) - set(_fail_port TRUE) - set(_csc_MESSAGE "${_csc_MESSAGE}Architecture '${_arch}' not supported by ${PORT}!\n") - endif() - endforeach() - endif() - - #CRT linkage fail check - if(DEFINED _csc_ON_CRT_LINKAGE) - foreach(_crt_link ${_csc_ON_CRT_LINKAGE}) - if("${VCPKG_CRT_LINKAGE}" MATCHES "${_crt_link}") - set(_fail_port TRUE) - set(_csc_MESSAGE "${_csc_MESSAGE}CRT linkage '${VCPKG_CRT_LINKAGE}' not supported by ${PORT}!\n") - endif() - endforeach() - endif() - - #Library linkage fail check - if(DEFINED _csc_ON_LIBRARY_LINKAGE) - foreach(_lib_link ${_csc_ON_LIBRARY_LINKAGE}) - if("${VCPKG_LIBRARY_LINKAGE}" MATCHES "${_lib_link}") - set(_fail_port TRUE) - set(_csc_MESSAGE "${_csc_MESSAGE}Library linkage '${VCPKG_LIBRARY_LINKAGE}' not supported by ${PORT}!\n") - endif() - endforeach() - endif() - - if(_fail_port OR _csc_ALWAYS) - message(FATAL_ERROR ${_csc_MESSAGE}) - endif() + cmake_parse_arguments(PARSE_ARGV 0 _csc "ALWAYS" "MESSAGE" "ON_TARGET;ON_ARCH;ON_CRT_LINKAGE;ON_LIBRARY_LINKAGE") + if(DEFINED _csc_UNPARSED_ARGUMENTS) + message(FATAL_ERROR "Unknown arguments passed to vcpkg_fail_port_install. Please correct the portfile!") + endif() + if(DEFINED _csc_MESSAGE) + set(_csc_MESSAGE "${_csc_MESSAGE}\n") + else() + set(_csc_MESSAGE "") + endif() -endfunction() \ No newline at end of file + unset(_fail_port) + #Target fail check + if(DEFINED _csc_ON_TARGET) + foreach(_target ${_csc_ON_TARGET}) + string(TOUPPER ${_target} _target_upper) + if(VCPKG_TARGET_IS_${_target_upper}) + set(_fail_port TRUE) + set(_csc_MESSAGE "${_csc_MESSAGE}Target '${_target}' not supported by ${PORT}!\n") + endif() + endforeach() + endif() + + #Architecture fail check + if(DEFINED _csc_ON_ARCH) + foreach(_arch ${_csc_ON_ARCH}) + if(${VCPKG_TARGET_ARCHITECTURE} MATCHES ${_arch}) + set(_fail_port TRUE) + set(_csc_MESSAGE "${_csc_MESSAGE}Architecture '${_arch}' not supported by ${PORT}!\n") + endif() + endforeach() + endif() + + #CRT linkage fail check + if(DEFINED _csc_ON_CRT_LINKAGE) + foreach(_crt_link ${_csc_ON_CRT_LINKAGE}) + if("${VCPKG_CRT_LINKAGE}" MATCHES "${_crt_link}") + set(_fail_port TRUE) + set(_csc_MESSAGE "${_csc_MESSAGE}CRT linkage '${VCPKG_CRT_LINKAGE}' not supported by ${PORT}!\n") + endif() + endforeach() + endif() + + #Library linkage fail check + if(DEFINED _csc_ON_LIBRARY_LINKAGE) + foreach(_lib_link ${_csc_ON_LIBRARY_LINKAGE}) + if("${VCPKG_LIBRARY_LINKAGE}" MATCHES "${_lib_link}") + set(_fail_port TRUE) + set(_csc_MESSAGE "${_csc_MESSAGE}Library linkage '${VCPKG_LIBRARY_LINKAGE}' not supported by ${PORT}!\n") + endif() + endforeach() + endif() + + if(_fail_port OR _csc_ALWAYS) + message(FATAL_ERROR ${_csc_MESSAGE}) + endif() +endfunction() diff --git a/scripts/cmake/vcpkg_find_acquire_program.cmake b/scripts/cmake/vcpkg_find_acquire_program.cmake index a525dbc11..303737078 100644 --- a/scripts/cmake/vcpkg_find_acquire_program.cmake +++ b/scripts/cmake/vcpkg_find_acquire_program.cmake @@ -14,9 +14,13 @@ ## The current list of programs includes: ## ## - 7Z +## - ARIA2 (Downloader) ## - BISON +## - DARK +## - DOXYGEN ## - FLEX ## - GASPREPROCESSOR +## - GPERF ## - PERL ## - PYTHON2 ## - PYTHON3 @@ -26,8 +30,8 @@ ## - NASM ## - NINJA ## - NUGET +## - SCONS ## - YASM -## - ARIA2 (Downloader) ## ## Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). ## diff --git a/scripts/cmake/vcpkg_fixup_cmake_targets.cmake b/scripts/cmake/vcpkg_fixup_cmake_targets.cmake index d72381be5..b2faa4abe 100644 --- a/scripts/cmake/vcpkg_fixup_cmake_targets.cmake +++ b/scripts/cmake/vcpkg_fixup_cmake_targets.cmake @@ -1,24 +1,42 @@ -#.rst: -# .. command:: vcpkg_fixup_cmake_targets -# -# Transforms all /debug/share//*targets-debug.cmake files and move them to /share/. -# Removes all /debug/share//*targets.cmake and /debug/share//*config.cmake -# -# Transforms all references matching /bin/*.exe to /tools//*.exe on Windows -# Transforms all references matching /bin/* to /tools//* on other platforms -# -# Fixes ${_IMPORT_PREFIX} in auto generated targets to be one folder deeper. -# Replaces ${CURRENT_INSTALLED_DIR} with ${_IMPORT_PREFIX} in configs/targets. -# -# :: -# vcpkg_fixup_cmake_targets([CONFIG_PATH ]) -# -# ``CONFIG_PATH`` -# *.cmake files subdirectory (like "lib/cmake/${PORT}"). -# -# Example usage: -# vcpkg_fixup_cmake_targets(CONFIG_PATH "lib/cmake/myPort") - +## # vcpkg_fixup_cmake_targets +## +## 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 ] [TARGET_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}`. +## +## ## Notes +## Transform all `/debug//*targets-debug.cmake` files and move them to `/`. +## Removes all `/debug//*targets.cmake` and `/debug//*config.cmake`. +## +## Transform all references matching `/bin/*.exe` to `/tools//*.exe` on Windows. +## Transform all references matching `/bin/*` to `/tools//*` 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) function(vcpkg_fixup_cmake_targets) cmake_parse_arguments(_vfct "" "CONFIG_PATH;TARGET_PATH" "" ${ARGN}) diff --git a/scripts/cmake/vcpkg_install_meson.cmake b/scripts/cmake/vcpkg_install_meson.cmake index 7ab9d55b3..edc6c7302 100644 --- a/scripts/cmake/vcpkg_install_meson.cmake +++ b/scripts/cmake/vcpkg_install_meson.cmake @@ -1,7 +1,18 @@ +## # vcpkg_install_meson +## +## Builds a meson project previously configured with `vcpkg_configure_meson()`. +## +## ## Usage +## ```cmake +## vcpkg_install_meson() +## ``` +## +## ## 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) function(vcpkg_install_meson) - vcpkg_find_acquire_program(NINJA) - unset(ENV{DESTDIR}) # installation directory was already specified with '--prefix' option message(STATUS "Package ${TARGET_TRIPLET}-rel") @@ -17,5 +28,4 @@ function(vcpkg_install_meson) WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg LOGNAME package-${TARGET_TRIPLET}-dbg ) - endfunction() diff --git a/scripts/cmake/vcpkg_prettify_command.cmake b/scripts/cmake/vcpkg_prettify_command.cmake index 9d9a2b798..ca04f9120 100644 --- a/scripts/cmake/vcpkg_prettify_command.cmake +++ b/scripts/cmake/vcpkg_prettify_command.cmake @@ -4,7 +4,7 @@ ## ## ## Usage ## ```cmake -## vcpkg_prettify_command() +## vcpkg_prettify_command( ) ## ``` ## ## ## Examples -- cgit v1.2.3