[lldb/script] Add scripting extension template generator (#209647)
This patch adds a `scripting extension generate <ExtensionType>...` command that introspects a Python extension base class and emits a skeleton subclass with `# TODO: Implement` stubs for its abstract methods (or, with `-a`, every method), then opens the result in an editor. Generated imports use `from <module> import <class>`, and the generated `__init__` forwards its arguments to `super().__init__(...)` since every base class relies on its constructor to set up attributes (`self.target`, `self.process`, ...) that inherited, non-overridden methods depend on. When the host can't open an external editor (e.g. non-macOS), the command reports that as a message rather than an error, since the file is already written. To catch regressions in the generator itself instead of just checking that a file was produced, this patch adds `TestScriptingExtensionGenerate.py`, which generates a template for every extension kind on the fly and drives it through a live lldb session (`process launch -C`, `breakpoint set -P`, `target stop-hook add -P`, etc.). Signed-off-by: Med Ismail Bennani <ismail@bennani.ma> (cherry picked from commit c4962f5721a36e198234019b846d3788738f766a)
This commit is contained in:
1 parent
e28ea20ce0
commit
3df0bbdc25
13 files changed
+961
-12
No files matched your search
@@ -36,11 +36,13 @@
|
||||
#include "lldb/Target/ThreadPlan.h"
|
||||
#include "lldb/Utility/Instrumentation.h"
|
||||
#include "lldb/Utility/LLDBLog.h"
|
||||
#include "lldb/Utility/StructuredData.h"
|
||||
#include "lldb/Utility/Timer.h"
|
||||
#include "lldb/ValueObject/ValueObject.h"
|
||||
#include "lldb/lldb-enumerations.h"
|
||||
#include "lldb/lldb-forward.h"
|
||||
#include "llvm/ADT/STLExtras.h"
|
||||
#include "llvm/ADT/StringExtras.h"
|
||||
#include "llvm/ADT/StringRef.h"
|
||||
#include "llvm/Support/Error.h"
|
||||
#include "llvm/Support/ErrorExtras.h"
|
||||
@@ -265,6 +267,363 @@ StructuredData::DictionarySP ScriptInterpreterPython::GetInterpreterInfo() {
|
||||
return info_json.CreateStructuredDictionary();
|
||||
}
|
||||
|
||||
llvm::Expected<std::string> ScriptInterpreterPython::ExtensionToImportPath(
|
||||
lldb::ScriptedExtension extension) {
|
||||
switch (extension) {
|
||||
case eScriptedExtensionOperatingSystem:
|
||||
return "lldb.plugins.operating_system";
|
||||
case eScriptedExtensionScriptedPlatform:
|
||||
return "lldb.plugins.scripted_platform";
|
||||
case eScriptedExtensionScriptedProcess:
|
||||
return "lldb.plugins.scripted_process";
|
||||
case eScriptedExtensionScriptedHook:
|
||||
return "lldb.plugins.scripted_hook";
|
||||
case eScriptedExtensionScriptedBreakpointResolver:
|
||||
return "lldb.plugins.scripted_breakpoint";
|
||||
case eScriptedExtensionScriptedThreadPlan:
|
||||
return "lldb.plugins.scripted_thread_plan";
|
||||
case eScriptedExtensionScriptedFrameProvider:
|
||||
return "lldb.plugins.scripted_frame_provider";
|
||||
case eScriptedExtensionScriptedThread:
|
||||
case eScriptedExtensionScriptedFrame:
|
||||
return "lldb.plugins.scripted_process";
|
||||
case eScriptedExtensionScriptedStackFrameRecognizer:
|
||||
return "lldb.plugins.scripted_stackframe_recognizer";
|
||||
case eScriptedExtensionInvalid:
|
||||
return llvm::createStringError("invalid extension name");
|
||||
}
|
||||
return llvm::createStringError("invalid extension name");
|
||||
}
|
||||
|
||||
llvm::Expected<StructuredData::ObjectSP>
|
||||
ScriptInterpreterPython::GetExtensionSchema(
|
||||
const llvm::SmallVector<llvm::StringRef> &extension_path) {
|
||||
lldb::ScriptedExtension extension =
|
||||
ScriptInterpreter::StringToExtension(extension_path.back());
|
||||
auto import_path_or_err = ExtensionToImportPath(extension);
|
||||
if (!import_path_or_err)
|
||||
return import_path_or_err.takeError();
|
||||
|
||||
StreamString command_stream;
|
||||
// __import__(path, fromlist=['']) imports the submodule and returns it
|
||||
// directly (rather than the top-level package), as a single expression --
|
||||
// this keeps the whole call eval-able in one line while guaranteeing the
|
||||
// module is imported first; referencing "<import_path>.<ClassName>"
|
||||
// directly would only work if something else had already imported
|
||||
// <import_path> as a side effect.
|
||||
command_stream.Printf("lldb.embedded_interpreter.generate_extension_schema("
|
||||
"__import__('%s', fromlist=['']).%s)",
|
||||
import_path_or_err->c_str(),
|
||||
ScriptInterpreter::ExtensionToString(extension).data());
|
||||
|
||||
// Use eScriptReturnTypeOpaqueObject: it transfers a real owned reference
|
||||
// we can safely extract the string from. eScriptReturnTypeCharStrOrNone
|
||||
// instead hands back a pointer to a temporary Python object's buffer
|
||||
// that gets destroyed (and, for a freshly created string like this one,
|
||||
// deallocated) as soon as ExecuteOneLineWithReturn returns -- reading
|
||||
// it afterwards is a use-after-free.
|
||||
void *result_obj = nullptr;
|
||||
if (!ExecuteOneLineWithReturn(
|
||||
command_stream.GetData(),
|
||||
ScriptInterpreter::eScriptReturnTypeOpaqueObject, &result_obj,
|
||||
ExecuteScriptOptions().SetEnableIO(false)))
|
||||
return llvm::createStringError("invalid extension schema format");
|
||||
|
||||
// ExecuteOneLineWithReturn releases the GIL before returning, so touching
|
||||
// the returned object (Str() below can execute arbitrary Python code) must
|
||||
// re-acquire it first. py_result is scoped so its destructor (a DECREF)
|
||||
// also runs before the GIL is released below, not after.
|
||||
std::string schema_str;
|
||||
{
|
||||
PyGILState_STATE gil_state = PyGILState_Ensure();
|
||||
{
|
||||
PythonObject py_result(PyRefType::Owned,
|
||||
static_cast<PyObject *>(result_obj));
|
||||
if (py_result.IsAllocated() && py_result.get() != Py_None)
|
||||
schema_str = py_result.Str().GetString().str();
|
||||
}
|
||||
PyGILState_Release(gil_state);
|
||||
}
|
||||
|
||||
if (schema_str.empty())
|
||||
return llvm::createStringError("empty extension schema");
|
||||
return StructuredData::ParseJSON(schema_str);
|
||||
}
|
||||
|
||||
llvm::Error ScriptInterpreterPython::ParseExtensionSchema(
|
||||
Stream &s, llvm::StringRef output_script_prefix,
|
||||
const llvm::SmallVector<llvm::StringRef> &extension_path,
|
||||
bool generate_non_abstract_methods, std::set<std::string> &typing_imports) {
|
||||
auto schema_or_err = GetExtensionSchema(extension_path);
|
||||
if (!schema_or_err)
|
||||
return schema_or_err.takeError();
|
||||
|
||||
StructuredData::ObjectSP schema = *schema_or_err;
|
||||
if (!schema)
|
||||
return llvm::createStringError("empty extension schema");
|
||||
StructuredData::Dictionary *dict = schema->GetAsDictionary();
|
||||
if (!dict)
|
||||
return llvm::createStringError("extension schema is not a JSON object");
|
||||
|
||||
// Merge each class' typing imports into the caller-owned set so the
|
||||
// final `from typing import ...` line covers every class we emit.
|
||||
StructuredData::Array *schema_typing;
|
||||
if (dict->GetValueForKeyAsArray("typing_imports", schema_typing))
|
||||
schema_typing->ForEach([&](StructuredData::Object *entry) {
|
||||
if (auto *str = entry->GetAsString())
|
||||
typing_imports.insert(str->GetValue().str());
|
||||
return true;
|
||||
});
|
||||
|
||||
llvm::StringRef base_class, import_path;
|
||||
if (!dict->GetValueForKeyAsString("class", base_class))
|
||||
return llvm::createStringError(
|
||||
llvm::formatv("extension schema dictionary is missing 'class' key")
|
||||
.str());
|
||||
if (!dict->GetValueForKeyAsString("module", import_path))
|
||||
return llvm::createStringError(
|
||||
llvm::formatv("extension schema dictionary is missing 'module' key")
|
||||
.str());
|
||||
|
||||
// imports
|
||||
s.Printf("from %s import %s\n", import_path.data(), base_class.data());
|
||||
s.EOL();
|
||||
|
||||
// class definition
|
||||
s.Printf("class %s%s(%s):\n", output_script_prefix.data(), base_class.data(),
|
||||
base_class.data());
|
||||
s.IndentMore();
|
||||
|
||||
// Class docstring: list the non-callable members the base class exposes
|
||||
// so the user sees what's available without having to hop back to the
|
||||
// base class definition.
|
||||
bool has_body = false;
|
||||
StructuredData::Array *attributes;
|
||||
if (dict->GetValueForKeyAsArray("attributes", attributes) &&
|
||||
attributes->GetSize()) {
|
||||
s.Indent();
|
||||
s.PutCString("\"\"\"\n");
|
||||
s.Indent();
|
||||
s.Printf("Attributes inherited from %s:\n", base_class.data());
|
||||
for (size_t i = 0; i < attributes->GetSize(); i++) {
|
||||
auto maybe_dict = attributes->GetItemAtIndexAsDictionary(i);
|
||||
if (!maybe_dict)
|
||||
continue;
|
||||
StructuredData::Dictionary *attr_dict = *maybe_dict;
|
||||
llvm::StringRef attr_name;
|
||||
if (!attr_dict->GetValueForKeyAsString("name", attr_name))
|
||||
continue;
|
||||
llvm::StringRef attr_type;
|
||||
bool has_type = attr_dict->GetValueForKeyAsString("type", attr_type);
|
||||
s.Indent();
|
||||
s.Printf("- %s", attr_name.data());
|
||||
if (has_type)
|
||||
s.Printf(": %s", attr_type.data());
|
||||
s.EOL();
|
||||
}
|
||||
s.Indent();
|
||||
s.PutCString("\"\"\"\n\n");
|
||||
has_body = true;
|
||||
}
|
||||
|
||||
// members
|
||||
StructuredData::Array *members;
|
||||
if (!dict->GetValueForKeyAsArray("members", members))
|
||||
return llvm::createStringError("missing 'members' key in extension schema");
|
||||
|
||||
// If the base class doesn't mark anything `@abstractmethod`, the filter
|
||||
// "only stub abstract methods" would leave the derived class empty --
|
||||
// which isn't a useful starting point. Fall back to emitting every
|
||||
// method in that case so the user has actual code to edit.
|
||||
bool any_abstract = false;
|
||||
for (size_t i = 0; i < members->GetSize(); i++) {
|
||||
auto maybe_dict = members->GetItemAtIndexAsDictionary(i);
|
||||
if (!maybe_dict)
|
||||
continue;
|
||||
bool is_abstract = false;
|
||||
if ((*maybe_dict)->GetValueForKeyAsBoolean("is_abstract", is_abstract) &&
|
||||
is_abstract) {
|
||||
any_abstract = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
bool emit_all_methods = generate_non_abstract_methods || !any_abstract;
|
||||
|
||||
for (size_t i = 0; i < members->GetSize(); i++) {
|
||||
auto maybe_dict = members->GetItemAtIndexAsDictionary(i);
|
||||
if (!maybe_dict)
|
||||
return llvm::createStringError(
|
||||
llvm::formatv(
|
||||
"member at index {0} in extension schema isn't a dictionary")
|
||||
.str());
|
||||
|
||||
StructuredData::Dictionary *member_dict = *maybe_dict;
|
||||
llvm::StringRef symbol, args;
|
||||
if (!member_dict->GetValueForKeyAsString("name", symbol))
|
||||
return llvm::createStringError(
|
||||
llvm::formatv(
|
||||
"member at index {0} in extension schema is missing 'name' key")
|
||||
.str());
|
||||
if (!member_dict->GetValueForKeyAsString("signature", args))
|
||||
return llvm::createStringError(
|
||||
llvm::formatv("member at index {0} in extension schema is missing "
|
||||
"'signature' key")
|
||||
.str());
|
||||
|
||||
bool is_abstract = false;
|
||||
bool has_is_abstract =
|
||||
member_dict->GetValueForKeyAsBoolean("is_abstract", is_abstract);
|
||||
if (!emit_all_methods)
|
||||
if (!has_is_abstract || !is_abstract)
|
||||
continue;
|
||||
|
||||
s.Indent();
|
||||
s.Printf("def %s%s:\n", symbol.data(), args.data());
|
||||
|
||||
s.IndentMore();
|
||||
llvm::StringRef documentation;
|
||||
if (member_dict->GetValueForKeyAsString("doc", documentation)) {
|
||||
s.Indent();
|
||||
s.PutCString("\"\"\"\n");
|
||||
|
||||
llvm::SmallVector<llvm::StringRef> lines;
|
||||
documentation.split(lines, "\n");
|
||||
|
||||
for (llvm::StringRef line : lines) {
|
||||
s.Indent();
|
||||
s.PutCString(line);
|
||||
s.EOL();
|
||||
}
|
||||
|
||||
s.Indent();
|
||||
s.PutCString("\"\"\"");
|
||||
s.EOL();
|
||||
}
|
||||
|
||||
if (symbol == "__init__") {
|
||||
// The base class' constructor sets up attributes (e.g. self.target,
|
||||
// self.process) that the inherited, non-overridden methods rely on.
|
||||
// Forward the same arguments so that state is still initialized.
|
||||
// Splitting the param list on `,` requires bracket-depth awareness
|
||||
// because annotations like `Union[X, Y]` also contain commas.
|
||||
llvm::StringRef params = args.trim("()");
|
||||
std::vector<std::string> forwarded_args;
|
||||
int depth = 0;
|
||||
size_t start = 0;
|
||||
auto flush = [&](size_t end) {
|
||||
llvm::StringRef param = params.slice(start, end);
|
||||
param = param.split(':').first.split('=').first.trim();
|
||||
if (!param.empty() && param != "self")
|
||||
forwarded_args.push_back(param.str());
|
||||
};
|
||||
for (size_t i = 0; i < params.size(); ++i) {
|
||||
char c = params[i];
|
||||
if (c == '[' || c == '(' || c == '{')
|
||||
++depth;
|
||||
else if (c == ']' || c == ')' || c == '}')
|
||||
--depth;
|
||||
else if (c == ',' && depth == 0) {
|
||||
flush(i);
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
flush(params.size());
|
||||
s.Indent();
|
||||
s.Printf("super().__init__(%s)\n",
|
||||
llvm::join(forwarded_args, ", ").c_str());
|
||||
}
|
||||
|
||||
s.Indent();
|
||||
s.PutCString("# TODO: Implement\n");
|
||||
s.Indent();
|
||||
s.PutCString("pass\n\n");
|
||||
s.IndentLess();
|
||||
has_body = true;
|
||||
}
|
||||
|
||||
// A class with no body is a Python syntax error, so emit `pass` when the
|
||||
// base class has nothing to stub out (no methods and no attributes to
|
||||
// document).
|
||||
if (!has_body) {
|
||||
s.Indent();
|
||||
s.PutCString("pass\n");
|
||||
}
|
||||
|
||||
return llvm::Error::success();
|
||||
}
|
||||
|
||||
llvm::Expected<FileSpec> ScriptInterpreterPython::GenerateExtensionTemplate(
|
||||
const std::string &name, std::vector<ExtensionTemplateRequest> &extensions,
|
||||
bool generate_non_abstract_methods, std::string output_file) {
|
||||
// `ParseExtensionSchema` accumulates every `typing` generic it sees
|
||||
// (`Optional`, `Union`, `List`, ...) into this set so we can emit a
|
||||
// targeted `from typing import ...` line only for what's actually
|
||||
// referenced. The Python schema does the detection so we don't have
|
||||
// to re-scan strings here.
|
||||
std::set<std::string> typing_imports;
|
||||
StreamString bodies;
|
||||
for (const ExtensionTemplateRequest &extension : extensions) {
|
||||
if (llvm::Error err =
|
||||
ParseExtensionSchema(bodies, name, extension.path,
|
||||
generate_non_abstract_methods, typing_imports))
|
||||
return std::move(err);
|
||||
bodies.PutCString("\n\n");
|
||||
}
|
||||
|
||||
StreamString generated_file_stream;
|
||||
generated_file_stream.PutCString("import lldb\n");
|
||||
if (!typing_imports.empty()) {
|
||||
std::vector<std::string> sorted_imports(typing_imports.begin(),
|
||||
typing_imports.end());
|
||||
generated_file_stream.Format("from typing import {0}\n",
|
||||
llvm::join(sorted_imports, ", "));
|
||||
}
|
||||
generated_file_stream.PutCString("\n");
|
||||
generated_file_stream.PutCString(bodies.GetString());
|
||||
|
||||
FileSpec save_location;
|
||||
if (output_file.empty()) {
|
||||
// Sanitize the caller-supplied class prefix so it can't escape the
|
||||
// temp directory (`../`, path separators, ...). Only keep ASCII
|
||||
// alphanumerics; everything else collapses to `_`, and an all-junk
|
||||
// name falls back to a fixed default.
|
||||
std::string sanitized;
|
||||
sanitized.reserve(name.size());
|
||||
for (char c : name)
|
||||
sanitized.push_back(llvm::isAlnum(c) ? static_cast<char>(llvm::toLower(c))
|
||||
: '_');
|
||||
if (sanitized.find_first_not_of('_') == std::string::npos)
|
||||
sanitized = "extension";
|
||||
const std::string file_name = "lldb_" + sanitized + "_extension.py";
|
||||
save_location = HostInfo::GetGlobalTempDir();
|
||||
FileSystem::Instance().Resolve(save_location);
|
||||
save_location.AppendPathComponent(file_name);
|
||||
} else {
|
||||
save_location = FileSpec(output_file);
|
||||
FileSystem::Instance().Resolve(save_location);
|
||||
}
|
||||
|
||||
File::OpenOptions flags = File::eOpenOptionWriteOnly |
|
||||
File::eOpenOptionCanCreate |
|
||||
File::eOpenOptionTruncate;
|
||||
|
||||
auto opened_file = FileSystem::Instance().Open(save_location, flags);
|
||||
|
||||
if (!opened_file)
|
||||
return opened_file.takeError();
|
||||
|
||||
FileUP file = std::move(opened_file.get());
|
||||
|
||||
size_t byte_size = generated_file_stream.GetSize();
|
||||
|
||||
Status error = file->Write(generated_file_stream.GetData(), byte_size);
|
||||
|
||||
if (error.Fail() || byte_size != generated_file_stream.GetSize())
|
||||
return llvm::createStringError("Unable to write to destination file. Bytes "
|
||||
"written do not match generated file size.");
|
||||
return save_location;
|
||||
}
|
||||
|
||||
void ScriptInterpreterPython::SharedLibraryDirectoryHelper(
|
||||
FileSpec &this_file) {
|
||||
// When we're loaded from python, this_file will point to the file inside the
|
||||
|
||||
Reference in new issue
Block a user