https://github.com/medismailben updated
https://github.com/llvm/llvm-project/pull/97262
>From 06a79c19a169fa6b8bed30bde37b7ee56ade5cef Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ism...@bennani.ma>
Date: Tue, 2 Jul 2024 12:47:50 -0700
Subject: [PATCH] [lldb/docs] Add scripting extensions documentation to the
website
This patch adds the documentation for a subset of scripting extensions
such as scripted process, scripted thread, operating system threads &
scritped thread plans to the lldb website.
Signed-off-by: Med Ismail Bennani <ism...@bennani.ma>
---
lldb/docs/CMakeLists.txt | 7 +++-
lldb/docs/index.rst | 1 +
.../python/templates/operating_system.py | 20 ++++-----
.../python/templates/scripted_platform.py | 25 ++++++-----
.../python/templates/scripted_process.py | 42 +++++++++----------
5 files changed, 48 insertions(+), 47 deletions(-)
diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt
index f482e91d1b10c..ed4296bbf03a4 100644
--- a/lldb/docs/CMakeLists.txt
+++ b/lldb/docs/CMakeLists.txt
@@ -27,8 +27,13 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
get_target_property(lldb_bindings_dir swig_wrapper_python BINARY_DIR)
add_custom_target(lldb-python-doc-package
COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_bindings_dir}/lldb.py"
"${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
+ COMMAND "${CMAKE_COMMAND}" -E make_directory
"${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins"
+ COMMAND "${CMAKE_COMMAND}" -E copy
"${LLDB_SOURCE_DIR}/examples/python/templates/scripted_process.py"
"${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+ COMMAND "${CMAKE_COMMAND}" -E copy
"${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py"
"${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+ COMMAND "${CMAKE_COMMAND}" -E copy
"${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py"
"${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMENT "Copying lldb.py to pretend its a Python package.")
- add_dependencies(lldb-python-doc-package swig_wrapper_python)
+
+ add_dependencies(lldb-python-doc-package swig_wrapper_python lldb-python)
# FIXME: Don't treat Sphinx warnings as errors. The files generated by
# automodapi are full of warnings (partly caused by SWIG, our documentation
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index 1e7d69002dd3e..3ce23beec2a5e 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -141,6 +141,7 @@ interesting areas to contribute to lldb.
use/python
use/python-reference
Python API <python_api>
+ Python Extensions <python_extensions>
.. toctree::
diff --git a/lldb/examples/python/templates/operating_system.py
b/lldb/examples/python/templates/operating_system.py
index a8053bcaa21af..d83019079ee90 100644
--- a/lldb/examples/python/templates/operating_system.py
+++ b/lldb/examples/python/templates/operating_system.py
@@ -10,16 +10,16 @@ class OperatingSystem(ScriptedThread):
"""
Class that provides data for an instance of a LLDB 'OperatingSystemPython'
plug-in class.
- ```
- thread_info = {
- "tid": tid,
- "name": "four",
- "queue": "queue4",
- "state": "stopped",
- "stop_reason": "none",
- "core" : 2
- }
- ```
+ .. code-block:: python
+
+ thread_info = {
+ "tid": tid,
+ "name": "four",
+ "queue": "queue4",
+ "state": "stopped",
+ "stop_reason": "none",
+ "core" : 2
+ }
- tid : thread ID (mandatory)
- name : thread name (optional key/value pair)
diff --git a/lldb/examples/python/templates/scripted_platform.py
b/lldb/examples/python/templates/scripted_platform.py
index fb1bde8fd4cb7..5805f99dea4ca 100644
--- a/lldb/examples/python/templates/scripted_platform.py
+++ b/lldb/examples/python/templates/scripted_platform.py
@@ -10,9 +10,6 @@ class ScriptedPlatform(metaclass=ABCMeta):
Most of the base class methods are `@abstractmethod` that need to be
overwritten by the inheriting class.
-
- DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
- THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
"""
processes = None
@@ -32,16 +29,18 @@ def __init__(self, exe_ctx, args):
def list_processes(self):
"""Get a list of processes that are running or that can be attached to
on the platform.
- processes = {
- 420: {
- name: a.out,
- arch: aarch64,
- pid: 420,
- parent_pid: 42 (optional),
- uid: 0 (optional),
- gid: 0 (optional),
- },
- }
+ .. code-block:: python
+
+ processes = {
+ 420: {
+ name: a.out,
+ arch: aarch64,
+ pid: 420,
+ parent_pid: 42 (optional),
+ uid: 0 (optional),
+ gid: 0 (optional),
+ },
+ }
Returns:
Dict: The processes represented as a dictionary, with at least the
diff --git a/lldb/examples/python/templates/scripted_process.py
b/lldb/examples/python/templates/scripted_process.py
index 3ddcebd128eaa..b7b6499580e50 100644
--- a/lldb/examples/python/templates/scripted_process.py
+++ b/lldb/examples/python/templates/scripted_process.py
@@ -11,9 +11,6 @@ class ScriptedProcess(metaclass=ABCMeta):
Most of the base class methods are `@abstractmethod` that need to be
overwritten by the inheriting class.
-
- DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
- THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
"""
capabilities = None
@@ -106,8 +103,8 @@ def write_memory_at_address(self, addr, data, error):
Args:
addr (int): Address from which we should start reading.
- data (lldb.SBData): An `lldb.SBData` buffer to write to the
- process memory.
+ data (lldb.SBData): An `lldb.SBData` buffer to write to the process
+ memory.
error (lldb.SBError): Error object.
Returns:
@@ -121,13 +118,13 @@ def write_memory_at_address(self, addr, data, error):
def get_loaded_images(self):
"""Get the list of loaded images for the scripted process.
- ```
- scripted_image = {
- uuid = "c6ea2b64-f77c-3d27-9528-74f507b9078b",
- path = "/usr/lib/dyld"
- load_addr = 0xbadc0ffee
- }
- ```
+ .. code-block:: python
+
+ scripted_image = {
+ uuid = "c6ea2b64-f77c-3d27-9528-74f507b9078b",
+ path = "/usr/lib/dyld"
+ load_addr = 0xbadc0ffee
+ }
Returns:
List[scripted_image]: A list of `scripted_image` dictionaries
@@ -238,9 +235,6 @@ class ScriptedThread(metaclass=ABCMeta):
Most of the base class methods are `@abstractmethod` that need to be
overwritten by the inheriting class.
-
- DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
- THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
"""
@abstractmethod
@@ -305,10 +299,12 @@ def get_name(self):
def get_state(self):
"""Get the scripted thread state type.
+ .. code-block:: python
+
eStateStopped, ///< Process or thread is stopped and can be
examined.
eStateRunning, ///< Process or thread is running and can't be
examined.
- eStateStepping, ///< Process or thread is in the process of
stepping and can
- /// not be examined.
+ eStateStepping, ///< Process or thread is in the process of
stepping and
+ /// can not be examined.
eStateCrashed, ///< Process or thread has crashed and can be
examined.
Returns:
@@ -340,12 +336,12 @@ def get_stop_reason(self):
def get_stackframes(self):
"""Get the list of stack frames for the scripted thread.
- ```
- scripted_frame = {
- idx = 0,
- pc = 0xbadc0ffee
- }
- ```
+ .. code-block:: python
+
+ scripted_frame = {
+ idx = 0,
+ pc = 0xbadc0ffee
+ }
Returns:
List[scripted_frame]: A list of `scripted_frame` dictionaries
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
