[vcpkg] Add vcpkg_install_copyright() portfile function (#25239)

* [vcpkg tool] Add vcpkg_install_copyright

* Make sure FILE_LIST is provided

* relative to ${SOURCE_PATH}

* Add documentation

* Add to table of contents

* Relative paths was a bad idea.

* Tell users to use the correct way

Co-authored-by: Billy O'Neal <bion@microsoft.com>

* Fix docs

* Add parameter COMMENT

* Rename to vcpkg_concat_copyright

* Fix escape

* Revert "Fix escape"

This reverts commit 53f1636705.

* Revert "Rename to vcpkg_concat_copyright"

This reverts commit 6ce9152a61.

* Fix escape

* Add support for single copyright file

* Update docs

* Make comment less confusing

* [ci skip] Billy CR

* [ci skip] Format

* Remove explicit checks for STREQUAL ""

* Add error msg if file doesn't exist

Co-authored-by: Billy O'Neal <bion@microsoft.com>

docs/maintainers/maintainer-guide.md

@@ -109,6 +109,20 @@ This means that the user should see:
 Examples:
  * [`brotli`](https://github.com/microsoft/vcpkg/blob/4f0a640e4c5b74166b759a862d7527c930eff32e/ports/brotli/install.patch) creates the `unofficial-brotli` package, producing target `unofficial::brotli::brotli`.
 
+### Install copyright file
+
+Each port has to provide a file named `copyright` in the folder `${CURRENT_PACKAGES_DIR}/share/${PORT}`.
+
+Many ports are using this code to install a copyright file:
+
+```cmake
+file(INSTALL "${SOURCE_PATH}LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
+```
+
+This is discouraged in favour of [`vcpkg_install_copyright()`](vcpkg_install_copyright.md). New ports should use `vcpkg_install_copyright()` instead. However, it is still valid for existing ports to use something like the code above. You may replace this with `vcpkg_install_copyright` but you don't have to.
+
+`vcpkg_install_copyright` also includes the functionallity to handle multiple copyright files. See its [documentation](vcpkg_install_copyright.md) for more info.
+
 ## Features
 
 ### Do not use features to implement alternatives

docs/maintainers/portfile-functions.md

@@ -48,6 +48,7 @@
 - [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\_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)
 - [vcpkg\_install\_meson](vcpkg_install_meson.md)
 - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)

docs/maintainers/vcpkg_install_copyright.md

@@ -0,0 +1,69 @@
+# vcpkg_install_copyright
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_copyright.md).
+
+Merges multiple copyright files into a single file and install it.
+Installs a single copyright file.
+
+## Usage
+
+```cmake
+vcpkg_install_copyright(FILE_LIST <file1> <file2>... [COMMENT])
+```
+
+## Parameters
+
+### FILE_LIST
+Specifies a list of license files with absolute paths. You must provide at least one file.
+
+### COMMENT
+This optional parameter adds a comment before at the top of the file. 
+
+## Notes
+
+This function creates a file called `copyright` inside `${CURRENT_PACKAGES_DIR}/share/${PORT}`
+
+If more than one file is provided, this function concatenates the contents of multiple copyright files to a single file.
+
+The resulting `copyright` file looks similar to this:
+
+```
+LICENSE-LGPL2.txt:
+
+Lorem ipsum dolor...
+
+LICENSE-MIT.txt:
+
+Lorem ipsum dolor sit amet...
+```
+
+Or with `COMMENT`:
+
+```
+A meaningful comment
+
+LICENSE-LGPL2.txt:
+
+Lorem ipsum dolor...
+
+LICENSE-MIT.txt:
+
+Lorem ipsum dolor sit amet...
+```
+
+## Examples
+
+```cmake
+vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE/license.md" "${SOURCE_PATH}/LICENSE/license_gpl.md" COMMENT "This is a comment")
+```
+
+You can also collect the required files using a `GLOB` pattern:
+
+```cmake
+file(GLOB LICENSE_FILES "${SOURCE_PATH}/LICENSES/*")
+vcpkg_install_copyright(FILE_LIST ${LICENSE_FILES})
+```
+
+## Source
+
+[vcpkg_install_copyright.md](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_copyright.cmake)

scripts/cmake/vcpkg_install_copyright.cmake

@@ -0,0 +1,42 @@
+function(vcpkg_install_copyright)
+    cmake_parse_arguments(PARSE_ARGV 0 arg "" "COMMENT" "FILE_LIST")
+
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "${CMAKE_CURRENT_FUNCTION} was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    if(NOT DEFINED arg_FILE_LIST)
+        message(FATAL_ERROR "FILE_LIST must be specified")
+    endif()
+
+    list(LENGTH arg_FILE_LIST FILE_LIST_LENGTH)
+    set(out_string "")
+    
+    if(FILE_LIST_LENGTH LESS_EQUAL 0)
+        message(FATAL_ERROR "FILE_LIST must contain at least one file")
+    elseif(FILE_LIST_LENGTH EQUAL 1)
+        if(arg_COMMENT)
+            file(READ "${arg_FILE_LIST}" out_string)
+        else()
+            file(INSTALL "${arg_FILE_LIST}" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
+            return()
+        endif()
+    else()
+        foreach(file_item IN LISTS arg_FILE_LIST)
+            if(NOT EXISTS "${file_item}")
+                message(FATAL_ERROR "\n${CMAKE_CURRENT_FUNCTION} was passed a non-existing path: ${file_item}\n")
+            endif()
+
+            get_filename_component(file_name "${file_item}" NAME)
+            file(READ "${file_item}" file_contents)
+
+            string(APPEND out_string "${file_name}:\n\n${file_contents}\n\n")
+        endforeach()
+    endif()
+
+    if(arg_COMMENT)
+        string(PREPEND out_string "${arg_COMMENT}\n\n")
+    endif()
+
+    file(WRITE "${CURRENT_PACKAGES_DIR}/share/${PORT}/copyright" "${out_string}")
+endfunction()

scripts/ports.cmake

@@ -45,6 +45,7 @@ include("${SCRIPTS}/cmake/vcpkg_get_program_files_platform_bitness.cmake")
 include("${SCRIPTS}/cmake/vcpkg_get_windows_sdk.cmake")
 include("${SCRIPTS}/cmake/vcpkg_host_path_list.cmake")
 include("${SCRIPTS}/cmake/vcpkg_install_cmake.cmake")
+include("${SCRIPTS}/cmake/vcpkg_install_copyright.cmake")
 include("${SCRIPTS}/cmake/vcpkg_install_gn.cmake")
 include("${SCRIPTS}/cmake/vcpkg_install_make.cmake")
 include("${SCRIPTS}/cmake/vcpkg_install_meson.cmake")

scripts/templates/portfile.in.cmake

@@ -80,5 +80,6 @@ vcpkg_cmake_install()
 #}
 # vcpkg_cmake_config_fixup(CONFIG_PATH cmake TARGET_PATH share/@PORT@)
 
-# Uncomment the line below if necessary to install the license file for the port to share/${PORT}/copyright
-# file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
+# Uncomment the line below if necessary to install the license file for the port
+# as a file named `copyright` to the directory `${CURRENT_PACKAGES_DIR}/share/${PORT}`
+# vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")