[lldb/Commands] Add ability to run shell command on the host.

[mib]

Summary

This patch introduces the (-h|--host) option to the platform shell
command. It allows the user to run shell commands from the host platform
(always available) without putting lldb in the background.

Since the default behaviour of platform shell is to run the command of
the selected platform, having such a choice can be quite handy when
debugging remote targets, for instances.

This patch also introduces a shell alias, to improve the command
discoverability and make it more convenient to use for the user.

rdar://62856024

Signed-off-by: Med Ismail Bennani <[e-mail]>

[jingham]

We certainly shouldn't duplicate the code for CommandObjectPlatformShell.

Why don't you just add a "m_use_host_platform" ivar to CommandObjectPlatformShell, and make two instances of CommandObjectPlatformShell, one with m_use_host_platform set to false and added as a sub-command of platform, and another instance with m_use_host_platform to true, and add that as a base command "shell"? Then you'd just have to make CommandObjectPlatformShell switch on m_use_host_platform and either get the selected platform or the host platform.

You'd also have to adjust the help string for one or the other of the commands, but CommandObject::SetHelp and SetHelpLong will allow you to do that.

[jingham]

I do something similar with CommandObjectThreadStepWithTypeAndScope so that I can share most of that command code, if you want to see an example of doing that.

[mib]

With the first implementation, I thought it'd be a good idea to have separate Command Objects for platform shell and shell because I was imagining the latter could be more "powerful": shell could have an interactive mode like the script command, which might not be as relevant for platform shell when debugging a remote target.

That was my original idea, but I agree we should avoid code duplication, so here is a different implementation following @jingham's suggestions. shell is an alias to platform shell -h -- in this case.

[mib]

It looks like command options are not supported on aliases that already have options:

(lldb) shell -t 1 -- sleep 5
zsh:1: command not found: -t
error: command returned with status 127

In this case, shell -t 1 -- sleep 5 expands to platform shell --host -- -t 1 -- sleep 5, and the option argument is passed as shell command instead of being parsed by lldb.

I might have done something wrong when creating the alias, so I'll skip the test_shell_timeout test until I come up with with a solution.

[JDevlieghere]

lldb/source/Commands/CommandObjectPlatform.cpp

1625 ↗

(On Diff #263005)

Is this only true for the alias?

lldb/test/API/commands/shell/TestShellCommand.py

28

I assume you copied this from TestPlatformCommand.py but if the test is skipped on Windows we can probably remove this line here.

On that note, I think we could avoid some code duplication by merging these tests and have the same tests, once called with shell and once with platform shell.

[mib]

lldb/source/Commands/CommandObjectPlatform.cpp

1625 ↗

(On Diff #263005)

I added this check because when using shell with no command, instead of showing the command usage, lldb tries running an empty command (if that makes sense) and showed the following error message:

(lldb) shell
error: executable doesn't exist: '(empty)'

[mib]

Merged the shell and platform shell test as @JDevlieghere suggested it.

[JDevlieghere]

LGTM

lldb/source/Commands/CommandObjectPlatform.cpp

1590 ↗

(On Diff #264270)

Should we reset the timeout too?

lldb/source/Commands/CMakeLists.txt

 lldb_tablegen(CommandOptions.inc -gen-lldb-option-defs
   SOURCE Options.td
   TARGET LLDBOptionsGen)
 
 add_lldb_library(lldbCommands
   CommandCompletions.cpp
   CommandObjectApropos.cpp
   CommandObjectBreakpoint.cpp
   CommandObjectBreakpointCommand.cpp
   CommandObjectCommands.cpp
   CommandObjectDisassemble.cpp
   CommandObjectExpression.cpp
   CommandObjectFrame.cpp
   CommandObjectGUI.cpp
   CommandObjectHelp.cpp
+  CommandObjectLanguage.cpp
   CommandObjectLog.cpp
   CommandObjectMemory.cpp
   CommandObjectMultiword.cpp
   CommandObjectPlatform.cpp
   CommandObjectPlugin.cpp
   CommandObjectProcess.cpp
   CommandObjectQuit.cpp
   CommandObjectRegister.cpp
   CommandObjectReproducer.cpp
   CommandObjectSettings.cpp
+  CommandObjectShell.cpp
   CommandObjectSource.cpp
   CommandObjectStats.cpp
   CommandObjectTarget.cpp
   CommandObjectThread.cpp
   CommandObjectType.cpp
   CommandObjectVersion.cpp
   CommandObjectWatchpoint.cpp
   CommandObjectWatchpointCommand.cpp
-  CommandObjectLanguage.cpp
 
   LINK_LIBS
     lldbBase
     lldbBreakpoint
     lldbCore
     lldbDataFormatters
     lldbExpression
     lldbHost

lldb/source/Commands/CommandObjectShell.h

+//===-- CommandObjectShell.h ---=--------------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLDB_SOURCE_INTERPRETER_COMMANDOBJECTSHELL_H
+#define LLDB_SOURCE_INTERPRETER_COMMANDOBJECTSHELL_H
+
+#include "lldb/Host/OptionParser.h"
+#include "lldb/Interpreter/CommandObject.h"
+#include "lldb/Interpreter/Options.h"
+#include "lldb/Utility/Timeout.h"
+
+namespace lldb_private {
+
+class CommandObjectShell : public CommandObjectRaw {
+public:
+  CommandObjectShell(CommandInterpreter &interpreter);
+
+  ~CommandObjectShell() override;
+
+  void HandleCompletion(CompletionRequest &request) override;
+
+  static void GenerateAdditionalHelpAvenuesMessage(
+      Stream *s, llvm::StringRef command, llvm::StringRef prefix,
+      llvm::StringRef subcommand, bool include_upropos = true,
+      bool include_type_lookup = true);
+
+  class CommandOptions : public Options {
+  public:
+    CommandOptions() : Options() {}
+
+    ~CommandOptions() override {}
+
+    Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
+                          ExecutionContext *execution_context) override {
+      Status error;
+
+      const char short_option = (char)GetDefinitions()[option_idx].short_option;
+
+      switch (short_option) {
+      case 't':
+        uint32_t timeout_sec;
+        if (option_arg.getAsInteger(10, timeout_sec))
+          error.SetErrorStringWithFormat(
+              "could not convert \"%s\" to a numeric value.",
+              option_arg.str().c_str());
+        else
+          m_timeout = std::chrono::seconds(timeout_sec);
+        break;
+      default:
+        llvm_unreachable("Unimplemented option");
+      }
+
+      return error;
+    }
+
+    void OptionParsingStarting(ExecutionContext *execution_context) override {}
+
+    llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
+
+    // Instance variables to hold the values for command options.
+
+    Timeout<std::micro> m_timeout = std::chrono::seconds(10);
+  };
+
+  Options *GetOptions() override { return &m_options; }
+
+protected:
+  bool DoExecute(llvm::StringRef raw_command_line,
+                 CommandReturnObject &result) override;
+
+private:
+  CommandOptions m_options;
+};
+
+} // namespace lldb_private
+
+#endif // LLDB_SOURCE_INTERPRETER_COMMANDOBJECTSHELL_H

lldb/source/Commands/CommandObjectShell.cpp

+#include "CommandObjectShell.h"
+#include "lldb/Interpreter/CommandInterpreter.h"
+#include "lldb/Interpreter/CommandReturnObject.h"
+
+using namespace lldb;
+using namespace lldb_private;
+
+// CommandObjectShell
+
+CommandObjectShell::CommandObjectShell(CommandInterpreter &interpreter)
+    : CommandObjectRaw(interpreter, "shell", "Run a shell command on the host.",
+                       "shell <shell-command>", 0),
+      m_options() {}
+
+CommandObjectShell::~CommandObjectShell() = default;
+
+// "shell"
+#define LLDB_OPTIONS_shell
+#include "CommandOptions.inc"
+
+llvm::ArrayRef<OptionDefinition>
+CommandObjectShell::CommandOptions::GetDefinitions() {
+  return llvm::makeArrayRef(g_shell_options);
+}
+
+bool CommandObjectShell::DoExecute(llvm::StringRef raw_command_line,
+                                   CommandReturnObject &result) {
+  ExecutionContext exe_ctx = GetCommandInterpreter().GetExecutionContext();
+  m_options.NotifyOptionParsingStarting(&exe_ctx);
+
+  // Print out an usage syntax on an empty command line.
+  if (raw_command_line.empty()) {
+    result.GetOutputStream().Printf("%s\n", this->GetSyntax().str().c_str());
+    return true;
+  }
+
+  OptionsWithRaw args(raw_command_line);
+  const char *expr = args.GetRawPart().c_str();
+
+  if (args.HasArgs())
+    if (!ParseOptions(args.GetArgs(), result))
+      return false;
+
+  PlatformSP platform_sp(Platform::GetHostPlatform());
+  Status error;
+  if (platform_sp) {
+    FileSpec working_dir{};
+    std::string output;
+    int status = -1;
+    int signo = -1;
+    error = (platform_sp->RunShellCommand(expr, working_dir, &status, &signo,
+                                          &output, m_options.m_timeout));
+    if (!output.empty())
+      result.GetOutputStream().PutCString(output);
+    if (status > 0) {
+      if (signo > 0) {
+        const char *signo_cstr = Host::GetSignalAsCString(signo);
+        if (signo_cstr)
+          result.GetOutputStream().Printf(
+              "error: command returned with status %i and signal %s\n", status,
+              signo_cstr);
+        else
+          result.GetOutputStream().Printf(
+              "error: command returned with status %i and signal %i\n", status,
+              signo);
+      } else
+        result.GetOutputStream().Printf(
+            "error: command returned with status %i\n", status);
+    }
+  } else {
+    result.GetOutputStream().Printf(
+        "error: cannot run remote shell commands without a platform\n");
+    error.SetErrorString(
+        "error: cannot run remote shell commands without a platform");
+  }
+
+  if (error.Fail()) {
+    result.AppendError(error.AsCString());
+    result.SetStatus(eReturnStatusFailed);
+  } else {
+    result.SetStatus(eReturnStatusSuccessFinishResult);
+  }
+  return true;
+}
+
+void CommandObjectShell::HandleCompletion(CompletionRequest &request) {
+  // Return the completions of the commands in the help system:
+  if (request.GetCursorIndex() == 0) {
+    m_interpreter.HandleCompletionMatches(request);
+    return;
+  }
+  CommandObject *cmd_obj =
+      m_interpreter.GetCommandObject(request.GetParsedLine()[0].ref());
+
+  // The command that they are getting help on might be ambiguous, in which
+  // case we should complete that, otherwise complete with the command the
+  // user is getting help on...
+
+  if (cmd_obj) {
+    request.ShiftArguments();
+    cmd_obj->HandleCompletion(request);
+    return;
+  }
+  m_interpreter.HandleCompletionMatches(request);
+}

lldb/source/Commands/Options.td

let Command = "script add" in {
   Desc<"Name of the Python class to bind to this command name.">;
   def script_add_help : Option<"help", "h">, Group<1>, Arg<"HelpText">,
   Desc<"The help text to display for this command.">;
   def script_add_synchronicity : Option<"synchronicity", "s">,
     EnumArg<"ScriptedCommandSynchronicity", "ScriptSynchroType()">,
     Desc<"Set the synchronicity of this command's executions with regard to "
     "LLDB event system.">;
 }
+
+let Command = "shell" in {
+  def shell_timeout : Option<"timeout", "t">, Arg<"Value">,
+    Desc<"Seconds to wait for the host to finish running the command.">;
+}
+
 let Command = "source info" in {
   def source_info_count : Option<"count", "c">, Arg<"Count">,
     Desc<"The number of line entries to display.">;
   def source_info_shlib : Option<"shlib", "s">, Groups<[1,2]>, Arg<"ShlibName">,
     Completion<"Module">, Desc<"Look up the source in the given module or "
     "shared library (can be specified more than once).">;
   def source_info_file : Option<"file", "f">, Group<1>, Arg<"Filename">,
     Completion<"SourceFile">, Desc<"The file from which to display source.">;

lldb/source/Interpreter/CommandInterpreter.cpp

 #include "Commands/CommandObjectMemory.h"
 #include "Commands/CommandObjectPlatform.h"
 #include "Commands/CommandObjectPlugin.h"
 #include "Commands/CommandObjectProcess.h"
 #include "Commands/CommandObjectQuit.h"
 #include "Commands/CommandObjectRegister.h"
 #include "Commands/CommandObjectReproducer.h"
 #include "Commands/CommandObjectSettings.h"
+#include "Commands/CommandObjectShell.h"
 #include "Commands/CommandObjectSource.h"
 #include "Commands/CommandObjectStats.h"
 #include "Commands/CommandObjectTarget.h"
 #include "Commands/CommandObjectThread.h"
 #include "Commands/CommandObjectType.h"
 #include "Commands/CommandObjectVersion.h"
 #include "Commands/CommandObjectWatchpoint.h"
 
void CommandInterpreter::LoadCommandDictionary() {
   m_command_dict["register"] =
       CommandObjectSP(new CommandObjectRegister(*this));
   m_command_dict["reproducer"] =
       CommandObjectSP(new CommandObjectReproducer(*this));
   m_command_dict["script"] =
       CommandObjectSP(new CommandObjectScript(*this, script_language));
   m_command_dict["settings"] =
       CommandObjectSP(new CommandObjectMultiwordSettings(*this));
+  m_command_dict["shell"] = CommandObjectSP(new CommandObjectShell(*this));
   m_command_dict["source"] =
       CommandObjectSP(new CommandObjectMultiwordSource(*this));
   m_command_dict["statistics"] = CommandObjectSP(new CommandObjectStats(*this));
   m_command_dict["target"] =
       CommandObjectSP(new CommandObjectMultiwordTarget(*this));
   m_command_dict["thread"] =
       CommandObjectSP(new CommandObjectMultiwordThread(*this));
   m_command_dict["type"] = CommandObjectSP(new CommandObjectType(*this));

lldb/test/API/commands/shell/TestShellCommand.py

+"""
+Test the lldb host shell command.
+"""
+
+
+
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test import lldbutil
+
+
+class ShellCommandTestCase(TestBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    @no_debug_info_test
+    def test_help_platform(self):
+        self.expect("help shell", substrs=["shell <shell-command>",
+                                           "-t <value> ( --timeout <value> )"])
+
+    @expectedFailureAll(oslist=["windows"])
+    @no_debug_info_test
+    def test_shell(self):
+        """ Test that the shell command can invoke ls. """
+        triple = self.dbg.GetSelectedPlatform().GetTriple()
+        if re.match(".*-.*-windows", triple):
+            self.expect("shell dir c:\\", substrs=["Windows", "Program Files"])
+        elif re.match(".*-.*-.*-android", triple):
+            self.expect("shell ls /",
+                substrs=["cache", "dev", "system"])
+        else:
+            self.expect("shell ls /", substrs=["dev", "tmp", "usr"])
+
+    @no_debug_info_test
+    def test_shell_builtin(self):
+        """ Test a shell built-in command (echo) """
+        self.expect("shell echo hello lldb",
+                    substrs=["hello lldb"])
+
+    @no_debug_info_test
+    def test_shell_timeout(self):
+        """ Test a shell built-in command (sleep) that times out """
+        self.expect("shell -t 1 --  sleep 3", error=True, substrs=[
+                    "error: timed out waiting for shell command to complete"])