`foomatic-db-ppds` uses the Foomatic database from the packages
`foomatic-db` and -- optionally -- `foomatic-db-nonfree`
and the perl modules from `foomatic-db-engine`
to generate about 8,800 ppd files.
The general structure of the build recipe is as follows:
* Merge `foomatic-db` and `foomatic-db-nonfree` into
one package that represents the Foomatic database.
The package `foomatic-db-nonfree` is optional
as it taints the result license-wise;
it will only be used if `withNonfreeDb`
is to to `true` in the `callPackage` call.
We create a tiny setup hook script that provides the combined
database and sets an environment variable pointing to the
database direcotry, which is expected by the foomatic engine.
* The final package's license and version are computed
from the licenses and versions of the database packages.
The license is set to `free` if each database-providing
package has a free license, and to `unfree` otherwise.
The version is simply the highest version
of the database-providing packages.
* The final package uses `foomatic-compiledb`
from the `foomatic-db-engine` package to extract
all ppd files from the database packages.
`patchPpdFilesHook` is used to patch most
executable invocations in the ppd files
so that they point to nix store paths.
Finally, ppd files are gzipped to reduce storage
(from about 550 MiB to 90 MiB installed).
The "nonfree" version of the package, i.e. the version that is
based on `foomatic-db-nonfree` in addition to `foomatic-db`,
contains about 120 additional ppd files
compared to the "free" version.
Since the "free" version already produces about 8,700
ppd files and hydra won't build the "nonfree" version,
the commit adds two package variables to `all-packages.nix`:
* `foomatic-db-ppds` is based on `foomatic-db` only
* `foomatic-db-ppds-withNonfreeDb`
is also based on `foomaitc-db-nonfree`
The package introduced by this commit
is the result of combining other packages;
it is not the build product of a simple source tarball.
While it would also be possible to perform the ppd file
generation directly in the build process of the database
packages, this would yield further complexity as the
`foomatic-db-nonfree` package needs to be combined with the
`foomatic-db` package before ppd file extraction is possible.
There is no upstream product with a name that
could/should be used for the `name` attribute,
the variable name, or for the filename in nixpkgs.
Similar packages have different names across distributions:
* https://repology.org/projects/?search=openprinting
* https://repology.org/projects/?search=foomatic
The name `foomatic-db-ppds` seems to be most common
(albeit not really *that* common):
* https://repology.org/project/foomatic-db-ppds/versions
At least openSUSE splits their corresponding
package into multiple "binary" packages
(similar to our multi-output packages):
* https://build.opensuse.org/package/binaries/Printing/OpenPrintingPPDs/openSUSE_Tumbleweed
I considered something similar.
However, after doing some statistics,
I concluded that it's not worth the effort:
The biggest dependencies (`perl` and `cups-filters`) are
already present on most NixOS systems, and they cannot
be "split away" easily since it cannot be
done along a canonical line (e.g. printer driver).
Splitting directly by dependency risks that ppd files
unexpectedly "move from output to output" on package updates;
disappearing ppd files can be quite annoying for package users.
`foomatic-db-nonfree` contains -- similar to its sister
package `foomatic-db` -- knowledge about printers,
drivers, and driver options from OpenPrinting in xml files.
It needs to be combined with the `foomatic-db`
package to yield a working database.
It also provides about 100 (gzipped) ppd files.
In contrast to `foomatic-db`, this package contains
data that is provided under non-free licenses.
Quoting
https://github.com/OpenPrinting/foomatic-db-nonfree/blob/master/README
> This is a repository of PPD and Foomatic XML files that may
> have restrictions that keep them from being used on a variety
> of machines for licensing and other non-technical reasons.
ppd files can be found in
`$out/share/cups/model/foomatic-db-nonfree`.
The subdirectory `foomatic-db-nofree` is used to avoid conflicts
with other packages that might be combined with the package
`foomatic-db-nonfree` in `config.services.printing.drivers`.
ppd files in this package are *not* patched
to call executables from the nix store:
The only executable "rastertophaser6100" that is
called from ppd files isn't available in nixpkgs.
There is a daily snapshot of a source archive available at
https://www.openprinting.org/download/foomatic/ .
However, these files rotate daily and
cannot be used as a stable download source.
So we rely on OpenPrinting's Github repository
instead and pinpoint a fresh commit.
Note that the current version is from 2015,
so updates are unlikely.
`foomatic-db` contains the collected knowledge about printers,
drivers, and driver options from OpenPrinting in xml files.
It also provides thousands of ppd files.
The build process patches those files to reference executables
in the nix store and gzips them to reduce storage
(from about 670 MiB to 90 MiB installed).
In contrast to the sister package `foomatic-db-nonfree`
(packaged in a follow-up commit),
this package only includes files published under a free license.
Most files are published under the GPL,
some under the MIT license.
For details see
https://github.com/OpenPrinting/foomatic-db/blob/master/COPYING .
To encompass the different licenses, the package's
license is set to "free" as the common denominator.
ppd files can be found in `$out/share/cups/model/foomatic-db`.
The subdirectory `foomatic-db` is used to avoid conflicts
with other packages that might be combined with the package
`foomatic-db` in `config.services.printing.drivers`.
There is a daily snapshot of a source archive available at
https://www.openprinting.org/download/foomatic/ .
However, these files rotate daily and
cannot be used as a stable download source.
So we rely on OpenPrinting's Github repository
instead and pinpoint a fresh commit.
`foomatic-db-engine` contains several perl scripts to parse
and process XML files from the Foomatic database packages.
It can be used to extract ppd files,
which will be accomplished in a follow-up commit.
The package also contains scripts
to handle print queues and jobs.
It can -- optionally -- talk to the local cups server,
to network printers and to SMB print servers.
The build recipe contains switches to enable these features;
however, they are not needed when generating ppd files.
There is a daily snapshot of a source archive available at
https://www.openprinting.org/download/foomatic/ .
However, these files rotate daily and
cannot be used as a stable download source.
So we rely on OpenPrinting's Github repository
instead and pinpoint a fresh commit.
PostScript Printer Description (ppd) files
describe printer features and capabilities.
They are usually evaluated by CUPS to convert
print jobs into a format suitable for a printer.
The conversion is often accomplished by commands
or even short shell scripts inside the ppd files.
ppd files are included in many printer driver packages.
Their scripts sometimes refer to other executables;
some of them are more common (like `perl`),
others are more exotic (like `rastertohp`).
If an executable is called with its name alone,
the effects of the ppd file depend on whether
the executable is in the PATH of CUPS,
and on the executable's version.
If an executable is called with an absolut path
(like `/usr/bin/perl`), it won't work at all in NixOS.
The commit at hand adds a setup hook that uses
the `fixupPhase` to substitute certain executable's
invocations in pdd files with absolute paths.
To use it, add the hook to `nativeBuildInputs` and
provide a list of executable names in `ppdFileCommands`.
Each executable must be available in the
package that is being built, or in `buildInputs`.
The setup hook's script then looks for ppd files in
`share/cups/model` and `share/ppds` in each output,
and replaces executable names with their absolute paths.
If ppd files need to be patched in unorthodox locations or
the setup hook needs to be invoked manually for other reasons,
one may leave the list `ppdFileCommands` empty to
avoid automatic processing of ppd files, then call
the shell function `patchPpdFileCommands` directly.
Details are described in the file `patch-ppd-hook.sh`.
Notes on the motivation for this setup hook:
Most packages in nixpkgs that provide
ppd files do not patch those ppd files at all.
This is not fatal when the executables are just called
with their names since the user can add packages
with the executables to `services.printing.drivers`.
E.g. if the user adds `pkgs.perl`, then all ppd
files that invoke `perl` will work as expected.
Nevertheless, to make these ppd files independent of
their execution environment, command invocations should
be substituted with absolut paths into the nix store.
This is similar to patching shebang lines so scripts can be
called independently of having the interpreter in the PATH.
The hook script in this commit is meant to support new packages
`foomatic-db*` which will generate several thousands of
ppd files referencing a plethora of different executables.
During development of these packages, I realized that
it's quite hard to patch ppd files in a robust way.
While binary names like `rastertokpsl` seem to be sufficiently
unique to be patched with `sed`, names like `date` or `gs`
are hard to patch without producing "false positives",
i.e., coincidental occurences of the executable's name that do
*not* refer to the executable and should not be patched at all.
As this problem also affects other packages,
it seems reasonable to put a robust implementation
in its own setup hook so that other
packages can use it without much effort.
Notes on the implementation:
The ppd file format is far from trivial.
The basic structure are key-value pairs;
keys may occur multiple times.
Only a small subset of keys may contain
executable names or shell scripts in their values.
Some values may span multiple lines;
a linebreak might even occur in the middle of a token.
Some executable names also occur in other keys by accident
where they must not be substituted (e.g. `gs` or `date`).
It is necessary to provide the list of command
names that will be patched for two reasons:
ppd files often contain "tokens" that might look
like commands (e.g. "file" or "host") but aren't;
these would erroneously get patched.
Also, looking for everything that might be a command
would slow down the patching process considerably.
The implementation uses `awk` to detect
keys that might contain executable names;
only their values are treated for substitution.
This avoids most cases of "overzealous" substitutions.
Since values may span multiple lines,
`sed` alone (while faster than `awk`) cannot focus
its substitution capabilities on relevant keys.
An elaborate set of regular expressions further helps
to minimize the probability of "false positives".
Several tricks are employed to speed up `awk`.
Notably, relevant files are identified with
`grep` before `awk` is applied to those files only.
Note that the script probably cannot handle fancy command
names (like spaces or backslashes as part of the name).
Also, there are still edge cases that the script would
mistakenly skip, e.g. if a shell script contains a
line break in the middle of an executable's name;
although ppd files permit such constellations,
I have yet to see one.
ppd files may be gzipped.
The setup hook accepts gzipped ppd files:
It decompresses them, substitutes paths, then recompresses them.
However, Nix cannot detect substituted paths as
runtime dependencies in compressed ppd files.
To ensure substituted paths are propagated as
runtime dependencies, the script adds each substituted
path to the variable `propagatedBuildInputs`.
Since this might not be enough for multi-output packages,
those paths are also written directly to
`nix-support/propagated-build-inputs`.
See the comment in `patch-ppd-hook.sh` for details.
Finally, the setup hook comes with a small test that
probes some edge cases with an artificial ppd file.
References:
* https://www.cups.org/doc/spec-ppd.html
* general ppd file specification
* lists some keys that may contain
executable names or shell scripts
* https://refspecs.linuxfoundation.org/LSB_4.0.0/LSB-Printing/LSB-Printing/ppdext.html
* lists some keys that may contain
executable names or shell scripts
* https://en.wikipedia.org/wiki/PostScript_Printer_Description#CUPS
* lists the usual locations of ppd files
