From 75384af30a220e54695ff95359a2f2e7da5e9e81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Date: Thu, 5 May 2022 14:06:51 +0100 Subject: docs: rewrite to refer to meson commands instead of cmake MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Daniel P. Berrangé --- README.md | 9 +++---- docs/testing.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 67 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a8818cf..96d30b9 100644 --- a/README.md +++ b/README.md @@ -58,17 +58,14 @@ Building libvfio-user Build requirements: - * `cmake` (v2 or above) + * `meson` (v0.53.0 or above) * `apt install libjson-c-dev libcmocka-dev` *or* * `yum install json-c-devel libcmocka-devel` To build: - make && make install - -By default a debug build is created. To create a release build do: - - make BUILD_TYPE=rel + meson build + ninja -C build The kernel headers are necessary because VFIO structs and defines are reused. diff --git a/docs/testing.md b/docs/testing.md index 62234d6..d03cadc 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,26 +1,78 @@ Testing ======= -Running `make test` runs most of the integrated tests. You should have -`valgrind` installed. +The tests in libvfio-user are organized into a number of suites -Running `make pre-push` runs the above builds and tests in different configurations: GCC, -clang, and with ASAN enabled. +* unit - old unit tests written in C +* functional - old functional tests using binaries written in C +* pyunit - modern tests written in python +* style - code style checking (eg flake8, rstlint, etc) -There are some [older unit tests](test/unit-tests.c) written in C, but most -tests are now done via Python, in the [test/py](test/py) sub-directory. You can -run just the Python tests via `make pytest` or `make pytest-valgrind`. +Running `meson test -C build` runs all the suites: + +``` +meson build +meson test -C build +``` + +It is possible to be selective about which tests are run +by including or excluding suites: + +``` +meson test -C build --suite=pyunit +meson test -C build --no-suite=pyunit +``` + +The `unit` and `pyunit` suites support optional execution +under valgrind + +``` +meson test -C build --suite=unit --setup=valgrind +meson test -C build --suite=pyunit --setup=pyvalgrind +``` + +To run with ASAN enabled, pass the `-Db_sanitize=address` +option to meson. Note, this is incompatible with enabling +valgrind + +``` +meson build -Db_sanitize=address +meson test -C build +``` + +The `.github/workflows/pull_request.sh` script runs a +sequence of builds in various configurations. This is +invoked for all pull requests, but can be launched +manually by contributors ahead of opening a pull +request. The master branch is run through [Coverity](scan.coverity.com) when a new PR lands. -You can also run `make gcov` to get code coverage reports. +Coverage reports can be enabled via meson, provided `gcovr` is installed: + +``` +meson build -Db_coverage=true +meson test -C build +ninja -C build coverage +``` + +The resulting coverage report can be viewed with + +``` +firefox file:`pwd`/build/meson-logs/coveragereport/index.html +``` Debugging Test Errors --------------------- Sometimes debugging Valgrind errors on Python unit tests can be tricky. To -run specific tests use the pytest `-k` option in `PYTESTCMD` in the Makefile. +run specific tests, pass their name on the command line to `meson`: + +``` +meson build +meson test -C build test_quiesce.py +``` AFL++ ----- @@ -39,11 +91,12 @@ Set up and build: ``` apt update apt-get -y install libjson-c-dev libcmocka-dev clang valgrind \ - python3-pytest debianutils flake8 cmake + python3-pytest debianutils flake8 meson cd /src export AFL_LLVM_LAF_ALL=1 -make CC=afl-clang-fast WITH_TRAN_PIPE=1 +CC=afl-clang-fast meson build -Dtran-pipe=true +ninja -C build mkdir inputs # don't yet have a better starting point -- cgit v1.1