xalan-c: Install headers correctly (#4565)

* Add SKIP_CLEAN option to vcpkg_install_msbuild

Also add vcpkg_clean_msbuild function to factor out clean
logic and allow re-use in portfiles.

* xalan-c: Correct header globbing

* vcpkg_install_msbuild: SKIP_CLEAN documentation correction

* [xalan-c] Add explicit check for localmsgindex header.
[docs] Regenerate

13 files changed, 120 insertions, 14 deletions

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index f9476d3a7..3180609ad 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -2,10 +2,12 @@
 
 # Portfile helper functions

 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)

+- [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)

 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)

 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)

 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)

 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)

+- [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)

 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)

 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)

 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)

@@ -18,3 +20,4 @@
 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)

 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

 - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)

+- [vcpkg\_test\_cmake](vcpkg_test_cmake.md)

diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md
new file mode 100644
index 000000000..3657a5ea7
--- /dev/null
+++ b/docs/maintainers/vcpkg_add_to_path.md
@@ -0,0 +1,20 @@
+# vcpkg_add_to_path
+
+Add a directory to the PATH environment variable
+
+## Usage
+```cmake
+vcpkg_add_to_path([PREPEND] <${PYTHON3_DIR}>)
+```
+
+## Parameters
+### <positional>
+The directory to add
+
+### PREPEND
+Prepends the directory.
+
+The default is to append.
+
+## Source
+[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

diff --git a/docs/maintainers/vcpkg_clean_msbuild.md b/docs/maintainers/vcpkg_clean_msbuild.md
new file mode 100644
index 000000000..39d07077b
--- /dev/null
+++ b/docs/maintainers/vcpkg_clean_msbuild.md
@@ -0,0 +1,15 @@
+# vcpkg_clean_msbuild
+
+Clean intermediate files generated by `vcpkg_install_msbuild()`.
+
+## Usage
+```cmake
+vcpkg_clean_msbuild()
+```
+
+## Examples
+
+* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_clean_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)

diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md
index c8850b725..7e699f8ea 100644
--- a/docs/maintainers/vcpkg_from_bitbucket.md
+++ b/docs/maintainers/vcpkg_from_bitbucket.md
@@ -11,6 +11,7 @@ vcpkg_from_bitbucket(
     [REF <v2.0.0>]
     [SHA512 <45d0d7f8cc350...>]
     [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
 
@@ -40,6 +41,11 @@ 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.
 
diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md
index 69deea933..bc312f37a 100644
--- a/docs/maintainers/vcpkg_from_gitlab.md
+++ b/docs/maintainers/vcpkg_from_gitlab.md
@@ -11,6 +11,7 @@ vcpkg_from_gitlab(
     [REF <v10.7.3>]
     [SHA512 <45d0d7f8cc350...>]
     [HEAD_REF <master>]
+    [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
 
@@ -45,6 +46,11 @@ 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.
 
diff --git a/docs/maintainers/vcpkg_install_msbuild.md b/docs/maintainers/vcpkg_install_msbuild.md
index 76578c2ef..1de68ce70 100644
--- a/docs/maintainers/vcpkg_install_msbuild.md
+++ b/docs/maintainers/vcpkg_install_msbuild.md
@@ -52,12 +52,16 @@ 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.
+The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
 
 ### TARGET_PLATFORM_VERSION
 The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
@@ -82,6 +86,7 @@ Additional options passed to msbuild for Debug builds. These are in addition to
 
 ## Examples
 
+* [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
 * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
 
 ## Source
diff --git a/docs/maintainers/vcpkg_test_cmake.md b/docs/maintainers/vcpkg_test_cmake.md
new file mode 100644
index 000000000..15b3ad797
--- /dev/null
+++ b/docs/maintainers/vcpkg_test_cmake.md
@@ -0,0 +1,20 @@
+# vcpkg_test_cmake
+
+Tests a built package for CMake `find_package()` integration.
+
+## Usage:
+```cmake
+vcpkg_test_cmake(PACKAGE_NAME <name> [MODULE])
+```
+
+## Parameters:
+
+### PACKAGE_NAME
+The expected name to find with `find_package()`.
+
+### MODULE
+Indicates that the library expects to be found via built-in CMake targets.
+
+
+## Source
+[scripts/cmake/vcpkg_test_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_test_cmake.cmake)

diff --git a/ports/xalan-c/CONTROL b/ports/xalan-c/CONTROL
index 41c407477..aa2345462 100644
--- a/ports/xalan-c/CONTROL
+++ b/ports/xalan-c/CONTROL
@@ -1,4 +1,4 @@
 Source: xalan-c
-Version: 1.11-3
+Version: 1.11-4
 Description: Xalan is an XSLT processor for transforming XML documents into HTML, text, or other XML document types
 Build-Depends: xerces-c
diff --git a/ports/xalan-c/portfile.cmake b/ports/xalan-c/portfile.cmake
index 181786e1b..4c035260a 100644
--- a/ports/xalan-c/portfile.cmake
+++ b/ports/xalan-c/portfile.cmake
@@ -39,14 +39,19 @@ vcpkg_install_msbuild(
     OPTIONS_RELEASE /p:XERCESCROOT=${CURRENT_INSTALLED_DIR}
     OPTIONS_DEBUG /p:XERCESCROOT=${CURRENT_INSTALLED_DIR}/debug
     LICENSE_SUBPATH c/LICENSE
+    SKIP_CLEAN
 )
 
 file(COPY ${SOURCE_PATH}/c/src/xalanc DESTINATION ${CURRENT_PACKAGES_DIR}/include FILES_MATCHING PATTERN *.hpp)
 
-# LocalMsgIndex.hpp is here
-file(GLOB LOCALMSGINDEX ${CURRENT_BUILDTREES_DIR}/${VCPKG_TARGET_TRIPLET}-rel/*/c/Build/*/VC10/Release/Nls/Include/LocalMsgIndex.hpp)
+# LocalMsgIndex.hpp and LocalMsgData.hpp are here
+file(GLOB NLS_INCLUDES "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/*/c/Build/*/VC10/Release/Nls/Include/*.hpp")
+if(NOT NLS_INCLUDES)
+    message(FATAL_ERROR "Could not locate LocalMsgIndex.hpp")
+endif()
+file(COPY ${NLS_INCLUDES} DESTINATION ${CURRENT_PACKAGES_DIR}/include/xalanc/PlatformSupport)
 
-file(COPY ${LOCALMSGINDEX} DESTINATION ${CURRENT_PACKAGES_DIR}/include/xalanc/PlatformSupport)
+vcpkg_clean_msbuild()
 
 file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/include/xalanc/NLS)
 file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/include/xalanc/util/MsgLoaders/ICU/resources)
diff --git a/scripts/cmake/vcpkg_append_to_path.cmake b/scripts/cmake/vcpkg_add_to_path.cmake
index 6890dfe31..6890dfe31 100644
--- a/scripts/cmake/vcpkg_append_to_path.cmake
+++ b/scripts/cmake/vcpkg_add_to_path.cmake
diff --git a/scripts/cmake/vcpkg_clean_msbuild.cmake b/scripts/cmake/vcpkg_clean_msbuild.cmake
new file mode 100644
index 000000000..b0d77dfd2
--- /dev/null
+++ b/scripts/cmake/vcpkg_clean_msbuild.cmake
@@ -0,0 +1,19 @@
+## # vcpkg_clean_msbuild
+##
+## Clean intermediate files generated by `vcpkg_install_msbuild()`.
+##
+## ## Usage
+## ```cmake
+## vcpkg_clean_msbuild()
+## ```
+##
+## ## Examples
+##
+## * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
+
+function(vcpkg_clean_msbuild)
+    file(REMOVE_RECURSE
+        ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg
+        ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
+    )
+endfunction()
diff --git a/scripts/cmake/vcpkg_common_functions.cmake b/scripts/cmake/vcpkg_common_functions.cmake
index 90a3e2814..595ebb00e 100644
--- a/scripts/cmake/vcpkg_common_functions.cmake
+++ b/scripts/cmake/vcpkg_common_functions.cmake
@@ -1,6 +1,7 @@
 include(vcpkg_acquire_msys)
-include(vcpkg_append_to_path)
+include(vcpkg_add_to_path)
 include(vcpkg_check_linkage)
+include(vcpkg_clean_msbuild)
 include(vcpkg_download_distfile)
 include(vcpkg_extract_source_archive)
 include(vcpkg_execute_required_process)
diff --git a/scripts/cmake/vcpkg_install_msbuild.cmake b/scripts/cmake/vcpkg_install_msbuild.cmake
index ad700dd35..11bcdf189 100644
--- a/scripts/cmake/vcpkg_install_msbuild.cmake
+++ b/scripts/cmake/vcpkg_install_msbuild.cmake
@@ -52,12 +52,16 @@
 ## ### 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.
+## The configuration (``/p:Configuration`` msbuild parameter) used for Debug builds.
 ##
 ## ### TARGET_PLATFORM_VERSION
 ## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
@@ -82,12 +86,15 @@
 ##
 ## ## Examples
 ##
+## * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
 ## * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
 
+include(vcpkg_clean_msbuild)
+
 function(vcpkg_install_msbuild)
     cmake_parse_arguments(
         _csc
-        "USE_VCPKG_INTEGRATION;ALLOW_ROOT_INCLUDES;REMOVE_ROOT_INCLUDES"
+        "USE_VCPKG_INTEGRATION;ALLOW_ROOT_INCLUDES;REMOVE_ROOT_INCLUDES;SKIP_CLEAN"
         "SOURCE_PATH;PROJECT_SUBPATH;INCLUDES_SUBPATH;LICENSE_SUBPATH;RELEASE_CONFIGURATION;DEBUG_CONFIGURATION;PLATFORM;PLATFORM_TOOLSET;TARGET_PLATFORM_VERSION;TARGET"
         "OPTIONS;OPTIONS_RELEASE;OPTIONS_DEBUG"
         ${ARGN}
@@ -196,10 +203,9 @@ function(vcpkg_install_msbuild)
 
     vcpkg_copy_pdbs()
 
-    file(REMOVE_RECURSE
-        ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg
-        ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
-    )
+    if(NOT _csc_SKIP_CLEAN)
+        vcpkg_clean_msbuild()
+    endif()
 
     if(DEFINED _csc_INCLUDES_SUBPATH)
         file(COPY ${_csc_SOURCE_PATH}/${_csc_INCLUDES_SUBPATH}/ DESTINATION ${CURRENT_PACKAGES_DIR}/include/)