Clear-up some packaging issues.

This commit:

    1. addresses issue #3 by providing an Arch package with
       releases
    2. addresses issue #4 by providing a systemd unit

.github/workflows/release.yml

@@ -156,6 +156,7 @@ jobs:
         staging="mpdpopm-${{ env.RELEASE_VERSION }}-${{ matrix.target }}"
         mkdir -p "$staging"/{bin,doc}
         cp -v {README.org,AUTHORS,ChangeLog,COPYING,NEWS,THANKS} "$staging/doc/"
+        cp -v mpdpopm/mpdpopm.{conf,service} "$staging/doc/"
         cp -v mpdpopm/target/release/mppopm{,d} "$staging/bin"
         tar czf "$staging.tar.gz" "$staging"
         echo "ASSET=$staging.tar.gz" >> $GITHUB_ENV

.gitignore

@@ -10,3 +10,5 @@ configure
 Makefile
 config.log
 config.status
+PKGBUILD
+*.deb

ChangeLog

@@ -1,4 +1,19 @@
-2020-12-16  Michael Herstine  <[email protected]>
+2021-03-08  Michael Herstine  <[email protected]>
+
+	Clear-up some packaging issues.
+	This commit:
+
+	    1. addresses issue #3 by providing an Arch package with
+	       releases
+	    2. addresses issue #4 by providing a systemd unit
+
+2020-12-19  Michael Herstine  <[email protected]>
+
+	Commenting out the hard-coded release number in release.yml.
+
+2020-12-17  Michael Herstine  <[email protected]>
+
+	Fixing-up release workflow
 
 	Address issue #2.
 	This commit contains no new code or features; rather it is a

NEWS

@@ -1,5 +1,12 @@
 mpdpopm News -- history of user-visible changes           -*- outline -*-
 
+* 0.1.15 build
+
+** User-visible changes
+
+*** Include sample configuration & systemd unit files
+
+*** Begin providing an Arch package
 * 0.1.14 build
 
 ** User-visible changes

README.org

@@ -2,7 +2,7 @@
 #+AUTHOR: Michael Herstine
 #+DESCRIPTION: mpdpopm
 #+EMAIL: [email protected]
-#+DATE: <2020-12-16 Wed 19:36>
+#+DATE: <2021-03-05 Fri 17:22>
 #+AUTODATE: t
 
 * Introduction
@@ -172,23 +172,24 @@ The format is a LISP S-expression in which individual, top-level items are expre
 
 Entries:
 
-  - log :: file to which the daemon will log when running in the background (if you specify the =-F= flag, to run it in the foreground, it will log to =stdout=); no log rotation is provided, so either setup =logrotate= or keep an eye on it so it doesn't grow too large.
+  - log :: file to which the daemon will log when running in the background (if you specify the =-F= flag, to run it in the foreground, it will log to =stdout=); no log rotation is provided, so either setup =logrotate= or keep an eye on it so it doesn't grow too large. If not provided, will default to =$LOCALSTATEDIR/log/mppopmd.log=, where =$LOCALSTATEDIR= is =${prefix}/var= if you installed with Autotools, or just =/usr/local= otherwise.
   - host :: IP address on which the MPD daemon is listening (should match =bind_to_address= in your =mpd= configuration file); defaults to "localhost"
   - port :: port on which the =mpd= daemon is listening (should match =port= in your =mpd= configuration file); defaults to 6600
-  - local_music_dir :: the root of your MPD music directory, as seen from this host
+  - local_music_dir :: the root of your MPD music directory, as seen from this host. Defaults to =${prefix}/Music= if you installed with Autotools, or just =/usr/local/Music= otherwise. This is only used when invoking commands (associated with playcounts, ratings &c, or just generalized commands) when they use the %full-file parameter. Therefore, if the music directory isn't available from the host on which you are running =mppopmd= this can be left defaulted, but those features will be unavailable.
   - playcount_sticker :: the sticker name mpdpopm will use to store play counts (defaults to "unwoundstack.com:playcount")
   - lastplayed_sticker :: the sticker name mpdpopm will use to store the last played timestamp (defaults to "unwoundstack.com:lastplayed")
   - rating_sticker :: the sticker name mpdpopm will use to store the rating (defaults to "unwoundstack.com:rating")
   - played_thresh :: the percentage of a song's duration that must be played back in order for it to be considered as "played", expressed as number between 0 & 1 (defaults to 0.6)
-  - poll_interval_ms :: the amount of time, in milliseconds, between polls of =mpd= by =mppopmd= to check on playback progress
+  - poll_interval_ms :: the amount of time, in milliseconds, between polls of =mpd= by =mppopmd= to check on playback progress. Defaults to 5000 (i.e. five seconds).
   - commands_chan :: name of the MPD channel on which =mppopmd= shall listen for commands ("unwoundstack.com:commands" by default)
-  - playcount_command :: optional name of a program to run when the play count is incremented; this should be an absolute path. use playcount_command_args to specify arguments to this command
-  - playcount_command_args :: an array of arguments to specify to the playcount command; arguments may contain replacement parameters that will be filled in at the time of execution (on which more below)
-  - ratings :: optional name of a program to run when the rating is set; this should be an absolute path. use rating to specify arguments to this command
-  - ratings_command_args :: an array of arguments to specify to the ratings command; arguments may contain replacement parameters that will be filled in at the time of execution (on which more below)
+  - playcount_command :: optional name of a program to run when the play count is incremented; this should be an absolute path. use playcount_command_args to specify arguments to this command. Defaults to none.
+  - playcount_command_args :: an array of arguments to specify to the playcount command; arguments may contain replacement parameters that will be filled in at the time of execution (on which more below)-- defaults to none.
+  - ratings_command :: optional name of a program to run when the rating is set; this should be an absolute path. use rating to specify arguments to this command; defaults to none.
+  - ratings_command_args :: an array of arguments to specify to the ratings command; arguments may contain replacement parameters that will be filled in at the time of execution (on which more below); defaults to none.
 
 There is an additional configuration parameter not documented here: =gen_cmds=. That is described below.
 
+Finally, depending on how you installed =mpdpopm=, you may have a sample configuration file already. The Autotools distributions will install the sample to =$(docdir)/examples= (where =$(docdir)= is =${prefix}/share/doc/mpdpopm= by default). The Debian package installs it to =/usr/local/share/doc/mpdpopm/examples=. The pre-built binaries include it in the =doc= folder.
 **** Starting the Daemon
 
 Once you've got your configuration file prepared, you should probably start the daemon in the foreground for ease of trouble-shooting. I suggest starting it with the =-v= flag ("verbose") the first time, as well (there's also a =-d= flag which will produce more copious debug output). You should expect to see something like this:
@@ -244,6 +245,7 @@ In this example, =mppopmd= noticed that "Boplicity" by Miles Davis started playi
 
 Once things seem to be working, you might consider removing the =-F= flag & running =mppopmd= as a proper daemon.
 
+[[https://github.com/tanshoku][tanshoku]] was kind enough to contribute a systemd unit for this purpose. At present, the build does not install it, but provides it as an example and leaves it to the user to install should they desire (and after they have edited it to suit their configuration). You can find it in =${prefix}/share/mpdpopm/examples= for the Autotools distribution, =/usr/local/share/mpdpopm/examples= for the Debian package, and in the =doc= folder for the pre-built binaries.
 *** mppopm
 
 At this point, [[https://github.com/sp1ff/mpdpopm][mpdpopm]] will happily monitor your playback history & keep play counts & last played timestamps for you. If you would like to rate tracks, however, you will need to somehow induce your favorite mpd client to send a "rating" message to the [[https://github.com/sp1ff/mpdpopm][mpdpopm]] commands channel ("unwoundstack.com:commands" by default). Since this is unlikely to be convenient, I wrote an mpd client for the purpose: a little CLI called =mppopm=. You can simply execute

THANKS

@@ -1,3 +1,6 @@
+Thanks to tanshoku <https://github.com/tanshoku> for contributing
+the systemd unit.
+
 Thanks to Vincent Petithory <[email protected]> for
 `mpdfav'. Thanks to Ali Polatel <[email protected]> for `mpdcron'.
 

admin/Dockerfile-arch

@@ -0,0 +1,35 @@
+# Docker image for building, debugging & packaging    -*- mode: dockerfile; -*-
+FROM archlinux:latest AS base
+
+# Bootstrap
+RUN pacman --noconfirm -Syu && \
+	cp -v /etc/pacman.conf /etc/pacman.conf.orig && \
+	sed -e 's/^NoExtract/# NoExtract/' /etc/pacman.conf > /tmp/pacman.conf.tmp && \
+	cp -v /tmp/pacman.conf.tmp /etc/pacman.conf
+
+# WORKAROUND for glibc 2.33 and old Docker
+# See https://github.com/actions/virtual-environments/issues/2658
+# Thanks to https://github.com/lxqt/lxqt-panel/pull/1562
+RUN patched_glibc=glibc-linux4-2.33-4-x86_64.pkg.tar.zst && \
+    curl -LO "https://repo.archlinuxcn.org/x86_64/$patched_glibc" && \
+    bsdtar -C / -xvf "$patched_glibc"
+
+RUN pacman --noconfirm -S man-db man-pages vim base-devel gdb rust cargo && \
+ 	ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime && \
+	useradd -ms /bin/bash -G users,wheel mgh && \
+	echo 'mgh:mgh' | chpasswd && \
+	echo "%wheel ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers && \
+	mkdir /cores && chmod 777 /cores && \
+	echo "kernel.core_pattern=/cores/core.%e.%p" >> /etc/sysctl.d/50-coredump.conf
+
+# TODO(sp1ff): needed?
+# sysctl -p /etc/sysctl.d/50-coredump.conf
+# RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | bash -s -- -y
+
+USER mgh
+
+ENV PATH="/home/mgh/.cargo/bin:${PATH}"
+
+RUN cargo install cargo-aur && \
+	cargo install cargo-arch
+

admin/Dockerfile-debian

@@ -0,0 +1,32 @@
+# Docker image for building, debugging & packaging     -*- mode: dockerfile -*-
+FROM debian:stable-slim AS base
+
+ARG DEBIAN_FRONTEND
+ENV DEBIAN_FRONTEND=${DEBIAN_FRONTEND:-noninteractive}
+
+RUN set -ex && \
+	apt-get update && \
+	apt-get install -y --no-install-recommends \
+	# mpdpopm pre-requisistes \
+	rustc cargo locales \
+        # for my sanity \
+	less procps gdb sudo info vim && \
+        # tidy-up \
+	apt-get clean && \
+	rm -rf /tmp/* /var/tmp/* && \
+        # set the timezone to civilization (i.e. the Pacific) \
+	ln -fs /usr/share/zoneinfo/US/Pacific /etc/localtime && dpkg-reconfigure -f noninteractive tzdata && \
+	# Setup the en_US.UTF-8 locale \
+        cp -v /etc/locale.gen /etc/locale.gen.orig && \
+	sed 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen >> /tmp/locale.gen.$$ && \
+        mv -v /tmp/locale.gen.$$ /etc/locale.gen && \
+	locale-gen en_US.UTF-8 && \
+	update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 && \
+	# re-include the doc directories \
+	mkdir /usr/share/man/man1 && \
+	echo "path-include /usr/share/doc/scribbu" >> /etc/dpkg/dpkg.cfg.d/docker && \
+	echo "path-include /usr/share/man/man1/scribbu*" >> /etc/dpkg/dpkg.cfg.d/docker && \
+	echo "path-include /usr/share/info/scribbu.info" >> /etc/dpkg/dpkg.cfg.d/docker
+
+# The test suite won't work if this isn't set:
+ENV LANG="en_US.UTF-8"

admin/PKGBUILD.in

@@ -0,0 +1,25 @@
+pkgname=@PACKAGE_NAME@
+pkgver=@PACKAGE_VERSION@
+pkgrel=1
+pkgdesc='Maintain ratings & playcounts for your mpd server'
+url=https://github.com/sp1ff/mpdpopm
+arch=('x86_64')
+license=('GPL3')
+source=(mpdpopm-@[email protected])
+
+build() {
+  cd "${pkgname}-${pkgver}"
+  ./configure --prefix=/usr/local
+  make
+}
+
+check() {
+  cd "${pkgname}-${pkgver}"
+  make check
+}
+
+package() {
+  cd "${pkgname}-${pkgver}"
+  make DESTDIR="${pkgdir}/" install
+}
+

admin/build-dev-arch-pkg

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# This script will bindmount the host mpdpopm project directory and
+# invoke `cargo arch|aur' so as to make an Arch package.  It's meant
+# for use during mpdpopm development, as a check that my latest
+# changes won't break anything at release-time when it's time to
+# package the latest mpdpopm.
+
+# It is presumably run from the root mpdpopm directory.
+
+set -ex
+docker build -t mpdpopm-arch:latest -f admin/Dockerfile-arch .
+
+here=$(pwd)
+script=${here}/admin/build-dev-arch-pkg-cnt
+pkgbuild=${here}/PKGBUILD
+tarball=${here}/$1
+
+docker_args="-it"
+docker_args="$docker_args -v ${script}:/build-dev-pkg:ro"
+docker_args="$docker_args -v ${tarball}:/$1:ro"
+docker_args="$docker_args -v ${pkgbuild}:/PKGBUILD"
+docker_args="$docker_args --mount type=bind,source=${here},target=/mpdpopm"
+docker_args="$docker_args --privileged"
+docker_args="$docker_args --ulimit core=-1"
+docker_args="$docker_args -u mgh"
+# Un-comment to just drop into the container & experiment
+cmd="docker run ${docker_args} mpdpopm-arch:latest"
+# cmd="docker run ${docker_args} scribbu-arch:latest /build-dev-pkg $1"
+exec $cmd

admin/build-dev-arch-pkg-cnt

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -ex
+base="$(basename $1 .tar.gz)"
+version="${base:8}"
+cp -v /$1 /tmp
+cp -v /PKGBUILD /tmp
+cd /tmp
+makepkg -g >> PKGBUILD
+makepkg
+cp -v mpdpopm-${version}-1-x86_64.pkg.tar.zst /mpdpopm

configure.ac

@@ -1,4 +1,4 @@
-AC_INIT([mpdpopm], [0.1.14], [[email protected]], [mpdpopm], [https://github.com/sp1ff/mpdpopm])
+AC_INIT([mpdpopm], [0.1.15], [[email protected]], [mpdpopm], [https://github.com/sp1ff/mpdpopm])
 AC_CONFIG_AUX_DIR([build-aux])
 AC_CONFIG_SRCDIR([mpdpopm/Cargo.toml.in])
 AM_INIT_AUTOMAKE([-Wall -Werror -Wno-portability -Wno-override gnits std-options dist-bzip2 dist-xz])
@@ -20,7 +20,12 @@ dnl location at make-time.
 dnl
 dnl I handle this by having Autconf process vars.rs.am.in to vars.rs.am at configure time, and
 dnl adding a rule to Automake to build vars.rs from vars.rs.am at make-time.
+dnl
+dnl Ditto for etc/mppopmd.conf.am.in and etc/mppopmd.service.am.in
 AC_CONFIG_FILES([mpdpopm/src/vars.rs.am])
+AC_CONFIG_FILES([mpdpopm/mppopmd.conf.am:etc/mppopmd.conf.am.in])
+AC_CONFIG_FILES([mpdpopm/mppopmd.service.am:etc/mppopmd.service.am.in])
+AC_CONFIG_FILES([PKGBUILD:admin/PKGBUILD.in])
 AC_CONFIG_FILES([Makefile mpdpopm/Makefile mpdpopm/Cargo.toml])
 
 dnl Specify --enable-debug to make a development release.  By default,

etc/mppopmd.conf.am.in

@@ -0,0 +1,14 @@
+;; SAMPLE MPPOPMD CONFIGURATION FILE    -*- mode: lisp; -*-
+;; You will need to edit this to suit your particular installation.
+;; In particular, examine the `log' & `local_music_dir' values since those
+;; are difficult to guess. Also check the `host' & `port' settings.
+((log . "@datadir@/log/mppopmd.log")
+ (host . "localhost")
+ (port . 6600)
+ (local_music_dir . "@prefix@/Music")
+ (playcount_sticker . "unwoundstack.com:playcount")
+ (lastplayed_sticker . "unwoundstack.com:lastplayed")
+ (played_thresh . 0.6)
+ (poll_interval_ms . 5000)
+ (commands_chan . "unwoundstack.com:commands")
+ (rating_sticker . "unwoundstack.com:rating"))

etc/mppopmd.service.am.in

@@ -0,0 +1,13 @@
+# MPPOPMD SYSTEMD UNIT
+# You will likely need to edit this to suit your particular installation.
+[Unit]
+Description=mpdpopm ratings and playcounts for MPD
+Requires=mpd.service
+After=mpd.service
+
+[Service]
+Restart=on-failure
+ExecStart=@bindir@/mppopmd -F
+
+[Install]
+WantedBy=default.target

mpdpopm/.gitignore

@@ -5,3 +5,8 @@ Cargo.lock
 Cargo.toml
 rusty-tags.emacs
 README.md
+mppopmd.conf
+mppopmd.conf.am
+mppopmd.service
+mppopmd.service.am
+

mpdpopm/Cargo.toml.in

@@ -54,7 +54,7 @@ assets = [
        ["target/release/mppopm", "usr/local/bin/", "755"],
        ["target/release/mppopmd", "usr/local/bin/", "755"],
        ["README.md", "usr/local/share/doc/mpdpopm/README", "644"],
+       ["mppopmd.conf", "/usr/local/share/doc/mpdpopm/examples/mppopmd.conf", "644"],
+       ["mppopmd.service", "/usr/local/lib/systemd/user/mppopmd.service", "644"],
+       ["mppopmd.service", "/usr/local/lib/systemd/system/mppopmd.service", "644"],
 ]
-
-[package.metadata.arch]
-arch = ["x86_64"]

mpdpopm/Makefile.am

@@ -9,7 +9,7 @@ cargo_verbose_ = $(cargo_verbose_$(AM_DEFAULT_VERBOSITY))
 cargo_verbose_0 =
 cargo_verbose_1 = --verbose
 
-EXTRA_DIST = Cargo.lock
+EXTRA_DIST = Cargo.lock $(builddir)/mppopmd.conf $(builddir)/mppopmd.service
 bin_PROGRAMS = mppopmd mppopm
 
 # `vars.rs.am.in` contains Installation Directory Variables
@@ -24,7 +24,15 @@ bin_PROGRAMS = mppopmd mppopm
 $(builddir)/src/flapdoodle.rs: $(builddir)/src/vars.rs.am
 	sed -e "s|\$${prefix}|$(prefix)|g" $< > $@
 
-CLEANFILES = $(builddir)/src/flapdoodle.rs
+$(builddir)/mppopmd.conf: $(builddir)/mppopmd.conf.am
+	sed -e "s|\$${prefix}|$(prefix)|g" $< > $@
+
+$(builddir)/mppopmd.service: $(builddir)/mppopmd.service.am
+	sed -e "s|\$${prefix}|$(prefix)|g" $< > $@.$$$$ && \
+	sed -e "s|\$${exec_prefix}|$(prefix)|g" $@.$$$$ > $@  && \
+	rm $@.$$$$
+
+CLEANFILES = $(builddir)/src/flapdoodle.rs $(builddir)/mppopmd.conf $(builddir)/mppopmd.service
 
 DISTCLEANFILES = $(builddir)/Cargo.toml 
 
@@ -36,7 +44,7 @@ common_sources = clients.rs	\
 		 playcounts.rs	\
 		 ratings.rs
 
-mppopmd_SOURCES = $(srcdir)/Cargo.toml $(common_sources:%=src/%) src/bin/mppopmd.rs
+mppopmd_SOURCES = $(srcdir)/Cargo.toml $(common_sources:%=src/%) src/bin/mppopmd.rs $(builddir)/mppopmd.conf $(builddir)/mppopmd.service
 
 mppopm_SOURCES = $(srcdir)/Cargo.toml $(common_sources:%=src/%) src/bin/mppopm.rs
 
@@ -52,6 +60,7 @@ $(srcdir)/src/vars.rs: $(builddir)/src/flapdoodle.rs
 dist-hook:
 	cp -v Cargo.toml $(distdir)/mpdpopm
 	cp -v src/flapdoodle.rs $(distdir)/src/vars.rs
+	cp -v mppopmd.{conf,service} $(disdir)
 
 mppopmd$(EXEEXT): $(mppopmd_SOURCES) $(srcdir)/Cargo.toml $(srcdir)/src/vars.rs
 	cd $(top_srcdir)/mpdpopm && \
@@ -73,3 +82,15 @@ install-exec-local: mppopmd$(EXEEXT) mppopm$(EXEEXT)
 	install -d $(DESTDIR)$(bindir)
 	install -m 755 @abs_top_builddir@/mpdpopm/target/$(RUST_TARGET_SUBDIR)/mppopmd $(DESTDIR)$(bindir)/mppopmd
 	install -m 755 @abs_top_builddir@/mpdpopm/target/$(RUST_TARGET_SUBDIR)/mppopm $(DESTDIR)$(bindir)/mppopm
+	install -d $(DESTDIR)$(docdir)/examples
+	install -m 644 @abs_top_builddir@/mpdpopm/mppopmd.conf $(DESTDIR)$(docdir)/examples/mppopmd.conf
+	install -d $(DESTDIR)$(libdir)/systemd/system
+	install -m 644 @abs_top_builddir@/mpdpopm/mppopmd.service $(DESTDIR)$(libdir)/systemd/system/mppopmd.service
+	install -d $(DESTDIR)$(libdir)/systemd/user
+	install -m 644 @abs_top_builddir@/mpdpopm/mppopmd.service $(DESTDIR)$(libdir)/systemd/user/mppopmd.service
+
+uninstall-local:
+	rm -f $(DESTDIR)$(libdir)/systemd/user/mppopmd.service
+	rm -f $(DESTDIR)$(libdir)/systemd/system/mppopmd.service
+	rm -f $(DESTDIR)$(docdir)/examples/mppopmd.conf
+	rmdir $(DESTDIR)$(docdir)/examples