From e5323ec487f66c6fdf868dc32253918f9b9c0459 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Wed, 3 Nov 2021 12:20:36 +0100
Subject: [PATCH] [libcalamares] Expand Runner documentation

- document a bit more of the methods
- provide convenience method enableOutputProcessing() alongside
  an explicit setter; adjust tests to the changed API.
- add an executable() information method.
---
 src/libcalamares/utils/Runner.h  | 23 ++++++++++++++++++++---
 src/libcalamares/utils/Tests.cpp |  6 +++---
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/src/libcalamares/utils/Runner.h b/src/libcalamares/utils/Runner.h
index 2fe550e7f..47dba5b73 100644
--- a/src/libcalamares/utils/Runner.h
+++ b/src/libcalamares/utils/Runner.h
@@ -32,10 +32,15 @@ using ProcessResult = CalamaresUtils::ProcessResult;
 /** @brief A Runner wraps a process and handles running it and processing output
  *
  * This is basically a QProcess, but handles both running in the
- * host system (natively) or in the target (by calling chroot).
+ * host system (through env(1)) or in the target (by calling chroot(8)).
  * It has an output signal that handles output one line at a time
  * (unlike QProcess that lets you do the buffering yourself).
  * This output processing is only enabled if you do so explicitly.
+ *
+ * Use the set*() methods to configure the runner.
+ *
+ * If you call enableOutputProcessing(), then you can connect to
+ * the output() signal to receive each line (including trailing newline!).
  */
 class Runner : public QObject
 {
@@ -86,14 +91,26 @@ public:
         m_input = stdin;
         return *this;
     }
-
-    Runner& enableOutputProcessing( bool enable = true )
+    Runner& setOutputProcessing( bool enable )
     {
         m_output = enable;
         return *this;
     }
 
+    Runner& enableOutputProcessing()
+    {
+        m_output = true;
+        return *this;
+    }
+
     ProcessResult run();
+    /** @brief The executable (argv[0]) that this runner will run
+     *
+     * This is the first element of the command; it does not include
+     * env(1) or chroot(8) which are injected when actually running
+     * the command.
+     */
+    QString executable() const { return m_command.isEmpty() ? QString() : m_command.first(); }
 
 signals:
     void output( QString line );
diff --git a/src/libcalamares/utils/Tests.cpp b/src/libcalamares/utils/Tests.cpp
index 1edae6e31..12b72cb4c 100644
--- a/src/libcalamares/utils/Tests.cpp
+++ b/src/libcalamares/utils/Tests.cpp
@@ -892,7 +892,7 @@ LibCalamaresTests::testRunnerOutput()
     {
         Calamares::Utils::Runner r( { "ls", "-d", "." } );
         QSignalSpy spy( &r, &decltype( r )::output );
-        r.enableOutputProcessing( true );
+        r.enableOutputProcessing();
 
         auto result = r.run();
         QCOMPARE( result.getExitCode(), 0 );
@@ -904,7 +904,7 @@ LibCalamaresTests::testRunnerOutput()
     {
         Calamares::Utils::Runner r( { "cat" } );
         QSignalSpy spy( &r, &decltype( r )::output );
-        r.enableOutputProcessing( true ).setInput( QStringLiteral( "hello\nworld\n\n!\n" ) );
+        r.enableOutputProcessing().setInput( QStringLiteral( "hello\nworld\n\n!\n" ) );
 
         {
             auto result = r.run();
@@ -927,7 +927,7 @@ LibCalamaresTests::testRunnerOutput()
         QStringList collectedOutput;
 
         Calamares::Utils::Runner r( { "cat" } );
-        r.enableOutputProcessing( true ).setInput( QStringLiteral( "hello\nworld\n\n!\n" ) );
+        r.enableOutputProcessing().setInput( QStringLiteral( "hello\nworld\n\n!\n" ) );
         QObject::connect( &r, &decltype( r )::output, [&collectedOutput]( QString s ) { collectedOutput << s; } );
 
         {