https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/109427
>From cc4032e58217a01ff414b8d03866a1631f492df8 Mon Sep 17 00:00:00 2001 From: David Spickett <david.spick...@linaro.org> Date: Fri, 20 Sep 2024 14:00:44 +0100 Subject: [PATCH 1/2] [lldb][docs] Resurrect the information on adding a new language This got deleted in e078c9507c3abb4d9bb2265c366b26557880a3e3, I presume accidentally, because it didn't have a corresponding rst file for it. So I've brought it back and converted it into Markdown. The content remains accurate, from what I know at least. It's a bit "now draw the rest of the owl" but if nothing else, it gives you a bunch of important classes to go and research as a starting point. You can see the original content here: https://github.com/llvm/llvm-project/blob/5d71fc5d7b5ffe2323418a09db6eddaf84d6c662/lldb/www/adding-language-support.html --- lldb/docs/index.rst | 1 + lldb/docs/resources/addinglanguagesupport.md | 95 ++++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 lldb/docs/resources/addinglanguagesupport.md diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst index d9b8e589eb2ac0..dd44a8430add80 100644 --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -163,6 +163,7 @@ interesting areas to contribute to lldb. resources/caveats resources/projects resources/lldbdap + resources/addinglanguagesupport Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html> Private C++ API <https://lldb.llvm.org/cpp_reference/index.html> diff --git a/lldb/docs/resources/addinglanguagesupport.md b/lldb/docs/resources/addinglanguagesupport.md new file mode 100644 index 00000000000000..d92104a0e5e6ec --- /dev/null +++ b/lldb/docs/resources/addinglanguagesupport.md @@ -0,0 +1,95 @@ +# Adding Programming Language Support + +LLDB has been architected to make it straightforward to add support for a +programming language. Only a small enum in core LLDB needs to be modified to +make LLDB aware of a new programming language. Everything else can be supplied +in derived classes that need not even be present in the core LLDB repository. +This makes it convenient for developers adding language support either in +branches or downstream repositories since it practically eliminates the +potential for merge conflicts. + +The basic steps are: +* Add the language to the `LanguageType` enum. +* Add a `TypeSystem` for the language. +* Add expression evaluation support. + +Additionally, you may want to create a `Language` and `LanguageRuntime` plugin +for your language, which enables support for advanced features like dynamic +typing and data formatting. + +## Add the Language to the LanguageType enum + +The `LanguageType` enum +(see [lldb-enumerations.h](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/lldb-enumerations.h)) +contains a list of every language known to LLDB. It is the one place where +support for a language must live that will need to merge cleanly with upstream +LLDB if you are developing your language support in a separate branch. When +adding support for a language previously unknown to LLDB, start by adding an +enumeration entry to `LanguageType`. + +## Add a TypeSystem for the Language + +Both [Module](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Core/Module.h) +and [Target](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Target/Target.h) +support the retrieval of a `TypeSystem` instance via `GetTypeSystemForLanguage()`. +For `Module`, this method is directly on the `Module` instance. For `Target`, +this is retrieved indirectly via the `TypeSystemMap` for the `Target` instance. + +The `TypeSystem` instance returned by the `Target` is expected to be capable of +evaluating expressions, while the `TypeSystem` instance returned by the `Module` +is not. If want to support expression evaluation for your language, you could +consider one of the following approaches: +* Implement a single `TypeSystem` class that supports evaluation when given an + optional `Target`, implementing all the expression evaluation methods on the + `TypeSystem`. +* Create multiple `TypeSystem` classes, one for evaluation and one for static + `Module` usage. + +For clang and Swift, the latter approach was chosen. Primarily to make it +clearer that evaluation with the static `Module`-returned `TypeSystem` instances +make no sense, and have them error out on those calls. But either approach is +fine. + +# Add Expression Evaluation Support + +Expression Evaluation support is enabled by implementing the relevant methods on +a `TypeSystem`-derived class. Search for `Expression` in the +[TypeSystem header](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Symbol/TypeSystem.h) +to find the methods to implement. + +# Type Completion + +There are three levels of type completion, each requiring more type information: +1. Pointer size: When you have a forward decl or a reference, and that's all you + need. At this stage, the pointer size is all you need. +2. Layout info: You need the size of an instance of the type, but you still don't + need to know all the guts of the type. +3. Full type info: Here you need everything, because you're playing with + internals of it, such as modifying a member variable. + +Ensure you never complete more of a type than is needed for a given situation. +This will keep your type system from doing more work than necessary. + +# Creating Types + +Your `TypeSystem` will need an approach for creating types based on a set of +`Module`s. If your type info is going to come from DWARF info, you will want to +subclass [DWARFASTParser](https://github.com/llvm/llvm-project/blob/main/lldb/source/Plugins/SymbolFile/DWARF/DWARFASTParser.h). + +# Language and LanguageRuntime Plugins + +If you followed the steps outlined above, you already have taught LLDB a great +deal about your language. If your language's runtime model and fundamental data +types don't differ much from the C model, you are pretty much done. + +However it is likely that your language offers its own data types for things +like strings and arrays, and probably has a notion of dynamic types, where the +effective type of a variable can only be known at runtime. + +These tasks are covered by two plugins: +* a `LanguageRuntime` plugin, which provides LLDB with a dynamic view of your + language; this plugin answers questions that require a live process to acquire + information (for example dynamic type resolution). +* a `Language plugin`, which provides LLDB with a static view of your language; + questions that are statically knoawble and do not require a process are + answered by this plugin (for example data formatters). \ No newline at end of file >From 6bcc832f33b11396a3fa641bbc8054ee644311fc Mon Sep 17 00:00:00 2001 From: David Spickett <david.spick...@linaro.org> Date: Mon, 23 Sep 2024 11:51:28 +0100 Subject: [PATCH 2/2] review comments --- lldb/docs/resources/addinglanguagesupport.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/lldb/docs/resources/addinglanguagesupport.md b/lldb/docs/resources/addinglanguagesupport.md index d92104a0e5e6ec..77730acefc8aa3 100644 --- a/lldb/docs/resources/addinglanguagesupport.md +++ b/lldb/docs/resources/addinglanguagesupport.md @@ -4,9 +4,8 @@ LLDB has been architected to make it straightforward to add support for a programming language. Only a small enum in core LLDB needs to be modified to make LLDB aware of a new programming language. Everything else can be supplied in derived classes that need not even be present in the core LLDB repository. -This makes it convenient for developers adding language support either in -branches or downstream repositories since it practically eliminates the -potential for merge conflicts. +This makes it convenient for developers adding language support in downstream +repositories since it practically eliminates the potential for merge conflicts. The basic steps are: * Add the language to the `LanguageType` enum. @@ -90,6 +89,6 @@ These tasks are covered by two plugins: * a `LanguageRuntime` plugin, which provides LLDB with a dynamic view of your language; this plugin answers questions that require a live process to acquire information (for example dynamic type resolution). -* a `Language plugin`, which provides LLDB with a static view of your language; - questions that are statically knoawble and do not require a process are +* a `Language` plugin, which provides LLDB with a static view of your language; + questions that are statically knowable and do not require a process are answered by this plugin (for example data formatters). \ No newline at end of file _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
