xpadneo, installer: Introduce make-based installer

This adds a new top-level `Makefile` for easy installation via package
managers. Instead of directly building the DKMS module, this allows
a package installer to just provide the source code and install the
support files. Building of the actual module via DKMS is left to the
package maintainer.

To aid following packaging guidelines, two variables are provided:

- `PREFIX`: Allows to install the package to a pre-install image which
  can be put in an archive for package deployment and file tracking. If
  this variable is provided, it will also skip deployment of the DKMS
  source tree. This is mainly due to limitations of DKMS handling
  prefixed installations properly. Package maintainers have to do this
  manually in a post-installation step.

- `ETC_PREFIX`: Allows to install files to `/usr/lib` which would
  normally go to `/etc`. This is applied relative to `PREFIX`.

TL;DR: `dkms add` won't be run if `PREFIX` is provided.

Please read `docs/PACKAGING.md`.

Maybe-fixes: atar-axis#405
Maybe-fixes: atar-axis#425
Maybe-fixes: atar-axis#431
Maybe-fixes: atar-axis#491
Signed-off-by: Kai Krakow <kai@kaishome.de>

Makefile

@@ -0,0 +1,49 @@
+MODPROBE_CONFS := xpadneo.conf
+UDEV_RULES := 60-xpadneo.rules 70-xpadneo-disable-hidraw.rules
+
+ifeq ($(PREFIX),)
+  DKMS ?= dkms
+else
+  $(warning Installing to prefix, dkms commands will not be run!)
+  DKMS ?= : SKIPPING dkms
+endif
+
+ETC_PREFIX ?= $(PREFIX)/etc
+
+all: build
+
+help:
+	@echo "Targets:"
+	@echo "help        This help"
+	@echo "build       Prepare the package for DKMS deployment"
+	@echo "install     Install the package and DKMS source code"
+	@echo "uninstall   Uninstall the package and DKMS source code"
+	@echo
+	@echo "Variables:"
+	@echo "PREFIX      Install files into this prefix"
+	@echo "ETC_PREFIX  Install etc files into this prefix (defaults to \$PREFIX/etc)"
+	@echo
+	@echo "Using PREFIX requires handling dkms commands in your package script."
+
+.PHONY: build install
+
+.INTERMEDIATE: VERSION
+
+VERSION:
+	{ [ -n "$(VERSION)" ] && echo $(VERSION) || git describe --tags --dirty; } >$@
+
+build: VERSION
+	$(MAKE) VERSION="$(shell cat VERSION)" -C hid-xpadneo dkms.conf
+
+install: build
+	mkdir -p $(PREFIX)/etc/modprobe.d $(PREFIX)/etc/udev/rules.d
+	install -D -m 0644 -t $(PREFIX)/etc/modprobe.d $(MODPROBE_CONFS:%=hid-xpadneo/etc-modprobe.d/%)
+	install -D -m 0644 -t $(PREFIX)/etc/udev/rules.d $(UDEV_RULES:%=hid-xpadneo/etc-udev-rules.d/%)
+	$(DKMS) add hid-xpadneo
+
+uninstall: VERSION
+	$(DKMS) remove "hid-xpadneo/$(shell cat VERSION)" --all
+	rm -Rf "$(PREFIX)/usr/src/hid-xpadneo-$(shell cat VERSION)"
+	rm -f $(PREFIX)$(UDEV_RULES:%=$(ETC_PREFIX)/udev/rules.d/%)
+	rm -f $(PREFIX)$(MODPROBE_CONFS:%=$(ETC_PREFIX)/modprobe.d/%)
+	rmdir --ignore-fail-on-non-empty -p $(PREFIX)/etc/modprobe.d $(PREFIX)/etc/udev/rules.d

docs/PACKAGING.md

@@ -0,0 +1,117 @@
+## Packaging
+
+From v0.10 on, xpadneo provides a `Makefile` to help package maintainers
+avoding a lot of the duplicate work which was historically done by the
+installer script. This also allows for prefixed installation to prepare an
+install image before merging the package to the live system.
+
+Run `make help` for an overview of the options.
+
+
+### Configuration
+
+The top-level `Makefile` supports some configuration variables:
+
+- `PREFIX`: Allows to install the package to a pre-install image which
+  can be put in an archive for package deployment and file tracking. If
+  this variable is provided, it will also skip deployment of the DKMS
+  source tree. This is mainly due to limitations of DKMS handling
+  prefixed installations properly. Package maintainers have to do this
+  manually in a post-installation step.
+
+- `ETC_PREFIX`: Allows to install files to `/usr/lib` which would
+  normally go to `/etc`. This is applied relative to `PREFIX`.
+
+**Example:**
+```bash
+make PREFIX=/tmp/xpadneo-image ETC_PREFIX=/usr/lib install
+```
+
+
+### Installation
+
+When using the `Makefile`, xpadneo will no longer automatically try to build
+the DKMS module. How to handle this in detail is left up to the package
+maintainer. If you run `make install` without a `PREFIX` or use an empty
+prefix, `make install` will run `dkms add` to add the source code to the
+DKMS source tree. No other DKMS action will be taken.
+
+**Examples:**
+```bash
+# Install package files to `/` and deploy the DKMS sources
+make install
+
+# Install package files but deploy the DKMS sources as a separate step
+make PREFIX=/ install
+dkms add hid-xpadneo
+```
+
+Instead of directly building the DKMS module, this allows a package installer
+to just provide the source code and install the support files. Building of
+the actual module via DKMS is left to the package maintainer.
+
+Many distributions recommend to install base configuration to `/usr/lib`
+instead of `/etc`. The make-based installer supports this by supplying a
+`ETC_PREFIX` variable.
+
+**Example:**
+```bash
+# Install package files to `/usr/lib` instead of `/etc`
+make ETC_PREFIX=/usr/lib install
+
+# This can be combined with prefixed installation
+make PREFIX=/tmp/xpadneo-image ETC_PREFIX=/usr/lib install
+dmks add hid-xpadneo
+```
+
+In all these usages, xpadneo will never try to build and install the kernel
+module on its own. This step is left up to the package maintainer.
+
+**Background:** DKMS does not support prefixed installations. If you try to
+do so, symlinks will point to the wrong location. DKMS also doesn't support
+proper uninstallation: It will remove the kernel module from its build system
+but it won't touch the files it copied to `/usr/src` during `dkms add`.
+Package maintainers are required to properly handle this according to their
+specific distribution. xpadneo won't try to mess with this to prevent errors
+in the boot system of the distribution. It cannot know the implementation
+details.
+
+`make PREFIX=...` will warn about this but still show the command which would
+be run:
+```
+# make PREFIX=...
+Makefile:7: Installing to prefix, dkms commands will not be run!
+...
+: SKIPPING dkms add hid-xpadneo
+```
+
+
+### Uninstallation
+
+Package maintainers usually don't need to care about uninstallation because
+the packaging system tracks installed files and also properly removes them.
+Still, xpadneo provides `make uninstall` which runs the following steps for
+that **exact** xpadneo version only:
+
+1. Removes xpadneo from *all* kernel instances of DKMS
+2. Removes xpadneo kernel sources from `/usr/src`
+3. Removes installed udev rules and module configurations **unconditionally**
+
+Step 3 means that it will remove files which may be shared with an already
+installed xpadneo package. **Be careful!**
+
+If using `PREFIX` or `ETC_PREFIX`, the same rules as above apply: If a
+`PREFIX` is provided, `dkms remove` won't be run.
+
+This is not meant to be used by package maintainers as part of handling the
+package installation. It is a development tool.
+
+
+### Summary
+
+Package maintainers are adviced to migration to the new installation method.
+Please provide feedback if you see problems or missing features.
+
+Package maintainers **SHOULD NOT** use `install.sh` or its sibling scripts
+to maintain the installation. But you may use the contents of it as a guide
+for your package installation script.

docs/README.md

@@ -37,6 +37,11 @@ Quote from [@atar-axis (Florian Dollinger)](https://github.com/atar-axis), creat
 These other projects may not support some of the advanced features of xpadneo.
 
 
+## Heads Up
+
+**Package maintainers:** Please see [Packaging](https://atar-axis.github.io/xpadneo/#packaging).
+
+
 ## Breaking Changes
 
 ### Kernel 4.18 or newer required

docs/index.md

@@ -2,6 +2,7 @@
 {% include_relative BT_DONGLES.md %}
 {% include_relative CONFIGURATION.md %}
 {% include_relative TROUBLESHOOTING.md %}
+{% include_relative PACKAGING.md %}
 {% include_relative DEBUGGING.md %}
 {% include_relative 3P-BUGS.md %}
 {% include_relative SDL.md %}

hid-xpadneo/Makefile

@@ -6,7 +6,9 @@ all: modules
 .INTERMEDIATE: ../VERSION
 
 ../VERSION:
-	git describe --tags --dirty >$@
+	$(MAKE) -C .. $(@:../%=%)
+
+# convenience rules for local dvelopment
 
 clean modules modules_install: ../VERSION
 	$(MAKE) -C $(KERNEL_SOURCE_DIR) INSTALL_MOD_DIR="kernel/drivers/hid" LD=$(LD) M=$(shell pwd)/src VERSION="$(shell cat ../VERSION)" $@
@@ -16,5 +18,7 @@ reinstall: modules
 	sudo rmmod hid-xpadneo || true
 	sudo modprobe hid-xpadneo $(MOD_PARAMS)
 
+# DKMS support rules
+
 dkms.conf: dkms.conf.in ../VERSION
 	sed 's/"@DO_NOT_CHANGE@"/"$(shell cat ../VERSION)"/g' <"$<" >"$@"

lib/installer.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+[ -n "${PREFIX}" ] && { echo >&2 "ERROR: Prefix installations are not supported, use make instead."; exit 1; }
+
 if [ ${EUID} -ne 0 ]; then
 	echo >&2 "ERROR: You most probably need superuser privileges to use this script, please run me via sudo!"
 	exit 3