Merge pull request #148 from Perfexionists/release-0.21.7

Release 0.21.7

.github/workflows/release.yml

@@ -11,12 +11,25 @@ jobs:
   release:
     if: ${{ github.event.pull_request.merged == true && contains(github.head_ref, 'release') }}
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
     steps:
       - name: Checkout latest version
         uses: actions/checkout@v3
         with:
           ref: devel
 
+      - name: Setup Python, Ubuntu and Python environment
+        uses: ./.github/workflows/actions/setup
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Perun (to assure it is correctly installed) and try obtaining the version
+        run: |
+          make install
+          perun --version
+
       - name: Set version
         id: manual-tagger
         run: echo "NEW_TAG=$(perun --version | cut -d' ' -f2)" >> "$GITHUB_OUTPUT"

.gitignore

@@ -1,13 +1,19 @@
-# Perun
+# Perun / Perun specific
 .perun/
+tests/sources/fuzz_examples/hang-init/hang
+tests/sources/fuzz_examples/hang-test/hang
+tests/sources/fuzz_examples/sigabrt-init/sigabrt
+tests/sources/fuzz_examples/sigabrt-test/sigabrt
+tests/sources/fuzz_examples/tail/tail
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
-*.py[cod]
+*.py[cod~]
 *$py.class
 
-# C extensions
+# C/C++ extensions
 *.so
+*.o
 
 # Distribution / packaging
 .Python
@@ -53,6 +59,9 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+*.gcda
+*.gcno
+*.gcov
 
 # Translations
 *.mo
@@ -181,3 +190,6 @@ com_crashlytics_export_strings.xml
 crashlytics.properties
 crashlytics-build.properties
 fabric.properties
+
+# Profiling
+prof/

AUTHORS.rst

@@ -1,10 +1,19 @@
+
 ===============
 Main Developers
 ===============
 
-The following lists the authors (active ones are bold)
+The following lists the authors (active ones are bold) that contributed to upstream (or to some fork) of Perun:
+
+  * **Tomas Fiedor**: |github| `tfiedor <https://github.com/tfiedor>`_ |email| `[email protected] <mailto: [email protected]>`_ (founder), core
+  * **Jiri Pavela**: |github| `JiriPavela <https://github.com/JiriPavela>`_ |email| `[email protected] <mailto: [email protected]>`_ tracer, core
+  * **Ondrej Michal**: |github| `HarryMichal <https://github.com/HarryMichal>`_ [energy profiler](https://gitlab.com/martymichal/sysrapl)
+  * **Peter Mocary**: |github| `PeterMocary <https://github.com/PeterMocary>`_ tracer
+  * Martina Grzybowska: GUI
+  * Vojtech Hajek: C# profiler
+  * Matus Liscinsky: fuzzing, perfblowing
+  * Radim Podola: |email| `[email protected] <mailto: [email protected]>`_ memory
+  * Simon Stupinsky: |email| `[email protected] <mailto: [email protected]>`_ models
 
-  * **Tomas Fiedor** <[email protected]> (founder)
-  * **Jiri Pavela** <[email protected]>
-  * Radim Podola <[email protected]>
-  * **Simon Stupinsky** <[email protected]>
+.. |github| image:: ./figs/icon-github.svg
+.. |email| image:: ./figs/icon-email.svg

CHANGELOG.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+0.21.7 (2023-11-08)
+-------------------
+
+  - Update README, licensing, authors and contributions.
+  - Fix minor issues in README, and various parts of Perun.
+  - Fix minor issue in helper scripts.
+
 0.21.6 (2023-11-06)
 -------------------
 

CONTRIBUTING

@@ -1,12 +1,20 @@
 Contributing
 ============
 
-In case you run in some unexpected behaviour, error or anything suspicious, either contact us
+In case you run into some unexpected behaviour, error or anything suspicious, either contact us
 directly through mail or [create a new Issue](https://github.com/Perfexionists/perun/issues/new).
 
-If you'd like to contribute, please fork the repository and use a new feature branch starting from
-the `develop` the develop branch. Pull requests are warmly welcome! However, please follow these
-guidelines:
+We build Perun so it is easily extensible. In case you are interested in extending our tool
+suite with new kinds of collectors, postprocessors or visualization methods, please refer to
+appropriate sections in Perun's documentation (i.e. Create your own
+[collector](https://perfexionists.github.io/perun/collectors.html#creating-your-own-collector),
+[postprocessor](https://perfexionists.github.io/perun/postprocessors.html#creating-your-own-postprocessor)
+or [visualization](https://perfexionists.github.io/perun/views.html#creating-your-own-visualization)).
+Do not hesitate to contact us, if you run into any problems.
+
+If you'd like to contribute, please first fork our repository and create a new dedicated feature branch starting from
+the `develop`  branch. Pull requests are warmly welcome! We will surely review the contribution (possibly request
+some changes). However, please follow these guidelines:
 
   1. **Document your code properly**---refer to 
   [sphinx documentation](http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain) 
@@ -16,21 +24,21 @@ guidelines:
   <https://github.com/Perfexionists/perun/tree/develop/tests> directory and should achieve a suitable
   amount of codecov coverage.
 
-  3. **Follow the project formatting** by utilising [Black](https://github.com/psf/black).
+  3. **Follow the project formatting**; we recommend using the [black](https://github.com/psf/black) formatter.
 
-  4. **Commit properly**, write meaningful commit messages, with first short line being short
+  4. **Commit properly**: write meaningful commit messages; we recommend to write first short line as a short
   description that can be included into the following template: "This commit will ___".
 
 Before considering a merge of pull requests we want the feature branch to fulfill the following:
 
-  1. The branch must be compilable (i.e. Travis checks are passing)
-  2. The tests cover reasonable proportion of code (i.e. codecov checks are passing)
-  3. The code has no issues checked by codacy and codeclimate (however, some checks may require
-  manual confirmation---e.g. the levels of cyclomatic complexity)
+  1. The branch must be compilable (i.e. Github Action checks are passing);
+  2. The tests cover reasonable proportion of code (i.e. codecov checks are passing);
+  3. The code has no issues checked by codacy;
+  4. At least one of the major maintainers has reviewed the code.
 
 If you think your extension could help others, please [send us
-PR](https://github.com/Perfexionists/perun/pull/new/develop), we will review the code and in case it is
-indeed suitable for wider audience and maintainable, we will include it in our
+PR](https://github.com/Perfexionists/perun/pull/new/develop), we will review the code and in case it is,
+indeed, suitable for wider audience and maintainable, we will include it in our
 [upstream](https://github.com/Perfexionists/perun).
 
 *But, please be understanding; we cannot fix and merge everything.*

INSTALL-tracer.md

@@ -0,0 +1,108 @@
+### Installing dependencies for tracer
+
+Perun supports multiple collectors of performance metrics.
+Our most advanced collector is Tracer (runnable by `perun collect trace`),
+which has additional dependencies.
+
+The standard Perun installation does not automatically install the instrumentation frameworks
+used by Tracer: SystemTap and eBPF. Installing these frameworks is optional when using Perun, 
+although having at least one of them is required in order to run Tracer. Moreover, both frameworks 
+rely on system-wide packages and thus should be installed directly by the user when needed.
+
+#### SystemTap (Ubuntu)
+
+In Ubuntu, SystemTap can be installed using `apt-get` package manager:
+
+    sudo apt-get install systemtap
+
+Furthermore, kernel debug symbols package must be installed in order to use SystemTap. 
+For Ubuntu 16.04 and higher run the following:
+
+    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C8CAB6595FDFF622 
+    codename=$(lsb_release -c | awk  '{print $2}')
+    sudo tee /etc/apt/sources.list.d/ddebs.list << EOF
+    deb http://ddebs.ubuntu.com/ ${codename}      main restricted universe multiverse
+    deb http://ddebs.ubuntu.com/ ${codename}-security main restricted universe multiverse
+    deb http://ddebs.ubuntu.com/ ${codename}-updates  main restricted universe multiverse
+    deb http://ddebs.ubuntu.com/ ${codename}-proposed main restricted universe multiverse
+    EOF
+
+    sudo apt-get update
+    sudo apt-get install linux-image-$(uname -r)-dbgsym
+
+To test that SystemTap works correctly, you can run the following command:
+
+    stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'
+
+For more information, see the [source](https://wiki.ubuntu.com/Kernel/Systemtap).
+
+#### SystemTap (Fedora)
+
+In Fedora, SystemTap can be installed using `yum` package manager:
+
+    sudo yum install systemtap systemtap-runtime
+
+Similarly to the Ubuntu, additional kernel packages must be installed to run SystemTap properly:
+
+    kernel-debuginfo
+    kernel-debuginfo-common
+    kernel-devel
+
+Different Fedora versions use different methods for obtaining those packages. Please refer to
+the [SystemTap setup guide](https://www.sourceware.org/systemtap/SystemTap_Beginners_Guide/using-systemtap.html#using-setup)
+
+#### BCC (Ubuntu)
+
+Tracer uses the [BCC (BPF Compiler Collection)](https://github.com/iovisor/bcc) frontend for the eBPF engine;
+eBPF is a framework that allows us to instrument the profile programs. 
+We recommend to install the necessary packages from the IO Visor repository as follows:
+
+    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 4052245BD4284CDD
+    echo "deb https://repo.iovisor.org/apt/$(lsb_release -cs) $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/iovisor.list
+    sudo apt-get update
+    sudo apt-get install bcc-tools libbcc-examples linux-headers-$(uname -r)
+
+The default BCC installation uses bindings for Python 2, however, Perun requires bindings for
+Python 3. To install them, run the following command:
+
+    sudo apt-get install python3-bcc
+
+#### BCC (Fedora)
+
+Installing BCC on Fedora is much easier. Simply run:
+
+    sudo dnf install bcc python3-bcc
+
+#### BCC (python virtualenv)
+
+Note that when using Perun in a Python virtual environment, the above installation instructions
+are not enough. Since the Python `bcc` package is not available through `pip`, installing it
+directly in a virtualenv using pip requirements list is not an option. A common workaround is
+to copy the system-wide python `bcc` package installed in the previous step (`python3-bcc`) 
+into the virtualenv packages.
+
+To find the system python3 `bcc` package, run:
+
+    python3 -c "import site; print(site.getsitepackages())"
+
+which shows the global site-packages paths (be warned that not all paths must necessarily exist).
+The package `bcc` should be located in at least one the listed path (otherwise the installation of 
+`python3-bcc` must have failed in the previous step). The resulting path may look like e.g.:
+
+    /usr/lib/python3/dist-packages
+
+Now activate the virtual environment and run the same command to get the list of site-packages paths 
+local to the virtualenv and find one which does exists:
+
+    <prefix>/venv-3.8/lib/python3.8/site-packages
+
+Next, copy the `bcc` package from the global site-packages to the virtualenv local site-packages:
+
+    cp -r /usr/lib/python3/dist-packages/bcc <prefix>/venv-3.8/lib/python3.8/site-packages/
+
+Now the `bcc` package should be available in the virtualenv python. 
+You can test it with the following command with activated virtualenv:
+
+    python3 -c "import bcc"
+
+which should successfully finish (i.e. `ModuleNotFoundError` should not be raised).

Makefile

@@ -1,9 +1,3 @@
-test:
-	python3 -m pytest --durations=10 --cov=./ --cov-report term-missing:skip-covered tests/
-
-check:
-	mypy perun/
-
 # Setuptools fails for nested requirements file when installed as `pip install .`, so sadly no
 # simple "dev" optional dependency
 dev:
@@ -12,6 +6,15 @@ dev:
 install:
 	pip3 install .
 
+init-test:
+	pip3 install .[test]
+
+test:
+	python3 -m pytest --durations=10 --cov=./ --cov-report term-missing:skip-covered tests/
+
+check:
+	mypy perun/
+
 docs:
 	$(MAKE) -C docs html