Add new ways to report build failures and giving hint messages from portfile.cmake

[autoantwort]

Motivation 1: In cases like microsoft/vcpkg#30744 users should not create issues (problem was insufficient disk space). In vcpkg_execute_build_process we could add a call to vcpkg_fail_with_user_interaction_required with a proper error message saying the disk is full.

Motivation 2: increase visibility or warnings since users report issues like this: microsoft/vcpkg#30592 (comment) (Could not find make. Please install it through your package manager.) => vcpkg_fail_with_user_interaction_required. Another example would be microsoft/vcpkg#31276 or microsoft/vcpkg#31312 or microsoft/vcpkg#35151 or microsoft/vcpkg#36541 or microsoft/vcpkg#35991 or microsoft/vcpkg#36011

Motivation 3: Many ports emits warnings like the following

alsa currently requires the following libraries from the system package manager:
    autoconf libtool
These can be installed on Ubuntu systems via sudo apt install autoconf libtool

This is confusing if the libs are already installed and the build is successful. These messages should only be printed when the build fails and they should be printed after the "how to report an issue" block to be more visible. => vcpkg_user_hint_on_failure

Also see docs PR microsoft/vcpkg-docs#60

[Thomas1664]

Better make sure that it's a regular file

[autoantwort]

Since it is only an internal interface I think it is ok here. Crashing in case of an folder is a good thing. And I don't care if someone wants to use symbolic links in the future.

[ras0219-msft]

First, I strongly agree we need to improve these cases. Better build error messages for users has tons of potential. I have a few different areas I wanted to comment on, so apologies in advance for the length.

Restating Cases

Listing out some more error cases that the user can fix, along with the diagnostic difficulty:

• Missing system libraries (hard)
• Permissions (hard -- looks the same as other issues?)
• MAX_PATH (medium)
• Out of Disk (easier)
• Out of Memory (easier)
• Missing Windows SDK (easier)
• Compiler issues (easier?)

Under this lens, I think your proposed mechanisms are intended to handle:

• Difficult to diagnose / specific-to-port (fail-hints)
• Easy to diagnose and generic (fail-require-user-interaction)

Instead of separating these two cases entirely, what about only having hints and, if hints are provided, reduce the prominence of the issue message?

Implementation: Port vs Tool

I see a design decision between putting the port in charge versus creating heuristics in the vcpkg tool. Port-based approaches are more easily iterated on, but are also very limiting. It is quite painful to try to regex through build logs from an "error handler" inside CMake (as we've done for some things). On the other hand, in the tool itself progress is slower and it often wouldn't be "worth it" to handle highly exceptional cases.

A bonus of implementing things in the tool is that they get localized :).

Port-approach Communication Channel

I'm not convinced that raw text known-paths in buildtrees/ are the right extension interface. Some alternatives to consider in no particular order:

• Named Pipe / Unix domain socket back to the vcpkg parent process (complex to implement, but opens up interesting doors)
• In-Band sequences to standard out (a la CI systems):
  message("::hintonfail::You may need to install xyz from your system package manager")
  (https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions)
• Instead of having the file path baked into the scripts, we could use an environment variable:
  file(APPEND "$ENV{HINT_FILE}" "Hint Message\n")
  (https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#environment-files)

Fortunately all these should be retrofit-able underneath a CMake function call interface (as you've implemented).

[autoantwort]

Under this lens, I think your proposed mechanisms are intended to handle:

• Difficult to diagnose / specific-to-port (fail-hints)
• Easy to diagnose and generic (fail-require-user-interaction)

Probably I should not hide the description in the docs PR: microsoft/vcpkg-docs#60

The motivation/difference of these two functions is the following:

• vcpkg_fail_with_user_interaction_required: We are 100% sure what the error is and the user has to fix it. Like disk full, missing windows SDK or missing program that the user must install. In this case we should not explain how to report an issue.
• vcpkg_user_hint_on_failure: We don't know if the hint resolves the error and maybe it is vcpkg's fault. Like "please install xyz from the system package manager". We don't check if xyz is already installed or not so installing xyz might resolve the issue or xyz is already installed and the problem is something different. So we should still show the explanation on how to report an issue.