Make parts of generic packaging conditional

This should allow to rebuild old releases from before Debian packages,
Arch ppackages, manpages, or even the HTML manual were added

.gitignore

@@ -1,11 +1,13 @@
 # Temporary files
 
+/release/
 /documentation/
 /manual/
 /tests/coverage/
-/dist/arch/arsse
-/dist/arch/src
-/dist/arch/pkg
+/dist/arch/arsse/
+/dist/arch/src/
+/dist/arch/pkg/
+/dist/man/
 /arsse.db*
 /config.php
 /.php_cs.cache

CHANGELOG

@@ -1,3 +1,14 @@
+Version 0.10.0 (2021-07-11)
+===========================
+
+New features:
+- Complete Unix manual page
+- Support for running service as a forking daemon
+- Respond to TERM and HUP signals when possible
+
+Changes:
+- Packages for Debian and related are now available (see manual for details)
+
 Version 0.9.2 (2021-05-25)
 ==========================
 

README.md

@@ -8,7 +8,7 @@ Information on how to install and use the software can be found in [the manual](
 
 The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/mensbeam/arsse/). The GitHub mirror does not accept bug reports, but the two should otherwise be equivalent.
 
-[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install --no-dev` is recommended.
+[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install -o --no-dev --no-scripts` is recommended.
 
 # Repository structure
 
@@ -34,13 +34,15 @@ Also necessary to the functioning of the application is the `/vendor/` directory
 
 The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
 
-The `/dist/` directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
+The `/dist/` directory, on the other hand, contains general and system-specific build files, and samples of configuration for Web servers and other system integration. These are not used by The Arsse itself, but are used during the process of preparing new releases for supported operating systems.
 
 ## Documentation
 
 The source text for The Arsse's manual can be found in `/docs/`, with pages written in [Markdown](https://spec.commonmark.org/current/) and converted to HTML [with Daux](#building-the-manual). If a static manual is generated its files will appear under `/manual/`.
 
-In addition to the manual the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
+The Arsse also has a UNIX manual page, also written in Markdown, which can be found under `/manpages/`. [Pandoc](https://pandoc.org/) is needed to convert it to the appropriate format, with the results stored under `/dist/man/`.
+
+In addition to the manuals the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
 
 ## Tests
 
@@ -50,7 +52,7 @@ The `/tests/` directory contains everything related to automated testing. It is
 |--------------------|------------------------------------------------------------------------------------|
 | `cases/`           | The test cases themselves, organized in roughly the same structure as the code     |
 | `coverage/`        | (optional) Generated code coverage reports                                         |
-| `docroot/`         | Sample documents used in some tests, to be returned by the PHP's basic HTTP server |
+| `docroot/`         | Sample documents used in some tests, to be returned by PHP's basic HTTP server |
 | `lib/`             | Supporting classes which do not contain test cases                                 |
 | `bootstrap.php`    | Bootstrap script, equivalent to `/arsse.php`, but for tests                        |
 | `phpunit.dist.xml` | PHPUnit configuration file                                                         |
@@ -74,7 +76,7 @@ The `/vendor-bin/` directory houses the files needed for the tools used in The A
 | `/robo`           | Simple wrapper for executing Robo on POSIX systems       |
 | `/robo.bat`       | Simple wrapper for executing Robo on Windows             |
 
-In addition the files `/package.json`, `/yarn.lock`, and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
+In addition the files `/package.json` and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
 
 # Common tasks
 
@@ -105,15 +107,20 @@ The Arsse's user manual, made using [Daux](https://daux.io/), can be compiled by
 
 The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual.
 
+## Building the man page
+
+The Arsse's UNIX manual page is authored in Markdown, and must be converted to the native roff format using [Pandoc](https://pandoc.org/). This can be done by running `./robo manpage`, which will output appropriate files to `/dist/man/`. The conversion should not be done manually as there is post-processing required for optimal output.
+
 ## Packaging a release
 
-Producing a release package is done by running `./robo package`. This performs the following operations:
+Producing release packages is done by running `./robo package`. This performs the following operations:
 
-- Duplicates a working tree with the commit (usually a release tag) to package
-- Generates the manual
+- Duplicates a [Git](https://git-scm.com/) working tree with the commit (usually a release tag) to package
+- Generates UNIX manual pages with [Pandoc](https://pandoc.org/)
+- Generates the HTML manual
 - Installs runtime Composer dependencies with an optimized autoloader
 - Deletes numerous unneeded files
 - Exports the default configuration of The Arsse to a file
 - Compresses the remaining files into a tarball
-
-Due to the first step, [Git](https://git-scm.com/) is required to package a release.
+- Produces a binary package for Arch Linux, if possible
+- Produces source and binary packages for Debian using [pbuilder](https://pbuilder-team.pages.debian.net/pbuilder/), if possible

RoboFile.php

@@ -1,11 +1,13 @@
 <?php
 
+use Robo\Collection\CollectionBuilder;
 use Robo\Result;
 
 const BASE = __DIR__.\DIRECTORY_SEPARATOR;
 const BASE_TEST = BASE."tests".\DIRECTORY_SEPARATOR;
 define("IS_WIN", defined("PHP_WINDOWS_VERSION_MAJOR"));
 define("IS_MAC", php_uname("s") === "Darwin");
+define("IS_LINUX", !IS_WIN && !IS_MAC);
 error_reporting(0);
 
 function norm(string $path): string {
@@ -145,9 +147,34 @@ class RoboFile extends \Robo\Tasks {
         return $this->taskExec($executor)->option("-d", "zend.assertions=1")->arg($execpath)->option("-c", $confpath)->args(array_merge($set, $args))->run();
     }
 
+    protected function commitVersion(?string $commit): array {
+        $target = $commit ?? $this->askDefault("Reference commit:", "HEAD");
+        $base = escapeshellarg(BASE);
+        $blackhole = $this->blackhole();
+        // get useable version strings from Git
+        $version = trim(`git -C $base describe --tags $target $blackhole`);
+        if (!$version) {
+            throw new \Exception("Commit reference invalid");
+        }
+        return [$target, $version];
+    }
+
+    protected function toolExists(string ...$binary): bool {
+        $blackhole = $this->blackhole(IS_WIN);
+        foreach ($binary as $bin) {
+            if (
+                (IS_WIN && (!exec(escapeshellarg($bin)." --help $blackhole", $junk, $status) || $status))
+                || (!IS_WIN && (!exec("which ".escapeshellarg($bin)." $blackhole", $junk, $status) || $status))
+             ) {
+                    return false;
+            }
+        }
+        return true;
+    }
+
     /** Packages a given commit of the software into a release tarball
      *
-     * The version to package may be any Git tree-ish identifier: a tag, a branch,
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
      * or any commit hash. If none is provided on the command line, Robo will prompt
      * for a commit to package; the default is "HEAD".
      *
@@ -155,38 +182,49 @@ class RoboFile extends \Robo\Tasks {
      * may not be equivalent due to subsequent changes in the exclude list, or because
      * of new tooling.
      */
-    public function package(string $version = null): Result {
+    public function packageGeneric(string $commit = null): Result {
+        if (!$this->toolExists("git", "pandoc")) {
+            throw new \Exception("Git and Pandoc are required in PATH to produce generic release tarballs");
+        }
         // establish which commit to package
-        $commit = $version ?? $this->askDefault("Commit to package:", "HEAD");
+        [$commit, $version] = $this->commitVersion($commit);
+        $archVersion = preg_replace('/^([^-]+)-(\d+)-(\w+)$/', "$1.r$2.$3", $version);
+        // name the generic release tarball
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
         // start a collection
         $t = $this->collectionBuilder();
         // create a temporary directory
         $dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
         // create a Git worktree for the selected commit in the temp location
-        $result = $this->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($commit))->dir(BASE)->run();
+        $result = $this->taskExec("git worktree add ".escapeshellarg($dir)." ".escapeshellarg($version))->dir(BASE)->run();
         if ($result->getExitCode() > 0) {
             return $result;
         }
         try {
-            // get useable version strings from Git
-            $version = trim(`git -C "$dir" describe --tags`);
-            $archVersion = preg_replace('/^([^-]+)-(\d+)-(\w+)$/', "$1.r$2.$3", $version);
-            // name the generic release tarball
-            $tarball = "arsse-$version.tar.gz";
-            // generate the Debian changelog; this also validates our original changelog
-            $debianChangelog = $this->changelogDebian($this->changelogParse(file_get_contents($dir."CHANGELOG"), $version), $version);
-            // save commit description to VERSION file for use by packaging
+            if (file_exists($dir."dist/debian")) {
+                // generate the Debian changelog; this also validates our original changelog
+                $debianChangelog = $this->changelogDebian($this->changelogParse(file_get_contents($dir."CHANGELOG"), $version), $version);
+                // save the Debian-format changelog
+                $t->addTask($this->taskWriteToFile($dir."dist/debian/changelog")->text($debianChangelog));
+            }
+            if (file_exists($dir."dist/arch")) {
+                // patch the Arch PKGBUILD file with the correct version string
+                $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^pkgver=.*$/m')->to("pkgver=$archVersion"));
+                // patch the Arch PKGBUILD file with the correct source file
+                $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^source=\("arsse-[^"]+"\)$/m')->to('source=("'.basename($tarball).'")'));
+            }
+            // save commit description to VERSION file for reference
             $t->addTask($this->taskWriteToFile($dir."VERSION")->text($version));
-            // save the Debian changelog
-            $t->addTask($this->taskWriteToFile($dir."dist/debian/changelog")->text($debianChangelog));
-            // patch the Arch PKGBUILD file with the correct version string
-            $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^pkgver=.*$/m')->to("pkgver=$archVersion"));
-            // patch the Arch PKGBUILD file with the correct source file
-            $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^source=\("arsse-[^"]+"\)$/m')->to('source=("'.basename($tarball).'")'));
             // perform Composer installation in the temp location with dev dependencies
             $t->addTask($this->taskComposerInstall()->arg("-q")->dir($dir));
-            // generate the manual
-            $t->addTask($this->taskExec("./robo manual -q")->dir($dir));
+            if (file_exists($dir."manpages")) {
+                // generate manpages
+                $t->addTask($this->taskExec("./robo manpage")->dir($dir));
+            }
+            if (file_exists($dir."docs")) {
+                // generate the HTML manual
+                $t->addTask($this->taskExec("./robo manual -q")->dir($dir));
+            }
             // perform Composer installation in the temp location for final output
             $t->addTask($this->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts")->arg("-q"));
             // delete unwanted files
@@ -194,6 +232,7 @@ class RoboFile extends \Robo\Tasks {
                 $dir.".git",
                 $dir.".gitignore",
                 $dir.".gitattributes",
+                $dir."dist/debian/.gitignore",
                 $dir."composer.json",
                 $dir."composer.lock",
                 $dir.".php_cs.dist",
@@ -202,6 +241,7 @@ class RoboFile extends \Robo\Tasks {
                 $dir."RoboFile.php",
                 $dir."CONTRIBUTING.md",
                 $dir."docs",
+                $dir."manpages",
                 $dir."tests",
                 $dir."vendor-bin",
                 $dir."vendor/bin",
@@ -211,11 +251,22 @@ class RoboFile extends \Robo\Tasks {
                 $dir."yarn.lock",
                 $dir."postcss.config.js",
             ]));
+            $t->addCode(function() use ($dir) {
+                // Remove files which lintian complains about; they're otherwise harmless
+                $files = [];
+                foreach (new \CallbackFilterIterator(new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($dir."vendor", \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS)), function($v, $k, $i) {
+                    return preg_match('/\/\.git(?:ignore|attributes|modules)$/D', $v);
+                }) as $f) {
+                    $files[] = $f;
+                }
+                return $this->taskFilesystemStack()->remove($files)->run();
+            });
             // generate a sample configuration file
             $t->addTask($this->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir));
             // remove any existing archive
             $t->addTask($this->taskFilesystemStack()->remove($tarball));
             // package it all up
+            $t->addTask($this->taskFilesystemStack()->mkdir(dirname($tarball)));
             $t->addTask($this->taskPack($tarball)->addDir("arsse", $dir));
             // execute the collection
             $result = $t->run();
@@ -227,11 +278,28 @@ class RoboFile extends \Robo\Tasks {
         return $result;
     }
 
-    /** Packages a release tarball into an Arch package  */
-    public function packageArch(string $tarball): Result {
+    /** Packages a given commit of the software into an Arch package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     * 
+     * The Arch base-devel group should be installed for this.
+     */
+    public function packageArch(string $commit = null): Result {
+        if (!$this->toolExists("git", "makepkg", "updpkgsums")) {
+            throw new \Exception("Git, makepkg, and updpkgsums are required in PATH to produce Arch packages");
+        }
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
         $dir = dirname($tarball).\DIRECTORY_SEPARATOR;
         // start a collection
         $t = $this->collectionBuilder();
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        }
         // extract the PKGBUILD from the tarball
         $t->addCode(function() use ($tarball, $dir) {
             // because Robo doesn't support extracting a single file we have to do it ourselves
@@ -244,17 +312,66 @@ class RoboFile extends \Robo\Tasks {
         return $t->run();
     }
 
-    /** Packages a release tarball into a Debian package */
-    public function packageDeb(string $tarball): Result {
-        // determine the "upstream" (tagged) version
-        if (preg_match('/^arsse-(\d+(?:\.\d+)*)/', basename($tarball), $m)) {
-            $version = $m[1];
-        } else {
-            throw new \Exception("Tarball is not named correctly");
+    /** Packages a given commit of the software a binary Debian package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     * 
+     * The pbuilder tool should be installed for this.
+     */
+    public function packageDeb(string $commit = null): Result {
+        if (!$this->toolExists("git", "sudo", "pbuilder")) {
+            throw new \Exception("Git, sudo, and pbuilder are required in PATH to produce Debian packages");
+        }
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
+        // define some more variables
+        $tgz = BASE."release/pbuilder-arsse.tgz";
+        $bind = dirname($tarball);
+        $script = BASE."dist/debian/pbuilder.sh";
+        $user = trim(`id -un`);
+        $group = trim(`id -gn`);
+        // start a task collection
+        $t = $this->collectionBuilder();
+        // check that the pbuilder base exists and create it if it does not
+        if (!file_exists($tgz)) {
+            $t->addTask($this->taskFilesystemStack()->mkdir(BASE."release"));
+            $t->addTask($this->taskExec('sudo pbuilder create --basetgz '.escapeshellarg($tgz).' --mirror http://ftp.ca.debian.org/debian/ --extrapackages "debhelper devscripts lintian"'));
+        }
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
         }
+        // build the packages
+        $t->addTask($this->taskExec('sudo pbuilder execute --basetgz '.escapeshellarg($tgz).' --bindmounts '.escapeshellarg($bind).' -- '.escapeshellarg($script).' '.escapeshellarg("$bind/".basename($tarball))));
+        // take ownership of the output files
+        $t->addTask($this->taskExec("sudo chown -R $user:$group ".escapeshellarg($bind)));
+        return $t->run();
+    }
+
+    /** Packages a release tarball into a Debian source package
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     */
+    public function packageDebsrc(string $commit = null): Result {
+        // establish which commit to package
+        [$commit, $version] = $this->commitVersion($commit);
+        $tarball = BASE."release/$version/arsse-$version.tar.gz";
+        // determine the base version (i.e. x.y.z) and the Debian version (i.e. x.y.z-a)
+        preg_match('/^(\d+(?:\.\d+)+)(?:-(\d+))?/', $version, $m);
+        $baseVersion = $m[1];
+        $debVersion = $m[1]."-".($version === $baseVersion ? "1" : $m[2]);
         // start a task collection and create a temporary directory
         $t = $this->collectionBuilder();
         $dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
+        // build the generic release tarball if it doesn't exist
+        if (!file_exists($tarball)) {
+            $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        }
         $base = $dir."arsse-$version".\DIRECTORY_SEPARATOR;
         // start by extracting the tarball
         $t->addCode(function() use ($tarball, $dir, $base) {
@@ -262,14 +379,66 @@ class RoboFile extends \Robo\Tasks {
             (new \Archive_Tar($tarball))->extract($dir, false);
             return $this->taskFilesystemStack()->rename($dir."arsse", $base)->run();
         });
-        // re-pack the tarball using specific names special to debuild
-        $t->addTask($this->taskPack($dir."arsse_$version.orig.tar.gz")->addDir("arsse-$version", $base));
-        // copy Debian files to lower down in the tree
-        $t->addTask($this->taskFilesystemStack()->mirror($base."dist/debian", $base."debian"));
-        $t->addTask($this->taskExec("deber")->dir($dir));
+        // re-pack the tarball using a specific name special to Debian
+        $t->addTask($this->taskPack($dir."arsse_$baseVersion.orig.tar.gz")->addDir("arsse-$baseVersion", $base));
+        // pack the debian tarball
+        $t->addTask($this->taskPack($dir."arsse_$debVersion.debian.tar.gz")->addDir("debian", $base."dist"));
+        // generate the DSC file
+        $t->addCode(function() use ($t, $debVersion, $baseVersion, $dir, $base) {
+            try {
+                $dsc = $this->generateDebianSourceControl($base."dist/debian/", $debVersion, [$dir."arsse_$baseVersion.orig.tar.gz", $dir."arsse_$debVersion.debian.tar.gz"]);
+            } catch (\Exception $e) {
+                return new Result($t, 1, $e->getMessage());
+            }
+            // write the DSC file
+            return $this->taskWriteToFile($dir."arsse_$debVersion.dsc")->text($dsc)->run();
+        });
+        // delete any existing files
+        $t->AddTask($this->taskFilesystemStack()->remove(BASE."release/$version/arsse_$baseVersion.orig.tar.gz")->remove(BASE."release/$version/arsse_$debVersion.debian.tar.gz")->remove(BASE."release/$version/arsse_$debVersion.dsc"));
+        $t->addTask($this->taskFilesystemStack()->copy($dir."arsse_$baseVersion.orig.tar.gz", BASE."release/$version/arsse_$baseVersion.orig.tar.gz")->copy($dir."arsse_$debVersion.debian.tar.gz", BASE."release/$version/arsse_$debVersion.debian.tar.gz")->copy($dir."arsse_$debVersion.dsc", BASE."release/$version/arsse_$debVersion.dsc"));
         return $t->run();
     }
 
+    /** Generates all possible package types for a given commit of the software
+     *
+     * The commit to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "HEAD".
+     * 
+     * Generic release tarballs will always be generated, but distribution-specific
+     * packages are skipped when the required tools are not available
+     */
+    public function package(string $commit = null): Result {
+        if (!$this->toolExists("git")) {
+            throw new \Exception("Git is required in PATH to produce packages");
+        }
+        [$commit,] = $this->commitVersion($commit);
+        // determine whether the distribution-specific packages can be built
+        $dist = [
+            'Arch'   => $this->toolExists("git", "makepkg", "updpkgsums"),
+            'Deb' => $this->toolExists("git", "sudo", "pbuilder"),
+        ];
+        // start a collection
+        $t = $this->collectionBuilder();
+        // build the generic release tarball
+        $t->addTask($this->taskExec(BASE."robo package:generic $commit"));
+        // build other packages
+        foreach ($dist as $distro => $run) {
+            if ($run) {
+                $subcmd = strtolower($distro);
+                $t->addTask($this->taskExec(BASE."robo package:$subcmd $commit"));
+            }
+        }
+        $out = $t->run();
+        // note any packages which were not built
+        foreach ($dist as $distro => $run) {
+            if (!$run) {
+                $this->say("Packages for $distro skipped");
+            }
+        }
+        return $out;
+    }
+
     /** Generates static manual pages in the "manual" directory
      *
      * The resultant files are suitable for offline viewing and inclusion into release builds
@@ -296,6 +465,9 @@ class RoboFile extends \Robo\Tasks {
      * Daux's theme changes
      */
     public function manualTheme(array $args): Result {
+        if (!$this->toolExists("yarn")) {
+            throw new \Exception("Yarn is required in PATH to update the Daux theme");
+        }
         $postcss = escapeshellarg(norm(BASE."node_modules/.bin/postcss"));
         $themesrc = norm(BASE."docs/theme/src/").\DIRECTORY_SEPARATOR;
         $themeout = norm(BASE."docs/theme/arsse/").\DIRECTORY_SEPARATOR;
@@ -314,6 +486,29 @@ class RoboFile extends \Robo\Tasks {
         return $t->run();
     }
 
+    /** Generates the "arsse" command's manual page (UNIX man page)
+     *
+     * This requires that the Pandoc document converter be installed and
+     * available in $PATH.
+     */
+    public function manpage(): Result {
+        if (!$this->toolExists("pandoc")) {
+            throw new \Exception("Pandoc is required in PATH to generate manual pages");
+        }
+        $t = $this->collectionBuilder();
+        $man = [
+            'en' => "man1/arsse.1",
+        ];
+        foreach ($man as $src => $out) {
+            $src = BASE."manpages/$src.md";
+            $out = BASE."dist/man/$out";
+            $t->addTask($this->taskFilesystemStack()->mkdir(dirname($out), 0755));
+            $t->addTask($this->taskExec("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src)));
+            $t->addTask($this->taskReplaceInFile($out)->regex('/\.\n(?!\.)/s')->to(". "));
+        }
+        return $t->run();
+    }
+
     protected function changelogParse(string $text, string $targetVersion): array {
         $lines = preg_split('/\r?\n/', $text);
         $version = "";
@@ -323,9 +518,9 @@ class RoboFile extends \Robo\Tasks {
         $expected = ["version"];
         for ($a = 0; $a < sizeof($lines);) {
             $l = rtrim($lines[$a++]);
-            if (in_array("version", $expected) && preg_match('/^Version (\d+(?:\.\d+)*) \(([\d\?]{4}-[\d\?]{2}-[\d\?]{2})\)\s*$/', $l, $m)) {
+            if (in_array("version", $expected) && preg_match('/^Version (\d+(?:\.\d+)*) \(([\d\?]{4}-[\d\?]{2}-[\d\?]{2})\)\s*$/D', $l, $m)) {
                 $version = $m[1];
-                if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $m[2])) {
+                if (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $m[2])) {
                     // uncertain dates are allowed only for the top version, and only if it does not match the target version (otherwise we have forgotten to set the correct date before tagging)
                     if (!$out && $targetVersion !== $version) {
                         // use today's date; local time is fine
@@ -338,7 +533,7 @@ class RoboFile extends \Robo\Tasks {
                 }
                 if ($entry) {
                     $out[] = $entry;
-                } 
+                }
                 $entry = ['version' => $version, 'date' => $date, 'features' => [], 'fixes' => [], 'changes' => []];
                 $expected = ["separator"];
             } elseif (in_array("separator", $expected) && preg_match('/^=+/', $l)) {
@@ -365,10 +560,10 @@ class RoboFile extends \Robo\Tasks {
             } elseif (in_array("changes section", $expected) && $l === "Changes:") {
                 $section = "changes";
                 $expected = ["item"];
-            } elseif (in_array("item", $expected) && preg_match('/^- (\w.*)$/', $l, $m)) {
+            } elseif (in_array("item", $expected) && preg_match('/^- (\w.*)$/D', $l, $m)) {
                 $entry[$section][] = $m[1];
                 $expected = ["item", "continuation", "blank line"];
-            } elseif (in_array("continuation", $expected) && preg_match('/^  (\w.*)$/', $l, $m)) {
+            } elseif (in_array("continuation", $expected) && preg_match('/^  (\w.*)$/D', $l, $m)) {
                 $last = sizeof($entry[$section]) - 1;
                 $entry[$section][$last] .= "\n".$m[1];
             } else {
@@ -389,24 +584,25 @@ class RoboFile extends \Robo\Tasks {
         $out[] = $entry;
         return $out;
     }
-    
+
     protected function changelogDebian(array $log, string $targetVersion): string {
         $latest = $log[0]['version'];
         $baseVersion = preg_replace('/^(\d+(?:\.\d+)*).*/', "$1", $targetVersion);
         if ($baseVersion !== $targetVersion && version_compare($latest, $baseVersion, ">")) {
             // if the changelog contains an entry for a future version, change its version number to match the target version instead of using the future version
             $log[0]['version'] = $targetVersion;
-        } else {
+            $log[0]['distribution'] = "UNRELEASED";
+        } elseif ($baseVersion !== $targetVersion) {
             // otherwise synthesize a changelog entry for the changes since the last tag
-            array_unshift($log, ['version' => $targetVersion, 'date' => date("Y-m-d"), 'features' => [], 'fixes' => [], 'changes' => ["Unspecified changes"]]);
+            array_unshift($log, ['version' => $targetVersion, 'date' => date("Y-m-d"), 'features' => [], 'fixes' => [], 'changes' => ["Unspecified changes"], 'distribution' => "UNRELEASED"]);
         }
         $out = "";
         foreach ($log as $entry) {
             // normalize the version string
-            preg_match('/^(\d+(?:\.\d+)*)(?:-(\d+)-.+)?$/', $entry['version'], $m);
+            preg_match('/^(\d+(?:\.\d+)*)(?:-(\d+)-.+)?$/D', $entry['version'], $m);
             $version = $m[1]."-".($m[2] ?: "1");
             // output the entry
-            $out .= "arsse ($version) UNRELEASED; urgency=low\n";
+            $out .= "arsse ($version) ".($entry['distribution'] ?? "unstable")."; urgency=low\n";
             if ($entry['features']) {
                 $out .= "\n";
                 foreach ($entry['features'] as $item) {
@@ -425,8 +621,134 @@ class RoboFile extends \Robo\Tasks {
                     $out .= "  * ".trim(preg_replace("/^/m", "    ", $item))."\n";
                 }
             }
-            $out .= "\n -- The Arsse team <no-contact@code.mensbeam.com>  ".\DateTimeImmutable::createFromFormat("Y-m-d", $entry['date'], new \DateTimeZone("UTC"))->format("D, d M Y")." 00:00:00 +0000\n\n";
+            $out .= "\n -- J. King <jking@jkingweb.ca>  ".\DateTimeImmutable::createFromFormat("Y-m-d", $entry['date'], new \DateTimeZone("UTC"))->format("D, d M Y")." 00:00:00 +0000\n\n";
         }
         return $out;
     }
+
+    protected function generateDebianSourceControl(string $dir, string $version, array $tarballs): string {
+        // read in control file
+        if (!$control = @file_get_contents($dir."control")) {
+            throw new \Exception("Unable to read Debian control file");
+        }
+        // read the format
+        if (!$format = @file_get_contents($dir."source/format")) {
+            throw new \Exception("Unable to read source format in Debian files");
+        }
+        // read the binary packages from the control file
+        if (preg_match_all('/^Package:\s*(\S+)/m', $control, $m)) {
+            $binary = [];
+            foreach ($m[1] as $pkg) {
+                $binary[] = $pkg;
+            }
+        } else {
+            throw new \Exception("No packages defined in Debian control file");
+        }
+        // read the package architectures from the control file
+        if (preg_match_all('/^Architecture:\s*(\S+)/m', $control, $m) || sizeof($m[1]) != sizeof($binary)) {
+            $architecture = [];
+            foreach ($m[1] as $pkg) {
+                $architecture[] = preg_replace('/\s/', "", $pkg);
+            }
+        } else {
+            throw new \Exception("Number of architectures defined in Debian control file does not match number of packages");
+        }
+        // read the package sections from the control file
+        if (preg_match_all('/^Section:\s*(\S+)/m', $control, $m) || sizeof($m[1]) != sizeof($binary)) {
+            $section = [];
+            foreach ($m[1] as $pkg) {
+                $section[] = $pkg;
+            }
+        } else {
+            throw new \Exception("Number of sections defined in Debian control file does not match number of packages");
+        }
+        // read the package priorities from the control file
+        if (preg_match_all('/^Priority:\s*(\S+)/m', $control, $m) || sizeof($m[1]) != sizeof($binary)) {
+            $priority = [];
+            foreach ($m[1] as $pkg) {
+                $priority[] = $pkg;
+            }
+        } else {
+            throw new \Exception("Number of priorities defined in Debian control file does not match number of packages");
+        }
+        // read simple metadata from the control file
+        $metadata = [];
+        foreach (["Source", "Maintainer", "Homepage", "Standards-Version", "Vcs-Browser", "Vcs-Git"] as $meta) {
+            if (preg_match('/^'.$meta.':\s*(.+)/m', $control, $m)) {
+                $metadata[$meta] = $m[1];
+            } else {
+                throw new \Exception("$meta is not defined in Debian control file");
+            }
+        }
+        // read build dependencies from control file
+        if (preg_match('/(?:^|\n)Build-Depends:\s*((?:[^\n]|\n(?= ))+)/s', $control, $m)) {
+            $buildDepends = preg_replace('/\s/', "", $m[1]);
+        } else {
+            $buildDepends = "";
+        }
+        // trim format
+        $format = trim($format);
+        // consolidate binaries and package list
+        $packageList = [];
+        for ($a = 0; $a < sizeof($binary); $a++) {
+            $packageList[] = "$binary[$a] deb $section[$a] $priority[$a] arch=$architecture[$a]";
+        }
+        $packageList = implode("\n ", $packageList);
+        // consolidate package names
+        $binary = implode(",", $binary);
+        // consolidate architectures
+        $architecture = implode(",", array_unique($architecture));
+        // calculate checksums for files
+        $fMeta = [];
+        foreach ($tarballs as $f) {
+            $fMeta[$f] = [
+                'name'   => basename($f),
+                'size'   => filesize($f),
+                'sha1'   => hash_file("sha1", $f),
+                'sha256' => hash_file("sha256", $f),
+                'md5'    => hash_file("md5", $f),
+            ];
+        }
+        // consolidate SHA-1 checksums
+        $sums = [];
+        foreach ($fMeta as $data) {
+            $sums[] = $data['sha1']." ".$data['size']." ".$data['name'];
+        }
+        $sumsSha1 = implode("\n ", $sums);
+        // consolidate SHA-256 checksums
+        $sums = [];
+        foreach ($fMeta as $data) {
+            $sums[] = $data['sha256']." ".$data['size']." ".$data['name'];
+        }
+        $sumsSha256 = implode("\n ", $sums);
+        // consolidate MD5 checksums
+        $sums = [];
+        foreach ($fMeta as $data) {
+            $sums[] = $data['md5']." ".$data['size']." ".$data['name'];
+        }
+        $sumsMd5 = implode("\n ", $sums);
+        // return complete file
+        return <<< DSC_FILE
+Format: $format
+Source: {$metadata['Source']}
+Binary: $binary
+Architecture: $architecture
+Version: $version
+Maintainer: {$metadata['Maintainer']}
+Homepage: {$metadata['Homepage']}
+Standards-Version: {$metadata['Standards-Version']}
+Vcs-Browser: {$metadata['Vcs-Browser']}
+Vcs-Git: {$metadata['Vcs-Git']}
+Build-Depends: $buildDepends
+Package-List:
+ $packageList
+Checksums-Sha1:
+ $sumsSha1
+Checksums-Sha256:
+ $sumsSha256
+Files:
+ $sumsMd5
+
+DSC_FILE;
+    }
 }

arsse.php

@@ -25,8 +25,7 @@ if (\PHP_SAPI === "cli") {
     exit($exitStatus);
 } else {
     // load configuration
-    $conf = file_exists(BASE."config.php") ? new Conf(BASE."config.php") : new Conf;
-    Arsse::load($conf);
+    Arsse::bootstrap();
     // handle Web requests
     $emitter = new \Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
     $response = (new REST)->dispatch();

composer.json

@@ -22,6 +22,7 @@
         "ext-intl": "*",
         "ext-json": "*",
         "ext-hash": "*",
+        "ext-filter": "*",
         "ext-dom": "*",
         "nicolus/picofeed": "^0.1.43",
         "hosteurope/password-generator": "1.*",
@@ -33,6 +34,9 @@
     "require-dev": {
         "bamarni/composer-bin-plugin": "*"
     },
+    "suggest": {
+        "ext-pcntl": "To respond to signals, particular to reload configuration via SIGHUP"
+    },
     "config": {
         "platform": {
             "php": "7.1.33"

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "2a87797422ae569bafcbb6476461ac38",
+    "content-hash": "c658930fbc56b2b2cf646e34c6a8d8d3",
     "packages": [
         {
             "name": "docopt/docopt",
@@ -1045,16 +1045,16 @@
         },
         {
             "name": "symfony/polyfill-intl-idn",
-            "version": "v1.22.1",
+            "version": "v1.23.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-intl-idn.git",
-                "reference": "2d63434d922daf7da8dd863e7907e67ee3031483"
+                "reference": "65bd267525e82759e7d8c4e8ceea44f398838e65"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/polyfill-intl-idn/zipball/2d63434d922daf7da8dd863e7907e67ee3031483",
-                "reference": "2d63434d922daf7da8dd863e7907e67ee3031483",
+                "url": "https://api.github.com/repos/symfony/polyfill-intl-idn/zipball/65bd267525e82759e7d8c4e8ceea44f398838e65",
+                "reference": "65bd267525e82759e7d8c4e8ceea44f398838e65",
                 "shasum": ""
             },
             "require": {
@@ -1068,7 +1068,7 @@
             "type": "library",
             "extra": {
                 "branch-alias": {
-                    "dev-main": "1.22-dev"
+                    "dev-main": "1.23-dev"
                 },
                 "thanks": {
                     "name": "symfony/polyfill",
@@ -1112,7 +1112,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-intl-idn/tree/v1.22.1"
+                "source": "https://github.com/symfony/polyfill-intl-idn/tree/v1.23.0"
             },
             "funding": [
                 {
@@ -1128,20 +1128,20 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2021-01-22T09:19:47+00:00"
+            "time": "2021-05-27T09:27:20+00:00"
         },
         {
             "name": "symfony/polyfill-intl-normalizer",
-            "version": "v1.22.1",
+            "version": "v1.23.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-intl-normalizer.git",
-                "reference": "43a0283138253ed1d48d352ab6d0bdb3f809f248"
+                "reference": "8590a5f561694770bdcd3f9b5c69dde6945028e8"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/polyfill-intl-normalizer/zipball/43a0283138253ed1d48d352ab6d0bdb3f809f248",
-                "reference": "43a0283138253ed1d48d352ab6d0bdb3f809f248",
+                "url": "https://api.github.com/repos/symfony/polyfill-intl-normalizer/zipball/8590a5f561694770bdcd3f9b5c69dde6945028e8",
+                "reference": "8590a5f561694770bdcd3f9b5c69dde6945028e8",
                 "shasum": ""
             },
             "require": {
@@ -1153,7 +1153,7 @@
             "type": "library",
             "extra": {
                 "branch-alias": {
-                    "dev-main": "1.22-dev"
+                    "dev-main": "1.23-dev"
                 },
                 "thanks": {
                     "name": "symfony/polyfill",
@@ -1196,7 +1196,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.22.1"
+                "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.23.0"
             },
             "funding": [
                 {
@@ -1212,20 +1212,20 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2021-01-22T09:19:47+00:00"
+            "time": "2021-02-19T12:13:01+00:00"
         },
         {
             "name": "symfony/polyfill-php72",
-            "version": "v1.22.1",
+            "version": "v1.23.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-php72.git",
-                "reference": "cc6e6f9b39fe8075b3dabfbaf5b5f645ae1340c9"
+                "reference": "9a142215a36a3888e30d0a9eeea9766764e96976"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/polyfill-php72/zipball/cc6e6f9b39fe8075b3dabfbaf5b5f645ae1340c9",
-                "reference": "cc6e6f9b39fe8075b3dabfbaf5b5f645ae1340c9",
+                "url": "https://api.github.com/repos/symfony/polyfill-php72/zipball/9a142215a36a3888e30d0a9eeea9766764e96976",
+                "reference": "9a142215a36a3888e30d0a9eeea9766764e96976",
                 "shasum": ""
             },
             "require": {
@@ -1234,7 +1234,7 @@
             "type": "library",
             "extra": {
                 "branch-alias": {
-                    "dev-main": "1.22-dev"
+                    "dev-main": "1.23-dev"
                 },
                 "thanks": {
                     "name": "symfony/polyfill",
@@ -1272,7 +1272,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-php72/tree/v1.22.1"
+                "source": "https://github.com/symfony/polyfill-php72/tree/v1.23.0"
             },
             "funding": [
                 {
@@ -1288,7 +1288,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2021-01-07T16:49:33+00:00"
+            "time": "2021-05-27T09:17:38+00:00"
         }
     ],
     "packages-dev": [
@@ -1353,11 +1353,12 @@
         "ext-intl": "*",
         "ext-json": "*",
         "ext-hash": "*",
+        "ext-filter": "*",
         "ext-dom": "*"
     },
     "platform-dev": [],
     "platform-overrides": {
         "php": "7.1.33"
     },
-    "plugin-api-version": "1.1.0"
+    "plugin-api-version": "2.1.0"
 }

dist/arch/PKGBUILD

@@ -32,8 +32,8 @@ package() {
     depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1" "php-fpm>=7.1")
     # create most directories necessary for the final package
     cd "$pkgdir"
-    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx"
-    #copy requisite files
+    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d" "etc/webapps/arsse"
+    # copy requisite files
     cd "$srcdir/arsse"
     cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
     cp -r manual/* "$pkgdir/usr/share/doc/arsse"
@@ -42,12 +42,13 @@ package() {
     cp dist/sysuser.conf "$pkgdir/usr/lib/sysusers.d/arsse.conf"
     cp dist/tmpfiles.conf "$pkgdir/usr/lib/tmpfiles.d/arsse.conf"
     cp dist/php-fpm.conf "$pkgdir/etc/php/php-fpm.d/arsse.conf"
+    cp -r dist/man "$pkgdir/usr/share"
     cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
     cd "$pkgdir"
     # copy files requiring special permissions
     cd "$srcdir/arsse"
     install -Dm755 dist/arsse "$pkgdir/usr/bin/arsse"
-    install -Dm640 dist/arch/config.php "$pkgdir/etc/webapps/arsse"
+    install -Dm640 dist/config.php "$pkgdir/etc/webapps/arsse"
     # patch generic configuration files to use Arch-specific paths and identifiers
     sed -i -se 's/\/\(etc\|usr\/share\)\/arsse\//\/\1\/webapps\/arsse\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/usr/lib/tmpfiles.d/arsse.conf" "$pkgdir/usr/lib/systemd/system/"* "$pkgdir/usr/bin/"*
     sed -i -se 's/\/var\/run\/php\//\/run\/php-fpm\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/etc/php/php-fpm.d/arsse.conf"

dist/arch/PKGBUILD-git

@@ -10,7 +10,7 @@ license=("MIT")
 provides=("arsse")
 conflicts=("arsse")
 depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1")
-makedepends=("composer")
+makedepends=("composer" "pandoc")
 checkdepends=()
 optdepends=("nginx: HTTP server"
             "apache>=2.4: HTTP server"
@@ -37,6 +37,7 @@ pkgver() {
 build() {
     cd "$srcdir/arsse"
     composer install
+    ./robo manpage
     ./robo manual
     composer install --no-dev -o --no-scripts
     php arsse.php conf save-defaults config.defaults.php
@@ -48,8 +49,8 @@ package() {
     depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1" "php-fpm>=7.1")
     # create most directories necessary for the final package
     cd "$pkgdir"
-    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx"
-    #copy requisite files
+    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d" "etc/webapps/arsse"
+    # copy requisite files
     cd "$srcdir/arsse"
     cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
     cp -r manual/* "$pkgdir/usr/share/doc/arsse"
@@ -58,12 +59,13 @@ package() {
     cp dist/sysuser.conf "$pkgdir/usr/lib/sysusers.d/arsse.conf"
     cp dist/tmpfiles.conf "$pkgdir/usr/lib/tmpfiles.d/arsse.conf"
     cp dist/php-fpm.conf "$pkgdir/etc/php/php-fpm.d/arsse.conf"
+    cp -r dist/man "$pkgdir/usr/share"
     cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
     cd "$pkgdir"
     # copy files requiring special permissions
     cd "$srcdir/arsse"
     install -Dm755 dist/arsse "$pkgdir/usr/bin/arsse"
-    install -Dm640 dist/arch/config.php "$pkgdir/etc/webapps/arsse"
+    install -Dm640 dist/config.php "$pkgdir/etc/webapps/arsse"
     # patch generic configuration files to use Arch-specific paths and identifiers
     sed -i -se 's/\/\(etc\|usr\/share\)\/arsse\//\/\1\/webapps\/arsse\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/usr/lib/tmpfiles.d/arsse.conf" "$pkgdir/usr/lib/systemd/system/"* "$pkgdir/usr/bin/"*
     sed -i -se 's/\/var\/run\/php\//\/run\/php-fpm\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/etc/php/php-fpm.d/arsse.conf"

dist/arsse

@@ -1,4 +1,4 @@
-#! /usr/bin/php
+#! /usr/bin/env php
 <?php
 if (posix_geteuid() == 0) {
     $info = posix_getpwnam("arsse");

dist/debian/arsse.config

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+set -e
+
+. /usr/share/debconf/confmodule
+
+# Set up dbconfig-common
+if test -f /usr/share/dbconfig-common/dpkg/config; then
+    . /usr/share/dbconfig-common/dpkg/config
+    dbc_dbtypes="sqlite3, pgsql, mysql"
+    dbc_authmethod_user="password"
+    dbc_go arsse "$@"
+fi
+
+# Prompt for dbconfig-common configuration
+db_go || true

dist/debian/arsse.dirs

@@ -0,0 +1 @@
+var/lib/arsse

dist/debian/arsse.install

@@ -0,0 +1,18 @@
+lib       usr/share/arsse/
+locale    usr/share/arsse/
+sql       usr/share/arsse/
+vendor    usr/share/arsse/
+www       usr/share/arsse/
+CHANGELOG usr/share/arsse/
+UPGRADING usr/share/arsse/
+README.md usr/share/arsse/
+arsse.php usr/share/arsse/
+
+config.defaults.php             etc/arsse/
+manual                          usr/share/doc/arsse/
+dist/man/*                      usr/share/man/
+dist/debian/config.php          etc/arsse/
+dist/debian/dbconfig-common.php usr/share/arsse/
+debian/bin/arsse                usr/bin/
+debian/nginx                    etc/arsse/
+debian/apache                   etc/arsse/

dist/debian/arsse.links

@@ -0,0 +1 @@
+etc/arsse/config.php usr/share/arsse/config.php

dist/debian/arsse.postinst

@@ -0,0 +1,29 @@
+#!/bin/sh
+
+set -e
+
+. /usr/share/debconf/confmodule
+
+if [ "$1" = "configure" ]; then
+    # Set permissions on configuration file
+    dpkg-statoverride --list "/etc/arsse/config.php" >/dev/null || dpkg-statoverride --update --add root www-data 640 "/etc/arsse/config.php"
+    # Set up dbconfig-common
+    if test -f /usr/share/dbconfig-common/dpkg/postinst; then
+        . /usr/share/dbconfig-common/dpkg/postinst
+        dbc_generate_include_owner="root:www-data"
+        dbc_generate_include_perms="0640"
+        dbc_generate_include="php:/var/lib/arsse/dbconfig.inc"
+        dbc_pgsql_createdb_encoding="UTF8' lc_collate='C"
+        dbc_mysql_createdb_encoding="UTF8"
+        dbc_dbfile_owner="root:www-data"
+        dbc_dbfile_perms="0660"
+        dbc_go arsse "$@"
+    fi
+fi
+
+# dh_installdeb will replace this with shell code automatically
+# generated by other debhelper scripts.
+
+#DEBHELPER#
+
+exit 0

dist/debian/arsse.postrm

@@ -0,0 +1,20 @@
+#!/bin/sh
+
+set -e
+
+if test -f /usr/share/debconf/confmodule; then
+    . /usr/share/debconf/confmodule
+fi
+
+# Set up dbconfig-common
+if test -f /usr/share/dbconfig-common/dpkg/postrm; then
+    . /usr/share/dbconfig-common/dpkg/postrm
+    dbc_go arsse "$@"
+fi
+
+# dh_installdeb will replace this with shell code automatically
+# generated by other debhelper scripts.
+
+#DEBHELPER#
+
+exit 0

dist/debian/arsse.prerm

@@ -0,0 +1,16 @@
+#!/bin/sh
+
+set -e
+
+. /usr/share/debconf/confmodule
+
+# Set up dbconfig-common
+. /usr/share/dbconfig-common/dpkg/prerm
+dbc_go arsse "$@"
+
+# dh_installdeb will replace this with shell code automatically
+# generated by other debhelper scripts.
+
+#DEBHELPER#
+
+exit 0

dist/debian/config.php

@@ -0,0 +1,15 @@
+<?php
+/***
+    Please refer to config.defaults.php or the manual at /usr/share/doc/arsse/
+    for possible configuration parameters.
+
+    The last line includes database auto-configuration information which
+    Debian may have created during installation; any database-related 
+    configuration defined in this file will override anything defined in the 
+    included file.
+***/
+
+return [
+    'dbAutoUpdate' => true,
+]
++ (@include "/usr/share/arsse/dbconfig-common.php");

dist/debian/control

@@ -6,6 +6,7 @@ Standards-Version: 4.5.1
 Homepage: https://thearsse.com/
 Vcs-Browser: https://code.mensbeam.com/MensBeam/arsse/
 Vcs-Git: https://code.mensbeam.com/MensBeam/arsse/
+Build-Depends: debhelper
 
 Package: arsse
 Architecture: all
@@ -17,16 +18,15 @@ Description: Multi-protocol RSS/Atom newsfeed synchronization server
  client protocols such as Tiny Tiny RSS, Nextcloud News and Miniflux,
  allowing you to use compatible clients for many protocols with a single
  server.
-Build-Depends: debhelper
 Depends: ${misc:Depends},
-         dbconfig-mysql | dbconfig-pgsql |  dbconfig-sqlite3 |  dbconfig-no-thanks,
+         dbconfig-sqlite3 | dbconfig-pgsql | dbconfig-mysql | dbconfig-no-thanks,
          php (>= 7.1.0),
          php-cli,
          php-intl,
          php-json,
          php-xml,
-         php-sqlite3 | php-mysql | php-pgsql
-Recommends: apache2 | nginx,
+         php-sqlite3 | php-pgsql | php-mysql
+Recommends: nginx | apache2,
             php-fpm,
             php-curl,
             ca-certificates

dist/debian/copyright

@@ -2,6 +2,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: arsse
 Upstream-Contact: J. King <jking@jkingweb.ca>
 Source: https://code.mensbeam.com/MensBeam/arsse/
+License: Expat
 
 Files: *
 Copyright: 2017 J. King <jking@jkingweb.ca>

dist/debian/dbconfig-common.php

@@ -0,0 +1,44 @@
+<?php
+
+# This script transforms Debian's dbconfig-common PHP-format include files
+# into a form usable by The Arsse. This is necessary because The Arsse
+# supports defining configuration parameters for all supported database types
+# at once, using separate keys for the different types
+
+$dbconfpath = "/var/lib/arsse/dbconfig.inc"; // path defined in postinst script
+
+if (file_exists($dbconfpath)) {
+    require_once "/var/lib/arsse/dbconfig.inc";
+    $dbtype = $dbtype ?? "";
+    // the returned configuration depends on the $dbtype
+    if ($dbtype === "sqlite3") {
+        $conf = ['dbDriver' => "sqlite3"];
+        if (strlen((string) $basepath) && strlen((string) $dbname)) {
+            $conf['dbSQLite3File'] = "$basepath/$dbname";
+        }
+    } elseif ($dbtype === "pgsql") {
+        $conf = [
+            'dbDriver' => "postgresql",
+            'dbPostgreSQLHost' => $dbserver ?? "",
+            'dbPostgreSQLUser' => $dbuser ?? "arsse",
+            'dbPostgreSQLPass' => $dbpass ?? "",
+            'dbPostgreSQLPort' => (int) $dbport ?: 5432,
+            'dbPostgreSQLDb'   => $dbname ?? "arsse",
+        ];
+    } elseif ($dbtype === "mysql") {
+        $conf = [
+            'dbDriver' => "mysql",
+            'dbMySQLHost' => $dbserver ?? "",
+            'dbMySQLUser' => $dbuser ?? "arsse",
+            'dbMySQLPass' => $dbpass ?? "",
+            'dbMySQLPort' => (int) $dbport ?: 3306,
+            'dbMySQLDb'   => $dbname ?? "arsse",
+        ];
+    } else {
+        throw new \Exception("Debian dbconfig-common configuration file $dbconfpath is invalid");
+    }
+    return $conf;
+} else {
+    // if no configuration file exists simply return an empty array
+    return [];
+}

dist/debian/lintian-overrides

@@ -0,0 +1,6 @@
+# We make reference to "Tiny Tiny RSS"
+spelling-error-in-description Tiny Tiny (duplicate word) Tiny
+# The manual for DrUUID (a dependency) includes a harmless "up" link
+privacy-breach-generic usr/share/arsse/vendor/jkingweb/druuid/documentation/manual.html [<link rel="up" href="http://jkingweb.ca/code/">] (http://jkingweb.ca/code/)
+# We only ask dbconfig-common questions, which don't seem to require templates
+no-debconf-templates

dist/debian/pbuilder.sh

@@ -0,0 +1,40 @@
+#! /bin/bash -e
+
+### 
+# This script is fed to pbuilder to build Debian packages. The base tarball
+# should be created with a command similar to the following:
+#
+#   sudo pbuilder create --basetgz pbuilder-arsse.tgz --mirror http://ftp.ca.debian.org/debian/ --extrapackages "debhelper devscripts lintian"
+#
+# Thereafter pbuilder can be used to build packages with this command:
+#
+#   sudo pbuilder execute --basetgz pbuilder-arsse.tgz --bindmounts `basedir "/path/to/release/tarball"` -- pbuilder.sh "/path/to/release/tarball"
+#
+# This somewhat roundabout procedure is used because the pbuilder debuild
+# command does not seem to work in Arch Linux, nor does pdebuild. Doing
+# as much as possible within the chroot itself works around these problems.
+###
+
+# create a temporary directory
+tmp=`mktemp -d`
+
+# define various variables
+here=`dirname "$1"`
+tarball=`basename "$1"`
+version=`echo "$tarball"