cli(build): make build heartbeat opt-in via VIX_BUILD_HEARTBEAT and document it in help

Author: GaspardKirira

src/cmake/CMakeBuild.cpp

@@ -244,6 +244,22 @@ namespace vix::cli::build
 
     const bool filterCMakeSummary = is_configure_cmd(argv) && !cmakeVerbose;
 
+    const bool heartbeatEnabled = [&]() -> bool
+    {
+      if (quiet)
+        return false;
+      const char *v = std::getenv("VIX_BUILD_HEARTBEAT");
+      if (!v)
+        return false;
+
+      std::string s(v);
+      s = util::trim(s);
+      for (char &c : s)
+        c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+
+      return (s == "1" || s == "true" || s == "yes" || s == "on");
+    }();
+
     int pipefd[2];
     if (::pipe(pipefd) != 0)
     {
@@ -332,10 +348,11 @@ namespace vix::cli::build
 
     std::string buf(16 * 1024, '\0');
 
-    // Heartbeat state
+    // Heartbeat state (only used if enabled)
     const auto startTs = std::chrono::steady_clock::now();
     auto lastOutputTs = startTs;
     auto lastHeartbeatTs = startTs;
+    bool heartbeatPrinted = false;
 
     // poll loop
     while (true)
@@ -345,7 +362,7 @@ namespace vix::cli::build
       pfd.events = POLLIN | POLLHUP | POLLERR;
       pfd.revents = 0;
 
-      // 250ms tick -> lets us print heartbeat & not look frozen
+      // 250ms tick -> lets us keep UI responsive (and optional heartbeat)
       const int pr = ::poll(&pfd, 1, 250);
 
       if (pr < 0)
@@ -413,8 +430,7 @@ namespace vix::cli::build
       if (pr > 0 && (pfd.revents & (POLLHUP | POLLERR)))
         break;
 
-      // No output tick -> heartbeat (avoid "looks frozen")
-      if (!quiet)
+      if (heartbeatEnabled)
       {
         const auto now = std::chrono::steady_clock::now();
         const auto silenceMs =
@@ -430,8 +446,9 @@ namespace vix::cli::build
               std::chrono::duration_cast<std::chrono::milliseconds>(now - startTs).count();
 
           std::string msg =
-              "\r[building] still running… (" + util::format_seconds(elapsedMs) + ")   ";
+              "\r[building] still running... (" + util::format_seconds(elapsedMs) + ")   ";
           write_all_fd(STDOUT_FILENO, msg.data(), msg.size());
+          heartbeatPrinted = true;
         }
       }
     }
@@ -456,17 +473,19 @@ namespace vix::cli::build
       return r;
     }
 
-    if (!quiet)
+    // clear heartbeat line only if it was printed
+    if (heartbeatEnabled && heartbeatPrinted)
     {
-      // clear heartbeat line if any
-      const std::string clear = "\r";
+      // best-effort: overwrite the line then return carriage
+      const std::string clear = "\r\033[2K\r";
       write_all_fd(STDOUT_FILENO, clear.data(), clear.size());
     }
 
     r.exitCode = process::normalize_exit_code(status);
     r.capturedFirstLine = util::trim(firstLine);
     return r;
   }
+
 #else // _WIN32
 
   process::ExecResult run_process_capture(

src/commands/BuildCommand.cpp

@@ -919,43 +919,38 @@ namespace vix::commands::BuildCommand
 
     out << "Options:\n";
     out << "  --preset <name>       Preset to use (dev, dev-ninja, release)\n";
-    out << "  --target <triple>     Cross-compilation target triple (auto "
-           "toolchain)\n";
+    out << "  --target <triple>     Cross-compilation target triple (auto toolchain)\n";
     out << "  --sysroot <path>      Sysroot for cross toolchain (optional)\n";
-    out << "  --static              Request static linking "
-           "(VIX_LINK_STATIC=ON)\n";
-    out << "  -j, --jobs <n>        Parallel build jobs (default: CPU count, "
-           "clamped)\n";
+    out << "  --static              Request static linking (VIX_LINK_STATIC=ON)\n";
+    out << "  -j, --jobs <n>        Parallel build jobs (default: CPU count, clamped)\n";
     out << "  --clean               Force reconfigure (ignore cache/signature)\n";
     out << "  --no-cache            Disable signature cache shortcut\n";
-    out << "  --fast                Fast loop: if Ninja says up-to-date, exit "
-           "immediately\n";
-    out << "  --linker <mode>       auto|default|mold|lld (auto prefers mold "
-           "then lld)\n";
-    out << "  --launcher <mode>     auto|none|sccache|ccache (auto prefers "
-           "sccache)\n";
+    out << "  --fast                Fast loop: if Ninja says up-to-date, exit immediately\n";
+    out << "  --linker <mode>       auto|default|mold|lld (auto prefers mold then lld)\n";
+    out << "  --launcher <mode>     auto|none|sccache|ccache (auto prefers sccache)\n";
     out << "  --no-status           Disable NINJA_STATUS progress format\n";
     out << "  --no-up-to-date       Disable Ninja dry-run up-to-date detection\n";
-    out << "  -d, --dir <path>      Project directory (where CMakeLists.txt "
-           "lives)\n";
+    out << "  -d, --dir <path>      Project directory (where CMakeLists.txt lives)\n";
     out << "  -q, --quiet           Minimal output (still logs to files)\n";
     out << "  --targets             List detected cross toolchains on PATH\n";
-    out << "  --cmake-verbose       Show raw CMake configure output (no summary "
-           "filtering)\n";
-    out << "  --build-target <name> Build only a specific CMake target (ex: "
-           "blog)\n";
+    out << "  --cmake-verbose       Show raw CMake configure output (no summary filtering)\n";
+    out << "  --build-target <name> Build only a specific CMake target (ex: blog)\n";
     out << "  -h, --help            Show this help\n\n";
 
+    out << "Environment variables:\n";
+    out << "  VIX_BUILD_HEARTBEAT=1 Enable build heartbeat when no output is produced\n";
+    out << "                       for several seconds (disabled by default)\n\n";
+
     out << "Examples:\n";
     out << "  vix build\n";
     out << "  vix build --fast\n";
     out << "  vix build --preset release\n";
     out << "  vix build --preset release --static\n";
     out << "  vix build --launcher sccache --linker mold\n";
     out << "  vix build --target aarch64-linux-gnu\n";
-    out << "  vix build --preset release -target aarch64-linux-gnu\n";
+    out << "  vix build --preset release --target aarch64-linux-gnu\n";
     out << "  vix build --linker lld -- -DVIX_SYNC_BUILD_TESTS=ON\n";
-
+    out << "  VIX_BUILD_HEARTBEAT=1 vix build\n";
     out << "  vix build -j 8\n\n";
 
     out << "Logs:\n";
@@ -964,4 +959,5 @@ namespace vix::commands::BuildCommand
 
     return 0;
   }
+
 } // namespace vix::commands::BuildCommand