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

include/vcpkg/base/message-data.inc.h

@@ -335,6 +335,10 @@ DECLARE_MESSAGE(BuildResultSummaryLine,
                 "Displayed to show a count of results of a build_result in a summary.",
                 "{build_result}: {count}")
 DECLARE_MESSAGE(BuildTreesRootDir, (), "", "(Experimental) Specify the buildtrees root directory.")
+DECLARE_MESSAGE(BuildTroubleshootingFollowHints,
+                (),
+                "",
+                "Before reporting an issue see the following points to probably fix the build failue:")
 DECLARE_MESSAGE(BuildTroubleshootingMessage1,
                 (),
                 "First part of build troubleshooting message, printed before the URI to look for existing bugs.",

include/vcpkg/commands.build.h

@@ -131,14 +131,16 @@ namespace vcpkg
 
     StringLiteral to_string_locale_invariant(const BuildResult build_result);
     LocalizedString to_string(const BuildResult build_result);
-    LocalizedString create_user_troubleshooting_message(const InstallPlanAction& action,
+    LocalizedString create_user_troubleshooting_message(const VcpkgCmdArguments& args,
+                                                        const InstallPlanAction& action,
                                                         const VcpkgPaths& paths,
-                                                        const Optional<Path>& issue_body);
-    inline void print_user_troubleshooting_message(const InstallPlanAction& action,
+                                                        const ExtendedBuildResult& result);
+    inline void print_user_troubleshooting_message(const VcpkgCmdArguments& args,
+                                                   const InstallPlanAction& action,
                                                    const VcpkgPaths& paths,
-                                                   Optional<Path>&& issue_body)
+                                                   const ExtendedBuildResult& result)
     {
-        msg::println(Color::error, create_user_troubleshooting_message(action, paths, issue_body));
+        msg::println(Color::error, create_user_troubleshooting_message(args, action, paths, result));
     }
 
     /// <summary>
@@ -189,6 +191,10 @@ namespace vcpkg
         std::unique_ptr<BinaryControlFile> binary_control_file;
         Optional<vcpkg::Path> stdoutlog;
         std::vector<std::string> error_logs;
+        // if a package fails and a user has to do something for sure. For example installing the Windows SDK
+        Optional<std::string> user_required_interaction;
+        // if a package fails and a user can maybe solve this by following this commands (like `apt install ...`)
+        Optional<std::string> user_hints;
     };
 
     LocalizedString create_error_message(const ExtendedBuildResult& build_result, const PackageSpec& spec);

locales/messages.json

@@ -196,6 +196,7 @@
   "BuildResultSummaryLine": "{build_result}: {count}",
   "_BuildResultSummaryLine.comment": "Displayed to show a count of results of a build_result in a summary. An example of {build_result} is One of the BuildResultXxx messages (such as BuildResultSucceeded/SUCCEEDED). An example of {count} is 42.",
   "BuildTreesRootDir": "(Experimental) Specify the buildtrees root directory.",
+  "BuildTroubleshootingFollowHints": "Before reporting an issue see the following points to probably fix the build failue:",
   "BuildTroubleshootingMessage1": "Please ensure you're using the latest port files with `git pull` and `vcpkg update`.\nThen check for known issues at:",
   "_BuildTroubleshootingMessage1.comment": "First part of build troubleshooting message, printed before the URI to look for existing bugs.",
   "BuildTroubleshootingMessage2": "You can submit a new issue at:",

src/vcpkg/commands.build.cpp

@@ -169,7 +169,7 @@ namespace vcpkg::Build
                 msg::print(Color::warning, warnings);
             }
             msg::println_error(create_error_message(result, spec));
-            msg::print(create_user_troubleshooting_message(*action, paths, nullopt));
+            msg::print(create_user_troubleshooting_message(args, *action, paths, result));
             return 1;
         }
         binary_cache.push_success(*action);
@@ -932,12 +932,18 @@ namespace vcpkg
         }
 
         const ElapsedTimer timer;
-        auto command = vcpkg::make_cmake_cmd(paths, paths.ports_cmake, get_cmake_build_args(args, paths, action));
+        auto buildpath = paths.build_dir(action.spec);
+        const auto user_required_path =
+            buildpath / Strings::concat("required-user-interaction-", action.spec.triplet(), ".txt");
+        const auto user_hints_path = buildpath / Strings::concat("user-hints-", action.spec.triplet(), ".txt");
+        auto build_args = get_cmake_build_args(args, paths, action);
+        build_args.emplace_back("Z_VCPKG_REQUIRED_USER_INTERACTION_ON_BUILD_FAILURE_FILE", user_required_path);
+        build_args.emplace_back("Z_VCPKG_USER_HINTS_ON_BUILD_FAILURE_FILE", user_hints_path);
+        auto command = vcpkg::make_cmake_cmd(paths, paths.ports_cmake, std::move(build_args));
 
         const auto& abi_info = action.abi_info.value_or_exit(VCPKG_LINE_INFO);
         auto env = paths.get_action_env(abi_info);
 
-        auto buildpath = paths.build_dir(action.spec);
         fs.create_directory(buildpath, VCPKG_LINE_INFO);
         env.add_entry("GIT_CEILING_DIRECTORIES", fs.absolute(buildpath.parent_path(), VCPKG_LINE_INFO));
         auto stdoutlog = buildpath / ("stdout-" + action.spec.triplet().canonical_name() + ".log");
@@ -996,7 +1002,16 @@ namespace vcpkg
                 error_logs = fs.read_lines(logs).value_or_exit(VCPKG_LINE_INFO);
                 Util::erase_remove_if(error_logs, [](const auto& line) { return line.empty(); });
             }
-            return ExtendedBuildResult{BuildResult::BUILD_FAILED, stdoutlog, std::move(error_logs)};
+            ExtendedBuildResult result{BuildResult::BUILD_FAILED, stdoutlog, std::move(error_logs)};
+            if (fs.exists(user_required_path, VCPKG_LINE_INFO))
+            {
+                result.user_required_interaction = fs.read_contents(user_required_path, VCPKG_LINE_INFO);
+            }
+            if (fs.exists(user_hints_path, VCPKG_LINE_INFO))
+            {
+                result.user_hints = fs.read_contents(user_hints_path, VCPKG_LINE_INFO);
+            }
+            return result;
         }
 
         const BuildInfo build_info = read_build_info(fs, paths.build_info_file_path(action.spec));
@@ -1522,17 +1537,27 @@ namespace vcpkg
                                Strings::percent_encode(path));
     }
 
-    LocalizedString create_user_troubleshooting_message(const InstallPlanAction& action,
+    LocalizedString create_user_troubleshooting_message(const VcpkgCmdArguments& args,
+                                                        const InstallPlanAction& action,
                                                         const VcpkgPaths& paths,
-                                                        const Optional<Path>& issue_body)
+                                                        const ExtendedBuildResult& build_result)
     {
+        if (build_result.user_required_interaction.has_value())
+        {
+            return LocalizedString::from_raw(build_result.user_required_interaction.value_or_exit(VCPKG_LINE_INFO))
+                .append_raw('\n');
+        }
         const auto& spec_name = action.spec.name();
         LocalizedString result = msg::format(msgBuildTroubleshootingMessage1).append_raw('\n');
         result.append_indent().append_raw(make_gh_issue_search_url(spec_name)).append_raw('\n');
         result.append(msgBuildTroubleshootingMessage2).append_raw('\n');
-        if (issue_body.has_value())
+        if (build_result.stdoutlog.has_value())
         {
-            auto path = issue_body.get()->generic_u8string();
+            auto issue_body_path = paths.installed().root() / "vcpkg" / "issue_body.md";
+            paths.get_filesystem().write_contents(
+                issue_body_path, create_github_issue(args, build_result, paths, action), VCPKG_LINE_INFO);
+
+            auto path = issue_body_path.generic_u8string();
             result.append_indent().append_raw(make_gh_issue_open_url(spec_name, path)).append_raw("\n");
             if (!paths.get_filesystem().find_from_PATH("gh").empty())
             {
@@ -1555,6 +1580,14 @@ namespace vcpkg
             result.append(msgBuildTroubleshootingMessage3, msg::package_name = spec_name).append_raw('\n');
             result.append_raw(paths.get_toolver_diagnostics()).append_raw('\n');
         }
+        if (build_result.user_hints.has_value())
+        {
+            result.append_raw('\n')
+                .append(msgBuildTroubleshootingFollowHints)
+                .append_raw('\n')
+                .append_raw(build_result.user_hints.value_or_exit(VCPKG_LINE_INFO))
+                .append_raw('\n');
+        }
 
         return result;
     }

src/vcpkg/commands.install.cpp

@@ -561,12 +561,7 @@ namespace vcpkg
                 perform_install_plan_action(args, paths, action, status_db, binary_cache, build_logs_recorder);
             if (result.code != BuildResult::SUCCEEDED && keep_going == KeepGoing::NO)
             {
-                print_user_troubleshooting_message(action, paths, result.stdoutlog.then([&](auto&) -> Optional<Path> {
-                    auto issue_body_path = paths.installed().root() / "vcpkg" / "issue_body.md";
-                    paths.get_filesystem().write_contents(
-                        issue_body_path, create_github_issue(args, result, paths, action), VCPKG_LINE_INFO);
-                    return issue_body_path;
-                }));
+                print_user_troubleshooting_message(args, action, paths, result);
                 Checks::exit_fail(VCPKG_LINE_INFO);
             }