https://github.com/dmpots created
https://github.com/llvm/llvm-project/pull/134418
This commit adds three new commands for managing plugins. The `list` command
will show which plugins are currently registered and their enabled state. The
`enable` and `disable` commands can be used to enable or disable plugins.
A disabled plugin will not show up to the PluginManager when it iterates over
available plugins of a particular type.
The purpose of these commands is to provide more visibility into registered
plugins and allow users to disable plugins for experimental perf reasons.
There are a few limitations to the current implementation
1. Only SystemRuntime plugins are currently supported. We can easily extend
the existing implementation to support more types.
2. Only "statically" know plugin types are supported (i.e. those managed by
the PluginManager and not from `plugin load`). It is possibly we could support
dynamic plugins as well, but I have not looked into it yet.
>From e240bda8fcea9db4d9c456929ba811feb8d4152b Mon Sep 17 00:00:00 2001
From: David Peixotto <p...@meta.com>
Date: Tue, 11 Mar 2025 13:02:14 -0700
Subject: [PATCH] Add commands to list/enable/disable plugins
This commit adds three new commands for managing plugins. The `list`
command will show which plugins are currently registered and their
enabled state. The `enable` and `disable` commands can be used to
enable or disable plugins.
A disabled plugin will not show up to the PluginManager when it iterates
over available plugins of a particular type.
The purpose of these commands is to provide more visibility into registered
plugins and allow users to disable plugins for experimental perf reasons.
There are a few limitations to the current implementation
1. Only SystemRuntime plugins are currently supported. We can easily
extend the existing implementation to support more types.
2. Only "statically" know plugin types are supported (i.e. those
managed by the PluginManager and not from `plugin load`). It is
possibly we could support dynamic plugins as well, but I have
not looked into it yet.
---
lldb/source/Commands/CommandObjectPlugin.cpp | 335 ++++++++++++++++++
.../source/Commands/CommandObjectSettings.cpp | 1 +
lldb/source/Commands/Options.td | 5 +
.../command-plugin-enable+disable.test | 53 +++
.../Shell/Commands/command-plugin-list.test | 51 +++
5 files changed, 445 insertions(+)
create mode 100644 lldb/test/Shell/Commands/command-plugin-enable+disable.test
create mode 100644 lldb/test/Shell/Commands/command-plugin-list.test
diff --git a/lldb/source/Commands/CommandObjectPlugin.cpp
b/lldb/source/Commands/CommandObjectPlugin.cpp
index f3108b8a768d2..68261d24ffe1f 100644
--- a/lldb/source/Commands/CommandObjectPlugin.cpp
+++ b/lldb/source/Commands/CommandObjectPlugin.cpp
@@ -7,8 +7,11 @@
//===----------------------------------------------------------------------===//
#include "CommandObjectPlugin.h"
+#include "lldb/Core/PluginManager.h"
+#include "lldb/Host/OptionParser.h"
#include "lldb/Interpreter/CommandInterpreter.h"
#include "lldb/Interpreter/CommandReturnObject.h"
+#include "llvm/Support/GlobPattern.h"
using namespace lldb;
using namespace lldb_private;
@@ -46,12 +49,344 @@ class CommandObjectPluginLoad : public CommandObjectParsed
{
}
};
+namespace {
+#define LLDB_OPTIONS_plugin_list
+#include "CommandOptions.inc"
+
+// These option definitions are shared by the plugin list/enable/disable
+// commands.
+class PluginListCommandOptions : public Options {
+public:
+ PluginListCommandOptions() = default;
+
+ ~PluginListCommandOptions() override = default;
+
+ Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
+ ExecutionContext *execution_context) override {
+ Status error;
+ const int short_option = m_getopt_table[option_idx].val;
+
+ switch (short_option) {
+ case 'x':
+ m_exact_name_match = true;
+ break;
+ default:
+ llvm_unreachable("Unimplemented option");
+ }
+
+ return error;
+ }
+
+ void OptionParsingStarting(ExecutionContext *execution_context) override {
+ m_exact_name_match = false;
+ }
+
+ llvm::ArrayRef<OptionDefinition> GetDefinitions() override {
+ return llvm::ArrayRef(g_plugin_list_options);
+ }
+
+ // Instance variables to hold the values for command options.
+ bool m_exact_name_match = false;
+};
+
+// Define some data structures to describe known plugin "namespaces".
+// The PluginManager is organized into a series of static functions
+// that operate on different types of plugin. For example SystemRuntime
+// and ObjectFile plugins.
+//
+// The namespace name is used a prefix when matching plugin names. For example,
+// if we have an "elf" plugin in the "object-file" namespace then we will
+// match a plugin name pattern against the "object-file.elf" name.
+//
+// The plugin namespace here is used so we can operate on all the plugins
+// of a given type so it is easy to enable or disable them as a group.
+using GetPluginInfo = std::function<std::vector<RegisteredPluginInfo>()>;
+using SetPluginEnabled = std::function<bool(llvm::StringRef, bool)>;
+struct PluginNamespace {
+ llvm::StringRef name;
+ GetPluginInfo get_info;
+ SetPluginEnabled set_enabled;
+};
+
+// Currently supported set of plugin namespaces. This will be expanded
+// over time.
+PluginNamespace PluginNamespaces[] = {
+ {"system-runtime", PluginManager::GetSystemRuntimePluginInfo,
+ PluginManager::SetSystemRuntimePluginEnabled}};
+
+// Helper function to perform an action on each matching plugin.
+// The action callback is given the containing namespace along with plugin info
+// for each matching plugin.
+static int ActOnMatchingPlugins(
+ llvm::GlobPattern pattern,
+ std::function<void(const PluginNamespace &plugin_namespace,
+ const std::vector<RegisteredPluginInfo> &plugin_info)>
+ action) {
+ int num_matching = 0;
+
+ for (const PluginNamespace &plugin_namespace : PluginNamespaces) {
+ std::vector<RegisteredPluginInfo> all_plugins =
plugin_namespace.get_info();
+ std::vector<RegisteredPluginInfo> matching_plugins;
+ for (const RegisteredPluginInfo &plugin_info : all_plugins) {
+ std::string qualified_name =
+ (plugin_namespace.name + "." + plugin_info.name).str();
+ if (pattern.match(qualified_name)) {
+ matching_plugins.push_back(plugin_info);
+ }
+ }
+
+ if (!matching_plugins.empty()) {
+ num_matching += matching_plugins.size();
+ action(plugin_namespace, matching_plugins);
+ }
+ }
+
+ return num_matching;
+}
+
+// Return a string in glob syntax for matching plugins.
+static std::string GetPluginNamePatternString(llvm::StringRef user_input,
+ bool add_default_glob) {
+ std::string pattern_str;
+ if (user_input.empty())
+ pattern_str = "*";
+ else
+ pattern_str = user_input;
+
+ if (add_default_glob && pattern_str != "*") {
+ pattern_str = "*" + pattern_str + "*";
+ }
+
+ return pattern_str;
+}
+
+// Attempts to create a glob pattern for a plugin name based on plugin command
+// input. Writes an error message to the `result` object if the glob cannot be
+// created successfully.
+//
+// The `glob_storage` is used to hold the string data for the glob pattern. The
+// llvm::GlobPattern only contains pointers into the string data so we need a
+// stable location that can outlive the glob pattern itself.
+std::optional<llvm::GlobPattern>
+TryCreatePluginPattern(const char *plugin_command_name, const Args &command,
+ const PluginListCommandOptions &options,
+ CommandReturnObject &result, std::string &glob_storage)
{
+ size_t argc = command.GetArgumentCount();
+ if (argc > 1) {
+ result.AppendErrorWithFormat("'%s' requires one argument",
+ plugin_command_name);
+ return {};
+ }
+
+ llvm::StringRef user_pattern;
+ if (argc == 1) {
+ user_pattern = command[0].ref();
+ }
+
+ glob_storage =
+ GetPluginNamePatternString(user_pattern, !options.m_exact_name_match);
+
+ auto glob_pattern = llvm::GlobPattern::create(glob_storage);
+
+ if (auto error = glob_pattern.takeError()) {
+ std::string error_message =
+ (llvm::Twine("Invalid plugin glob pattern: '") + glob_storage +
+ "': " + llvm::toString(std::move(error)))
+ .str();
+ result.AppendError(error_message);
+ return {};
+ }
+
+ return *glob_pattern;
+}
+
+// Call the "SetEnable" function for each matching plugins.
+// Used to share the majority of the code between the enable
+// and disable commands.
+int SetEnableOnMatchingPlugins(const llvm::GlobPattern &pattern,
+ CommandReturnObject &result, bool enabled) {
+ return ActOnMatchingPlugins(
+ pattern, [&](const PluginNamespace &plugin_namespace,
+ const std::vector<RegisteredPluginInfo> &plugins) {
+ result.AppendMessage(plugin_namespace.name);
+ for (const auto &plugin : plugins) {
+ if (!plugin_namespace.set_enabled(plugin.name, enabled)) {
+ result.AppendErrorWithFormat("failed to enable plugin %s.%s",
+ plugin_namespace.name.data(),
+ plugin.name.data());
+ continue;
+ }
+
+ result.AppendMessageWithFormat(
+ " %s %-30s %s\n", enabled ? "[+]" : "[-]", plugin.name.data(),
+ plugin.description.data());
+ }
+ });
+}
+} // namespace
+
+class CommandObjectPluginList : public CommandObjectParsed {
+public:
+ CommandObjectPluginList(CommandInterpreter &interpreter)
+ : CommandObjectParsed(interpreter, "plugin list",
+ "Report info about registered LLDB plugins.",
+ nullptr) {
+ AddSimpleArgumentList(eArgTypePlugin);
+ SetHelpLong(R"(
+Display information about registered plugins.
+The plugin information is formatted as shown below
+
+ <plugin-namespace>
+ [+] <plugin-name> Plugin #1 description
+ [-] <plugin-name> Plugin #2 description
+
+An enabled plugin is marked with [+] and a disabled plugin is marked with [-].
+
+Selecting plugins
+------------------
+plugin list [<plugin-namespace>.][<plugin-name>]
+
+Plugin names are specified using glob patterns. The pattern will be matched
+against the plugins fully qualified name, which is composed of the namespace,
+followed by a '.', followed by the plugin name.
+
+When no arguments are given the plugin selection string is the wildcard '*'.
+By default wildcards are added around the input to enable searching by
+substring. You can prevent these implicit wild cards by using the
+-x flag.
+
+Examples
+-----------------
+List all plugins in the system-runtime namespace
+
+ (lldb) plugin list system-runtime.*
+
+List all plugins containing the string foo
+
+ (lldb) plugin list foo
+
+This is equivalent to
+
+ (lldb) plugin list *foo*
+
+List only a plugin matching a fully qualified name exactly
+
+ (lldb) plugin list -x system-runtime.foo
+)");
+ }
+
+ ~CommandObjectPluginList() override = default;
+
+ Options *GetOptions() override { return &m_options; }
+
+protected:
+ void DoExecute(Args &command, CommandReturnObject &result) override {
+ std::string glob_storage;
+ std::optional<llvm::GlobPattern> plugin_glob = TryCreatePluginPattern(
+ "plugin list", command, m_options, result, glob_storage);
+
+ if (!plugin_glob) {
+ assert(!result.Succeeded());
+ return;
+ }
+
+ int num_matching = ActOnMatchingPlugins(
+ *plugin_glob, [&](const PluginNamespace &plugin_namespace,
+ const std::vector<RegisteredPluginInfo> &plugins) {
+ result.AppendMessage(plugin_namespace.name);
+ for (auto &plugin : plugins) {
+ result.AppendMessageWithFormat(
+ " %s %-30s %s\n", plugin.enabled ? "[+]" : "[-]",
+ plugin.name.data(), plugin.description.data());
+ }
+ });
+
+ if (num_matching == 0) {
+ result.AppendErrorWithFormat("Found no matching plugins");
+ }
+ }
+
+ PluginListCommandOptions m_options;
+};
+
+class CommandObjectPluginEnable : public CommandObjectParsed {
+public:
+ CommandObjectPluginEnable(CommandInterpreter &interpreter)
+ : CommandObjectParsed(interpreter, "plugin enable",
+ "Enable registered LLDB plugins.", nullptr) {
+ AddSimpleArgumentList(eArgTypePlugin);
+ }
+
+ ~CommandObjectPluginEnable() override = default;
+
+ Options *GetOptions() override { return &m_options; }
+
+protected:
+ void DoExecute(Args &command, CommandReturnObject &result) override {
+ std::string glob_storage;
+ std::optional<llvm::GlobPattern> plugin_glob = TryCreatePluginPattern(
+ "plugin enable", command, m_options, result, glob_storage);
+
+ if (!plugin_glob) {
+ assert(!result.Succeeded());
+ return;
+ }
+
+ int num_matching = SetEnableOnMatchingPlugins(*plugin_glob, result, true);
+
+ if (num_matching == 0) {
+ result.AppendErrorWithFormat("Found no matching plugins to enable");
+ }
+ }
+
+ PluginListCommandOptions m_options;
+};
+
+class CommandObjectPluginDisable : public CommandObjectParsed {
+public:
+ CommandObjectPluginDisable(CommandInterpreter &interpreter)
+ : CommandObjectParsed(interpreter, "plugin disable",
+ "Disable registered LLDB plugins.", nullptr) {
+ AddSimpleArgumentList(eArgTypePlugin);
+ }
+
+ ~CommandObjectPluginDisable() override = default;
+
+ Options *GetOptions() override { return &m_options; }
+
+protected:
+ void DoExecute(Args &command, CommandReturnObject &result) override {
+ std::string glob_storage;
+ std::optional<llvm::GlobPattern> plugin_glob = TryCreatePluginPattern(
+ "plugin disable", command, m_options, result, glob_storage);
+
+ if (!plugin_glob) {
+ assert(!result.Succeeded());
+ return;
+ }
+
+ int num_matching = SetEnableOnMatchingPlugins(*plugin_glob, result, false);
+
+ if (num_matching == 0) {
+ result.AppendErrorWithFormat("Found no matching plugins to disable");
+ }
+ }
+
+ PluginListCommandOptions m_options;
+};
+
CommandObjectPlugin::CommandObjectPlugin(CommandInterpreter &interpreter)
: CommandObjectMultiword(interpreter, "plugin",
"Commands for managing LLDB plugins.",
"plugin <subcommand> [<subcommand-options>]") {
LoadSubCommand("load",
CommandObjectSP(new CommandObjectPluginLoad(interpreter)));
+ LoadSubCommand("list",
+ CommandObjectSP(new CommandObjectPluginList(interpreter)));
+ LoadSubCommand("enable",
+ CommandObjectSP(new CommandObjectPluginEnable(interpreter)));
+ LoadSubCommand("disable",
+ CommandObjectSP(new CommandObjectPluginDisable(interpreter)));
}
CommandObjectPlugin::~CommandObjectPlugin() = default;
diff --git a/lldb/source/Commands/CommandObjectSettings.cpp
b/lldb/source/Commands/CommandObjectSettings.cpp
index 7bbb0dd567ab1..1b60d441264d6 100644
--- a/lldb/source/Commands/CommandObjectSettings.cpp
+++ b/lldb/source/Commands/CommandObjectSettings.cpp
@@ -15,6 +15,7 @@
#include "lldb/Interpreter/CommandInterpreter.h"
#include "lldb/Interpreter/CommandOptionArgumentTable.h"
#include "lldb/Interpreter/CommandReturnObject.h"
+#include "lldb/Interpreter/OptionValue.h"
#include "lldb/Interpreter/OptionValueProperties.h"
using namespace lldb;
diff --git a/lldb/source/Commands/Options.td b/lldb/source/Commands/Options.td
index cc579d767eb06..ac8fd78f4a894 100644
--- a/lldb/source/Commands/Options.td
+++ b/lldb/source/Commands/Options.td
@@ -683,6 +683,11 @@ let Command = "platform shell" in {
Desc<"Shell interpreter path. This is the binary used to run the
command.">;
}
+let Command = "plugin list" in {
+ def plugin_info_exact : Option<"exact", "x">,
+ Desc<"Do not add implicit * glob around plugin
name">;
+}
+
let Command = "process launch" in {
def process_launch_stop_at_entry : Option<"stop-at-entry", "s">,
Desc<"Stop at the entry point of the program when launching a process.">;
diff --git a/lldb/test/Shell/Commands/command-plugin-enable+disable.test
b/lldb/test/Shell/Commands/command-plugin-enable+disable.test
new file mode 100644
index 0000000000000..fcc1994b7697c
--- /dev/null
+++ b/lldb/test/Shell/Commands/command-plugin-enable+disable.test
@@ -0,0 +1,53 @@
+# This test validates the plugin enable and disable commands.
+# Currently it works only for system-runtime plugins and we only have one
+# system runtime plugin so testing is a bit limited.
+#
+# Note that commands that return errors will stop running a script, so we
+# have new RUN lines for any command that is expected to return an error.
+
+# RUN: %lldb -s %s -o exit 2>&1 | FileCheck %s
+
+# Test plugin list shows the default state which is expected to be enabled.
+plugin list
+# CHECK-LABEL: plugin list
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin disable disables a plugin.
+plugin disable systemruntime-macosx
+# CHECK-LABEL: plugin disable systemruntime-macosx
+# CHECK: system-runtime
+# CHECK: [-] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Make sure plugin list shows it disabled as well.
+plugin list
+# CHECK: system-runtime
+# CHECK: [-] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin enable re-enables a plugin.
+plugin enable systemruntime-macosx
+# CHECK-LABEL: plugin enable systemruntime-macosx
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Make sure plugin list shows it enabled as well.
+plugin list
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin disable with wildcard works.
+plugin disable system*
+# CHECK-LABEL: plugin disable system*
+# CHECK: system-runtime
+# CHECK: [-] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin enable with wildcard works.
+plugin enable system*
+# CHECK-LABEL: plugin enable system*
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin enable/disable for unknown plugin returns an error.
+# RUN: %lldb -o "plugin enable some-plugin-that-does-not-exist" 2>&1 |
FileCheck %s --check-prefix=ERROR_PLUGIN_NOT_FOUND
+# RUN: %lldb -o "plugin disable some-plugin-that-does-not-exist" 2>&1 |
FileCheck %s --check-prefix=ERROR_PLUGIN_NOT_FOUND
+# ERROR_PLUGIN_NOT_FOUND: error: Found no matching plugins
diff --git a/lldb/test/Shell/Commands/command-plugin-list.test
b/lldb/test/Shell/Commands/command-plugin-list.test
new file mode 100644
index 0000000000000..7e5c9c671a783
--- /dev/null
+++ b/lldb/test/Shell/Commands/command-plugin-list.test
@@ -0,0 +1,51 @@
+# This test validates the plugin list command.
+# Currently it works only for system-runtime plugins and we only have one
+# system runtime plugin so testing is a bit limited.
+#
+# Note that commands that return errors will stop running a script, so we
+# have new RUN lines for any command that is expected to return an error.
+
+# RUN: %lldb -s %s -o exit 2>&1 | FileCheck %s
+
+# Test plugin list without an argument will list all plugins.
+plugin list
+# CHECK-LABEL: plugin list
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin list with an argument will match a plugin name by substring.
+plugin list macosx
+# CHECK-LABEL: plugin list macosx
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin exact list works with fully qualified name.
+plugin list -x system-runtime.systemruntime-macosx
+# CHECK-LABEL: plugin list -x system-runtime.systemruntime-macosx
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin glob list works with fully qualified name.
+plugin list system-runtime.systemruntime-macosx
+# CHECK-LABEL: plugin list system-runtime.systemruntime-macosx
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin exact list still allows glob patterns.
+plugin list -x system*
+# CHECK-LABEL: plugin list -x system*
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin glob list still allows glob patterns.
+plugin list system-runtime.*
+# CHECK-LABEL: plugin list system-runtime.*
+# CHECK: system-runtime
+# CHECK: [+] systemruntime-macosx System runtime plugin for Mac OS
X native libraries
+
+# Test plugin list can disable implicit glob patterns.
+# RUN: %lldb -o "plugin list -x macosx" 2>&1 | FileCheck %s
--check-prefix=ERROR_PLUGIN_NOT_FOUND
+
+# Test plugin list for unknown plugin returns an error.
+# RUN: %lldb -o "plugin list some-plugin-that-does-not-exist" 2>&1 | FileCheck
%s --check-prefix=ERROR_PLUGIN_NOT_FOUND
+# ERROR_PLUGIN_NOT_FOUND: error: Found no matching plugins
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
