From d67e1a100e22bd37d821384e8b5feb372c55c9d6 Mon Sep 17 00:00:00 2001 From: Douglas Raillard Date: Thu, 24 Apr 2025 11:18:02 +0100 Subject: [PATCH 1/4] lisa.utils: Fix YAML constructor handling FIX Use the existing YAML.constructor property behavior rather than instantiating the constructor ourselves. Doing so leads to missing a loader attribute which breaks loading. --- lisa/utils.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/lisa/utils.py b/lisa/utils.py index ce34383e3..e0ab1ef8d 100644 --- a/lisa/utils.py +++ b/lisa/utils.py @@ -1033,12 +1033,15 @@ class Serializable( # really should be instance-related. class _YAML(YAML): @property - @memoized def constructor(self): + ctor = super().constructor # This will rightfully raise in case constructor() is called # from YAML.__init__(), so that we do not accidentally memoized - # an instance of the wrong type. - return _Constructor() + # an instance of the wrong type. Doing so would circumvent our + # attempt at making the configuration local to the YAML + # instance we create here. + assert isinstance(ctor, _Constructor) + return ctor # If the user requested an unsafe instance, we provide a safe instance # with a re-implementation of some unsafe bits. This is because -- GitLab From 945ca29613ed97e9831f39baa8d76bacc203d7aa Mon Sep 17 00:00:00 2001 From: Douglas Raillard Date: Thu, 24 Apr 2025 12:13:51 +0100 Subject: [PATCH 2/4] lisa.utils: Fix inspect.getsource() for newtype() in Python 3.13 FIX Python 3.13 inspect.getsource() uses the new __firstlineno__ attribute that allows getting the first line number of the class declaration. Unfortunately, this was set to the location inside newtype where the class is actually created, leading to problems in Sphinx autodoc. Set the __firstlineno__ attribute manually to the newtype() caller's location to preseve accurate source location. --- lisa/utils.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/lisa/utils.py b/lisa/utils.py index e0ab1ef8d..3ffd9cafa 100644 --- a/lisa/utils.py +++ b/lisa/utils.py @@ -3598,7 +3598,7 @@ def get_sphinx_role(obj, name=None): return role -def newtype(cls, name, doc=None, module=None): +def newtype(cls, name, doc=None, module=None, stacklevel=1): """ Make a new class inheriting from ``cls`` with the given ``name``. @@ -3625,6 +3625,11 @@ def newtype(cls, name, doc=None, module=None): class New(cls, metaclass=Meta): # pylint: disable=invalid-metaclass pass + # Set the __firstlineno__ attribute for Python 3.13 inspect.getsource(). + # Otherwise we get the line number of the "class New" definition, which is + # right here and not matching where the newtype is logically defined + stack = inspect.stack() + New.__firstlineno__ = stack[stacklevel].lineno New.__name__ = name.split('.')[-1] New.__qualname__ = name -- GitLab From e9758bee0a15952ead3779b4f191410a57e43530 Mon Sep 17 00:00:00 2001 From: Douglas Raillard Date: Thu, 24 Apr 2025 13:30:52 +0100 Subject: [PATCH 3/4] doc/lisa_shell/man/man.rst: Add lisa-load-kmod to the list Add lisa-load-kmod to the list of commands in the "lisa" man page. --- doc/lisa_shell/man/man.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/lisa_shell/man/man.rst b/doc/lisa_shell/man/man.rst index d245c54dd..70a67e660 100644 --- a/doc/lisa_shell/man/man.rst +++ b/doc/lisa_shell/man/man.rst @@ -105,6 +105,7 @@ Buildroot commands Misc commands ------------- +* ``lisa-load-kmod`` - Build and load the LISA kernel module on a running target. * ``lisa-plot`` - Generate various plots from a ``trace.dat`` file. See ``lisa-plot -h`` for available plots. * ``lisa-platinfo-extract`` - Extract a platform information file -- GitLab From 94d31a94d1b929e9c9c349306ba2c2d95e3818a5 Mon Sep 17 00:00:00 2001 From: Douglas Raillard Date: Thu, 24 Apr 2025 12:28:47 +0100 Subject: [PATCH 4/4] tools/tests.sh: Check man page build output on Python 3.11 only Only check the manpage is up to date on Python 3.11 as the format of argparse help message changed in 3.13. This means the man page must be updated by running a Python 3.11 install. --- doc/man1/bisector.1 | 12 ++++++------ doc/man1/exekall.1 | 10 +++++----- doc/man1/lisa.1 | 2 ++ tools/lisa-doc-build | 5 ----- tools/tests.sh | 12 +++++++++--- 5 files changed, 22 insertions(+), 19 deletions(-) diff --git a/doc/man1/bisector.1 b/doc/man1/bisector.1 index 95d59bfc9..92a1fedb9 100644 --- a/doc/man1/bisector.1 +++ b/doc/man1/bisector.1 @@ -87,7 +87,7 @@ usage: bisector [\-h] [\-\-cli\-options CLI_OPTIONS] iterations to the report. The execution can later be resumed with \-\-resume. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-cli\-options CLI_OPTIONS YAML file containing command line option string in a @@ -119,7 +119,7 @@ Run the given steps in a loop and record the result in a report file. The report file can be inspected using the \(dqreport\(dq subcommand. The exit status is suitable for git bisect. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-cli\-options CLI_OPTIONS YAML file containing command line option string in a @@ -217,7 +217,7 @@ positional arguments: report Read back a previous session saved using \-\-report option of run subcommand. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-cli\-options CLI_OPTIONS YAML file containing command line option string in a @@ -800,7 +800,7 @@ positional arguments: PID Slave PID to act on or \(dqall\(dq. Start a monitor\-server before using \(dqall\(dq. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-cli\-options CLI_OPTIONS YAML file containing command line option string in a @@ -839,7 +839,7 @@ usage: bisector monitor\-server [\-h] [\-\-cli\-options CLI_OPTIONS] Start the DBus server to allow monitoring all running instances. Note that the server is not necessary to monitor a specific run instance. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-cli\-options CLI_OPTIONS YAML file containing command line option string in a @@ -869,7 +869,7 @@ Modify the properties of the steps in an existing report. positional arguments: report Report to edit. -optional arguments: +options: \-h, \-\-help show this help message and exit \-o OPTION, \-\-option OPTION Step\-specific options. Can be repeated. The format is diff --git a/doc/man1/exekall.1 b/doc/man1/exekall.1 index e02e1eef8..be52fd0d1 100644 --- a/doc/man1/exekall.1 +++ b/doc/man1/exekall.1 @@ -49,7 +49,7 @@ PATTERNS A pattern starting with \(dq!\(dq is used as a negative pattern. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-debug Show complete Python backtrace when exekall crashes. @@ -93,7 +93,7 @@ positional arguments: contained files recursively are selected. By default, the current directory is selected. -optional arguments: +options: \-h, \-\-help show this help message and exit \-\-dependency DEPENDENCY Same as specifying a module in PYTHON_MODULES but will only be used to @@ -200,7 +200,7 @@ arguments. positional arguments: db DBs created using exekall run to compare. -optional arguments: +options: \-h, \-\-help show this help message and exit .EE @@ -226,7 +226,7 @@ arguments. positional arguments: db DB created using exekall run to show. -optional arguments: +options: \-h, \-\-help show this help message and exit .EE @@ -250,7 +250,7 @@ positional arguments: artifact_dirs Artifact directories created using \(dqexekall run\(dq, or value databases to merge. -optional arguments: +options: \-h, \-\-help show this help message and exit \-o OUTPUT, \-\-output OUTPUT diff --git a/doc/man1/lisa.1 b/doc/man1/lisa.1 index 3e4b533b5..47db233a3 100644 --- a/doc/man1/lisa.1 +++ b/doc/man1/lisa.1 @@ -158,6 +158,8 @@ buildroot initramfs into the kernel. .SS Misc commands .INDENT 0.0 .IP \(bu 2 +\fBlisa\-load\-kmod\fP \- Build and load the LISA kernel module on a running target. +.IP \(bu 2 \fBlisa\-plot\fP \- Generate various plots from a \fBtrace.dat\fP file. See \fBlisa\-plot \-h\fP for available plots. .IP \(bu 2 diff --git a/tools/lisa-doc-build b/tools/lisa-doc-build index ba795aa67..81e57c994 100755 --- a/tools/lisa-doc-build +++ b/tools/lisa-doc-build @@ -43,11 +43,6 @@ docs=( for doc in "${docs[@]}"; do sphinx-build "$LISA_HOME/$doc" "$LISA_HOME/doc/man1" -Enab man || ret=2 done -# In Python >= 3.10, argparse's --help uses "options:" group instead of -# "optional arguments:", so we convert it back to the old form so that git diff -# will not find a difference if the doc is up to date, regardless of the version -# used to build the doc. -sed -i 's/^options:$/optional arguments:/' "$LISA_HOME"/doc/man1/*.1 echo "Man pages have been updated and the main documentation can be found under: $LISA_HOME/doc/_build/html/index.html" diff --git a/tools/tests.sh b/tools/tests.sh index 4a906e4ef..20908e07a 100755 --- a/tools/tests.sh +++ b/tools/tests.sh @@ -38,10 +38,16 @@ exekall run "$LISA_HOME/tools/exekall/src/exekall/_tests" echo "Starting documentation pedantic build ..." lisa-doc-build +MANPAGE_PYTHON_VERSION="3.11" + echo "Checking that the man pages are up to date ..." -if ! git diff --exit-code doc/man1/; then - echo "Please regenerate man pages in doc/man1 and commit them" - exit 1 +if python3 --version | grep -F "$MANPAGE_PYTHON_VERSION" ; then + if ! git diff --exit-code doc/man1/; then + echo "Please regenerate man pages in doc/man1 and commit them" + exit 1 + fi +else + echo "Skipped man page check as it only runs for $MANPAGE_PYTHON_VERSION" fi # FIXME: cbindgen does not work on our source anymore due to that issue: -- GitLab