test: make the test suite runner available as installed binary

Available as 'libinput test-suite'. This also renames the bit in the build
directory now.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

doc/user/test-suite.rst

@@ -5,8 +5,8 @@ libinput test suite
 ==============================================================================
 
 libinput ships with a number of tests all run automatically on ``ninja test``.
-The primary test suite is the ``libinput-test-suite-runner``. When testing,
-the ``libinput-test-suite-runner`` should always be invoked to check for
+The primary test suite is the ``libinput-test-suite``. When testing,
+the ``libinput-test-suite`` should always be invoked to check for
 behavior changes. The test suite relies on the kernel and udev to function
 correctly. It is not suitable for running inside containers.
 
@@ -66,7 +66,7 @@ run for a device.
 
 ::
 
-     $ ./builddir/libinput-test-suite-runner --list
+     $ ./builddir/libinput-test-suite --list
      ...
      pointer:left-handed:
 	pointer_left_handed_during_click_multiple_buttons:
@@ -121,7 +121,7 @@ basic shell-style function name matching. For example:
 
 ::
 
-     $ ./builddir/libinput-test-suite-runner --filter-test="*1fg_tap*"
+     $ ./builddir/libinput-test-suite --filter-test="*1fg_tap*"
 
 
 The ``--filter-device`` argument enables selective running of tests through
@@ -131,7 +131,7 @@ litest-specific shortnames, see the output of ``--list``. For example:
 
 ::
 
-     $ ./builddir/libinput-test-suite-runner --filter-device="synaptics*"
+     $ ./builddir/libinput-test-suite --filter-device="synaptics*"
 
 
 The ``--filter-group`` argument enables selective running of test groups
@@ -141,7 +141,7 @@ litest-specific test groups, see the output of ``--list``. For example:
 
 ::
 
-     $ ./builddir/libinput-test-suite-runner --filter-group="touchpad:*hover*"
+     $ ./builddir/libinput-test-suite --filter-group="touchpad:*hover*"
 
 
 The ``--filter-device`` and ``--filter-group`` arguments can be combined with
@@ -160,5 +160,33 @@ environment variable, if set, also enables verbose mode.
 
 ::
 
-     $ ./builddir/libinput-test-suite-runner --verbose
+     $ ./builddir/libinput-test-suite --verbose
      $ LITEST_VERBOSE=1 ninja test
+
+.. _test-installed:
+
+------------------------------------------------------------------------------
+Installing the test suite
+------------------------------------------------------------------------------
+
+If libinput is configured to install the tests, the test suite is available
+as the ``libinput test-suite`` command. When run as installed binary, the
+behavior of the test suite changes:
+
+- the ``libinput.so`` used is the one in the library lookup paths
+- no system-wide quirks are installed by the test suite, only those specific
+  to the test devices
+- test device-specific quirks are installed in the system-wide quirks
+  directory, usually ``/usr/share/libinput/``.
+
+It is not advisable to run ``libinput test-suite`` on a production machine.
+Data loss may occur. The primary use-case for the installed test suite is
+verification of distribution composes.
+
+.. note:: The ``prefix`` is still used by the test suite. For verification
+	of a system package, the test suite must be configured with the same prefix.
+
+To configure libinput to install the tests, use the ``-Dinstall-tests=true``
+meson option::
+
+  $ meson builddir -Dtests=true -Dinstall-tests=true <other options>

meson.build

@@ -406,6 +406,7 @@ dep_tools_shared = declare_dependency(link_with : lib_tools_shared,
 
 man_config = configuration_data()
 man_config.set('LIBINPUT_VERSION', meson.project_version())
+man_config.set('LIBINPUT_DATA_DIR', dir_data)
 
 deps_tools = [ dep_tools_shared, dep_libinput ]
 libinput_debug_events_sources = [ 'tools/libinput-debug-events.c' ]
@@ -843,11 +844,19 @@ if get_option('tests')
 		'test/test-switch.c',
 		'test/test-quirks.c',
 	]
-	libinput_test_runner = executable('libinput-test-suite-runner',
+	libinput_test_runner = executable('libinput-test-suite',
 					  libinput_test_runner_sources,
 					  include_directories : [includes_src, includes_include],
 					  dependencies : deps_litest,
-					  install : false)
+					  install_dir : libinput_tool_path,
+					  install : get_option('install-tests'))
+	configure_file(input : 'test/libinput-test-suite.man',
+		       output : 'libinput-test-suite.1',
+		       configuration : man_config,
+		       install : true,
+		       install_dir : dir_man1,
+		       )
+
 	test('libinput-test-suite-runner',
 	     libinput_test_runner,
 	     timeout : 1200)

meson_options.txt

@@ -18,6 +18,10 @@ option('tests',
        type: 'boolean',
        value: true,
        description: 'Build the tests [default=true]')
+option('install-tests',
+       type: 'boolean',
+       value: false,
+       description: 'Install the libinput test command [default=false]')
 option('documentation',
        type: 'boolean',
        value: true,

test/libinput-test-suite.man

@@ -0,0 +1,95 @@
+.TH libinput-test-suite "1" "" "libinput @LIBINPUT_VERSION@" "libinput Manual"
+.SH NAME
+libinput\-test\-suite \- run the libinput test suite
+.SH SYNOPSIS
+.B libinput test\-suite [OPTIONS]
+.PP
+.SH DESCRIPTION
+.PP
+The
+.B "libinput test\-suite"
+command runs the libinput test suite.
+Its primary purpose is to verify distribution composes after package updates. Test
+suite failures usually indicate missing patches and/or incompatible lower
+system layers.
+.PP
+.B The test suite should not be run by users. Data loss is possible.
+.PP
+The test suite must be run as root. The test suite installs several files
+on the host system (see section \fBFILES\fR), runs system commands and
+creates virtual kernel devices via uinput. These devices will interfere with
+any active session and may cause data loss.
+.PP
+It is recommended that the test suite is run in a virtual machine and/or on
+a system not otherwise in use. A graphical environment is not required to
+run the test suite.
+
+.SH OPTIONS
+Note that the options may change in future releases of libinput. Test names,
+test device names and test group names may change at any time.
+.TP 8
+.B \-\-filter\-test \fI"testname"\fB
+A glob limiting the tests to run. Specifying a filter sets the
+\fB\-\-jobs\fR default to 1.
+.TP 8
+.B \-\-filter\-device \fI"devicename"\fB
+A glob limiting the devices to run tests for. Specifying a filter sets the
+\fB\-\-jobs\fR default to 1.
+.TP 8
+.B \-\-filter\-group \fI"groupname"\fB
+A glob limiting the tests to (arbitrarily named) groups. Specifying a filter sets the
+\fB\-\-jobs\fR default to 1.
+.TP 8
+.B \-\-filter\-deviceless
+\fBFOR INTERNAL USE ONLY\fR
+.TP 8
+.B \-h, \-\-help
+Print help
+.TP 8
+.B \-j, \-\-jobs 8
+Number of parallel processes to run. Default: 8.
+.TP 8
+.B \-\-list
+List all test cases and the devices they are run for. Test names, test device
+names and test group names may change at any time.
+.TP 8
+.B \-\-verbose
+Enable verbose output, including libinput debug messages.
+.SH FILES
+The following directories are modified:
+
+.TP 8
+.B @LIBINPUT_DATA_DIR@
+Test device-specific quirks are installed in this directory with a custom
+prefix. Files in this directory are untouched but new files are installed
+and removed on exit. Existing files (e.g. from a previous aborted run) with
+the same name will be silently overwritten and removed.
+.TP 8
+.B /run/udev/rules.d
+Test-specific udev rules are installed in this directory and removed on
+exit.
+.PP
+.SH SYSTEM SETUP
+The \fBxorg.conf.d(5)\fR snippet below ensures the X server ignores the test
+devices created by this test suite:
+.PP
+.RS 4
+.nf
+.B "Section ""InputClass""
+.B "        Identifier ""libinput test suite blacklist""
+.B "        MatchProduct ""litest""
+.B "        Option ""Ignore"" ""on""
+.B "EndSection"
+.fi
+.RE
+.PP
+No configuration is required for Wayland compositors. libinput's default
+mode will ignore test devices from this test suite.
+.SH BUGS
+Some tests are sensitive to timing. Where a system is under heavy load,
+a test may fail. Re-running the test with \fB\-\-filter-test\fR can help
+verify whether a test case failure was a true failure.
+.SH LIBINPUT
+Part of the
+.B libinput(1)
+suite

test/litest.c

@@ -58,6 +58,7 @@
 #include "litest-int.h"
 #include "libinput-util.h"
 #include "quirks.h"
+#include "builddir.h"
 
 #include <linux/kd.h>
 
@@ -3900,26 +3901,31 @@ litest_parse_argv(int argc, char **argv)
 		OPT_JOBS,
 		OPT_LIST,
 		OPT_VERBOSE,
-		OPT_SYSTEM_QUIRKS,
 	};
 	static const struct option opts[] = {
 		{ "filter-test", 1, 0, OPT_FILTER_TEST },
 		{ "filter-device", 1, 0, OPT_FILTER_DEVICE },
 		{ "filter-group", 1, 0, OPT_FILTER_GROUP },
 		{ "filter-deviceless", 0, 0, OPT_FILTER_DEVICELESS },
-		{ "use-system-quirks", 0, 0, OPT_SYSTEM_QUIRKS },
 		{ "jobs", 1, 0, OPT_JOBS },
 		{ "list", 0, 0, OPT_LIST },
 		{ "verbose", 0, 0, OPT_VERBOSE },
 		{ "help", 0, 0, 'h'},
 		{ 0, 0, 0, 0}
 	};
-
 	enum {
 		JOBS_DEFAULT,
 		JOBS_SINGLE,
 		JOBS_CUSTOM
 	} want_jobs = JOBS_DEFAULT;
+	char *builddir;
+
+	/* If we are not running from the builddir, we assume we're running
+	 * against the system as installed */
+	builddir = builddir_lookup();
+	if (!builddir)
+		skip_quirks_install = true;
+	free(builddir);
 
 	if (in_debugger)
 		want_jobs = JOBS_SINGLE;
@@ -3984,9 +3990,6 @@ litest_parse_argv(int argc, char **argv)
 		case OPT_FILTER_DEVICELESS:
 			run_deviceless = true;
 			break;
-		case OPT_SYSTEM_QUIRKS:
-			skip_quirks_install = true;
-			break;
 		}
 	}