Skip to contentSkip to conversation

rteval: Modernize documentation

PATCH New John Kacur 1 participant 2 messages Jun 3 Kbuild

lore
Share & tools
lore

John Kacur

author
#0 lore raw

PATCH 1/2 rteval: Modernize documentation

Update and reorganize rteval documentation:

- Completely rewrite rteval.8 man page with current options and features
- Add comprehensive sections for all measurement modules (cyclictest and timerlat)
- Add all cpuset, load control, and configuration options
- Include practical examples section
- Update to reflect current rteval 3.10 functionality

- Update README with modern installation and dependency information
- Add sysstat, rtla, and all build tool dependencies
- Organize dependencies by category (measurement, load modules, utilities)
- Use HTTPS URLs instead of deprecated git:// protocol
- Update TESTING section with current test targets

- Rename doc/rteval.txt to doc/rteval-legacy.txt to indicate it's historical

- Delete doc/installing.txt as redundant with README

- Add SPDX-License-Identifier to all documentation files

---
 README                                | 122 ++++++--
 doc/installing.txt                    |  23 --
 doc/{rteval.txt => rteval-legacy.txt} |   2 +
 doc/rteval.8                          | 398 +++++++++++++++++---------
 4 files changed, 367 insertions(+), 178 deletions(-)
 delete mode 100644 doc/installing.txt
 rename doc/{rteval.txt => rteval-legacy.txt} (99%)
README +95 -27
index cb2700e5a0fc..afaff25b65a3 100644
@@ -1,42 +1,110 @@
+SPDX-License-Identifier: GPL-2.0-or-later
 
-Rteval is a python program written to evaluate the performance of a
+Rteval is a Python program written to evaluate the performance of a
 realtime Linux kernel on a particular hardware platform. The program
-unpacks source code for two loads: hackbench and a Linux kernel
-compile, then loops running hackbench and a parallel build of the
-Linux kernel. While the loads are running, the cyclictest program is
-run to measure realtime performance under load. When the specified run
-duration is met, the loads are stopped and cyclictest outputs measured
-timer latency values in histogram format, which is analyzed by
-rteval. Rteval then writes an XML file to disk with information about
-the system (gotten through DMI tables), the raw histogram data
-collected during the run and the statistical analysis of the run.
+runs measurement modules (cyclictest or timerlat) to measure scheduling
+and timer latency while simultaneously running system load modules
+(kernel compile, hackbench, stress-ng) to stress the system.
 
-The rteval source may be pulled from it's git tree on kernel.org:
-    git://git.kernel.org/pub/scm/utils/rteval/rteval.git
+When the specified run duration is met, rteval stops the loads and
+measurements, then writes an XML report to disk with information about
+the system (from DMI tables), raw measurement data, and statistical
+analysis including min/max latency, standard deviation, and histograms.
 
-Rteval requires the following packages to run:
+INSTALLATION
+============
+
+The rteval source may be pulled from its git tree on kernel.org:
+    https://git.kernel.org/pub/scm/utils/rteval/rteval.git
+
+Required Dependencies:
 
 Python >= 3.8
-    http://www.python.org/download/
+    https://www.python.org/download/
+
+python3-lxml
+    https://lxml.de/
+
+python3-libxml2
+    https://xmlsoft.org/
+
+sysstat
+    System performance monitoring tools (sar, iostat, mpstat)
+
+Measurement Module Requirements (choose one):
+
+For cyclictest measurement module:
+  rt-tests (realtime-tests package)
+    https://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git
+
+For timerlat measurement module (recommended):
+  rtla (part of Linux kernel tools)
+    Requires kernel 5.15+ with CONFIG_OSNOISE_TRACER enabled
+
+Load Module Requirements:
+
+For kcompile load module:
+  rteval-loads package (provides kernel source tarballs)
+    Or manually download kernel sources from https://www.kernel.org/
+
+  Build tools: gcc, binutils, gcc-c++, make, flex, bison, bc,
+               kernel-headers, openssl-devel, perl-interpreter,
+               elfutils-libelf-devel, xz, bzip2, tar, gzip
+
+For stress-ng load module (optional):
+  stress-ng
+    https://github.com/ColinIanKing/stress-ng
 
-python-lxml
-  http://lxml.de/
+System utilities:
+  numactl, dmidecode, procps-ng
 
-libxml2-python
-    http://xmlsoft.org/
+Installation:
 
-rt-tests
-    git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git
+  $ git clone https://git.kernel.org/pub/scm/utils/rteval/rteval.git
+  $ cd rteval
+  $ sudo make install
 
-Rteval end-to-end tests additionally require the following packages:
+For rt-tests (if using cyclictest):
 
-Test::Harness
+  $ git clone https://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git
+  $ cd rt-tests
+  $ sudo make prefix=/usr install
+
+TESTING
+=======
+
+Rteval includes unit tests and end-to-end tests. End-to-end tests
+require:
+
+Test::Harness (Perl module)
     https://metacpan.org/pod/Test::Harness
 
-Clark Williams <[email protected]> wrote rteval
+Run tests with:
+  $ make test          # Unit tests
+  $ make e2e-tests     # End-to-end tests (requires root)
+
+USAGE
+=====
+
+Basic usage (requires root):
+
+  $ sudo rteval -d 3600
+
+Run with timerlat measurement module:
+
+  $ sudo rteval -d 3600 --measurement-module timerlat
+
+See the man page for more options:
+
+  $ man rteval
+
+AUTHORS
+=======
+
+Clark Williams <williams at redhat dot com> wrote rteval.
 
-David Sommerseth <[email protected]> wrote the XML-RPC and database
-    logic for handling rteval results.
+David Sommerseth wrote the XML-RPC and database logic for handling
+    rteval results.
 
-John Kacur <jkacur at redhat dot com> ported it to python-3.0
-    and has been developing and maintaining it since then.
+John Kacur <jkacur at redhat dot com> ported it to Python 3 and has
+    been developing and maintaining it since then.
doc/installing.txt deleted +0 -23
deleted file mode 100644
index 227249bbc9ed..000000000000
@@ -1,23 +0,0 @@
-The rteval utility requires some external software libraries to run
-properly. These are:
-
-python-lxml
-  A python library to parse XML files and XSLT stylesheets
-  http://lxml.de/
-
-libxml2-python
-  A python library to parse XML files
-  http://xmlsoft.org/
-
-rt-tests
-  A collection of programs used to measure real-time behavior
-  git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git
-
-
-$ git clone \
-  git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git
-$ cd rt-tests && sudo make prefix=/usr install
-$ cd ../rteval
-$ sudo make install
-
-That should do it (I hope).
doc/rteval-legacy.txt renamed from doc/rteval.txt +2 -0
similarity index 99%
rename from doc/rteval.txt
rename to doc/rteval-legacy.txt
index 95d501bb764e..65ee4887a91f 100644
@@ -1,3 +1,5 @@
+SPDX-License-Identifier: GPL-2.0-or-later
+
 Evaluating Realtime Linux system performance with rteval
 Clark Williams <[email protected]>
 --------------------------------------------------------
doc/rteval.8 +270 -128

445 lines not on this page · raw message

Signature · 1 line
2.54.0
author
#1 lore raw

PATCH 2/2 rteval: Add make uninstall target and fix pyproject.toml license

Add uninstall target to Makefile:
- Removes rteval script from $(PREFIX)/bin
- Removes man page from share/man/man8
- Removes XSL files and load files from share/rteval
- Uninstalls Python package via pip (if installed from make install)
- Preserves /etc/rteval.conf (user may have customized)
- Respects DESTDIR variable for test installations
- Added to help target and .PHONY declarations

Fix pyproject.toml license deprecation warning:
- Change license from table format {text = "GPL-2.0-or-later"} to simple SPDX string "GPL-2.0-or-later"
- Fixes setuptools deprecation warning about project.license format

Add tags to .gitignore to ignore ctags files

---
 .gitignore     |  1 +
 Makefile       | 26 +++++++++++++++++++++++++-
 pyproject.toml |  2 +-
 3 files changed, 27 insertions(+), 2 deletions(-)
.gitignore +1 -0
index ee5621e3fa3d..bd20ca2f4a71 100644
@@ -29,3 +29,4 @@ stamp-h1
 autom4te.cache/
 rteval-[0-9]*
 local/
+tags
Makefile +25 -1
index a9d3a871f123..8b540c6c68b4 100644
@@ -94,6 +94,29 @@ rteval-$(VERSION).tar.bz2:
 	mv dist/rteval-$(VERSION).tar.bz2 .
 	rmdir dist
 
+uninstall:
+	@echo "Uninstalling rteval..."
+	# Remove the rteval script
+	rm -f $(DESTDIR)$(PREFIX)/bin/rteval
+	# Remove man page
+	rm -f $(DESTDIR)$(PREFIX)/share/man/man8/rteval.8.gz
+	# Remove XSL files
+	rm -f $(DATADIR)/rteval/rteval_*.xsl
+	# Note: Leaving /etc/rteval.conf in place (remove manually if needed)
+	# Remove load files
+	rm -rf $(DATADIR)/rteval/loadsource
+	# Remove rteval data directory if empty
+	rmdir $(DATADIR)/rteval 2>/dev/null || true
+	# Uninstall Python package
+	@if $(PYTHON) -m pip show rteval 2>/dev/null | grep -q "Location: /usr"; then \
+		echo "Uninstalling rteval Python package..."; \
+		$(PYTHON) -m pip uninstall -y rteval; \
+	elif $(PYTHON) -m pip show rteval >/dev/null 2>&1; then \
+		echo "rteval found in pip but points to source directory (not removing)"; \
+	else \
+		echo "rteval Python package not found (may have been installed via RPM)"; \
+	fi
+
 help:
 	@echo ""
 	@echo "rteval Makefile targets:"
@@ -106,6 +129,7 @@ help:
 	@echo "        cpuset-tests:     run cpuset integration tests (requires root)"
 	@echo "        tarfile:          create the source tarball"
 	@echo "        install:          install rteval locally"
+	@echo "        uninstall:        uninstall rteval"
 	@echo "        clean:            cleanup generated files"
 	@echo "        realclean:        Same as clean plus directory run"
 	@echo "        sysreport:        do a short testrun and generate sysreport data"
@@ -121,4 +145,4 @@ tags:
 cleantags:
 	rm -f tags
 
-.PHONY: tests unit-tests e2e-tests regression-tests cpuset-tests
+.PHONY: tests unit-tests e2e-tests regression-tests cpuset-tests uninstall
pyproject.toml +1 -1
index 9fc681f3f91b..b981ca7d7661 100644
@@ -18,7 +18,7 @@ analyzed for standard statistical measurements (i.e mode, median, range,
 mean, variance and standard deviation) and a report is generated.
 """, content-type = "text/plain"}
 requires-python = ">=3.10"
-license = {text = "GPL-2.0-or-later"}
+license = "GPL-2.0-or-later"
 dependencies = [
     "lxml",
     "requests",
Signature · 1 line
2.54.0