[scripts-audit] Work list for the scripts tree (stuff we don't need to do immediately)

[strega-nil]

See PR #16055

Not all scripts have been checked yet; we will update this list at our weekly scripts audit meeting.

Paths Forward

There are four possible paths forward:

• Moved to a port ("port")
  • this is where most of the scripts will end up; we don't wish for these scripts to be hamstrung by the strict requirements that we are placing on ports in the scripts tree
  • The existing scripts will be deprecated, since we don't want to break anybody using the old versions
  • Note that for vcpkg_*_<buildsystem> these will all be moved to a single vcpkg-<buildsystem> port.
• Keep in the scripts tree ("keep")
  • this is for scripts that are too simple or too integral to be a port
• Deleted outright ("delete")
  • This is rare. This is only done for scripts that no ports use, and:
    • literally have no use, or
    • should be replaced by other scripts, or
    • should be internal
• Deprecated ("deprecate")
  • This will be used for scripts that should be removed, but can't be since ports use it

Also, there may be scripts that we need to add; this will be marked "new"

Additionally, each script gets an audit item; this means "update to be in line with the standards set out in #16055".

vcpkg.cmake and ports.cmake

• vcpkg.cmake
  • PR [scripts-audit] vcpkg.cmake #16061
  • audit
• ports.cmake
  • PR [scripts audit] ports.cmake #16257
  • audit
    • use explicit paths to the scripts tree for include(), as opposed to just names (that get looked up in the module path)

scripts/cmake

• execute_process(): keep
  • PR [scripts-audit] execute_process #16190
  • audit
    • execute_process' OVERRIDDEN_EXECUTE_PROCESS should get Z_
    • execute_process' override should be a function rather than a macro
• vcpkg_acquire_msys(): port
  • PR #
  • Most of vcpkg_acquire_msys needs to become a tool port, except for the content of the mirror list.
  • Calls to vcpkg_acquire_msys that call PACKAGES are deprecated; the tool port will use NO_DEFAULT_PACKAGES DIRECT_PACKAGES
• vcpkg_add_to_path(): keep
  • PR [scripts-audit] vcpkg_add_to_path #16189
  • audit
• vcpkg_apply_patches(): deprecate
  • PR [scripts-audit] vcpkg_apply_patches #16304
  • audit
  • add z_vcpkg_apply_patches as an internal function
• vcpkg_build_cmake(): port
  • PR [scripts-audit] CMake buildsystem!!! #16377
  • audit
• vcpkg_build_gn(): deprecate
  • PR #
  • audit
  • deprecate in favor of vcpkg_build_ninja
• vcpkg_build_make(): port
  • PR [scripts-audit] Make buildsystem (port) #19753
  • audit
  • remove/deprecate ENABLE_INSTALL (depending on whether it's used) (see also INSTALL_TARGET)
  • look and see if MAKEFILE is used usefully vs SUBPATH; if not, deprecate/remove depending on whether it's used
• vcpkg_build_msbuild(): deprecate
  • PR #
  • audit
  • update modern ports to use vcpkg_install_msbuild()
• vcpkg_build_ninja(): port
  • PR #
  • audit
• vcpkg_build_nmake(): port
  • PR #
  • audit
• vcpkg_build_qmake(): port
  • PR #
  • audit
• vcpkg_buildpath_length_warning(): keep
  • PR [scripts-audit] vcpkg_buildpath_length_warning #16191
  • audit
• vcpkg_check_features(): keep
  • PR [scripts-audit] vcpkg_check_features #16192
  • audit
    • OUT_FEATURE_OPTIONS is made optional, and will default to FEATURE_OPTIONS
    • the <feature-var>s are now checked for uniqueness
    • The FEATURES keyword being optional is now deprecated
• vcpkg_check_linkage(): keep
  • PR #
  • audit
• vcpkg_clean_executables_in_bin(): deprecate
  • PR #
  • audit
  • add z_vcpkg_clean_executables_in_bin as an internal function
• vcpkg_clean_msbuild(): port
  • PR #
  • audit
• vcpkg_common_definitions: keep
  • PR #
  • audit
• vcpkg_common_functions: deprecate
• vcpkg_configure_cmake(): port
  • PR [scripts-audit] CMake buildsystem!!! #16377
  • audit
• vcpkg_configure_gn(): port
  • PR #
  • audit
• vcpkg_configure_make(): port
  • PR [scripts-audit] Make buildsystem (port) #19753
  • audit: serious work
• vcpkg_configure_meson(): port
  • PR #
  • audit
• vcpkg_configure_qmake(): port
  • PR #
  • audit
• vcpkg_copy_pdbs(): keep for now
  • PR [scripts audit] vcpkg_copy_pdbs #16309
  • audit
  • consider baking this into the tool, with a policy for disabling it
• vcpkg_copy_sources(): new
  • PR #
  • Notes: use xcopy or robocopy
• vcpkg_copy_tool_dependencies(): keep
  • PR #
  • add macOS stuff
  • add internal z_vcpkg_copy_tool_dependencies()
  • need to implement this into the vcpkg tool as opposed to using .py/.ps1 scripts
• vcpkg_prettify_command(): remove
  • PR [(z_)vcpkg_prettify_command(_line)] Scripts Tree Audit #16130
  • audit
  • add z_vcpkg_prettify_command_line as an internal function

Other Notes

• vcpkg_minimum_required: In the future, this will be used like cmake_minimum_required, setting up whether a deprecation warning is treated as an error or a warning.
  • we should add a z_vcpkg_deprecated(REMOVED_IN_VERSION <date> MESSAGE "...") which will warn when one uses a deprecated feature if their minimum required is below the <date>, or else issue a fatal error, in order to support older ports while also allowing us to make updates
  • Additionally, we should have a policy for when we can drop deprecated things: in this engineer's opinion, something like five years.

[JackBoosY]

For the vcpkg_*_gn part, see #17519 (comment).