Installing ddccontrol-db
========================

ddccontrol-db is a data-only package. It does not compile programs or
libraries. Its small handwritten configure script only selects installation
directories and checks commands needed by the subsequent make targets.
The Makefile uses portable make syntax and is tested with both GNU Make and
BSD make (`bmake`).

On a system where BSD make is installed as `bmake`, use:

    MAKE=bmake ./configure --prefix=/usr
    bmake
    bmake install

Installing a release archive
----------------------------

Release archives contain generated XML, CBOR, snapshot and source manifests,
and compiled gettext catalogs. Installation needs make, a SHA-256 utility
(sha256sum, sha256 or shasum), and the usual install, mkdir, awk, sed and shell
utilities:

    ./configure --prefix=/usr
    make
    sudo make install

The default prefix is /usr/local.

Building from a Git checkout
----------------------------

A Git checkout additionally needs GNU gettext to compile po/*.po to po/*.gmo,
and ddccontrol-dbgen to generate CBOR. See doc/cbor/producer.md for obtaining
the pinned Rust generator or providing an existing executable:

    ./configure --prefix=/usr
    make
    sudo make install

Select an executable outside PATH with either
`DDCDBGEN=/absolute/path/to/ddccontrol-dbgen ./configure` or
`./configure DDCDBGEN=/absolute/path/to/ddccontrol-dbgen`. This selection is
saved for subsequent make invocations. An environment or make command-line
DDCDBGEN value overrides the saved selection.

Compatibility with package build recipes
----------------------------------------

The retained autogen.sh is a compatibility stub. Existing recipes that run
autogen.sh before configure can keep doing so; it prints a migration notice
and succeeds without invoking Autoconf, Automake, Intltool, or Libtool.

The configure script accepts the standard directory, build/host, program-name,
dependency-tracking, and silent-rule options commonly supplied by Debian and
RPM package helpers. Options irrelevant to this data-only package are accepted
but have no effect. To build without translation catalogs, use:

    ./configure --prefix=/usr --disable-nls

Recipes that invoke autoreconf or eautoreconf directly are temporarily covered
by a minimal configure.ac compatibility shim. The generated configure forwards
all arguments to the handwritten configure implementation. Packagers should
still remove the regeneration step: configure and Makefile are maintained
source files, and Autoconf is not a normal build dependency.

Installation variables
----------------------

The Makefile supports these variables:

    PREFIX      installation prefix; defaults to /usr/local
    DATADIR     data root; defaults to $(PREFIX)/share
    DBDIR       database directory; defaults to $(DATADIR)/ddccontrol-db
    LOCALEDIR   locale root; defaults to $(DATADIR)/locale
    DESTDIR     staging root used by package builders
    LINGUAS     space-separated translations to build and install

The traditional lowercase `prefix`, `datadir`, `localedir`, and `dbdir`
spellings are accepted as aliases for existing package recipes. Unknown names
in `LINGUAS` are ignored, matching the previous gettext build behavior.

For example, a distribution package can stage files without root privileges:

    ./configure --prefix=/usr
    make install DESTDIR="$pkgdir"

To install only selected translations:

    make install PREFIX=/usr LINGUAS="fr pl"

Validation and maintenance
--------------------------

Run the version and translation checks with:

    make check

This target does not require Perl. Run the optional list-control checks and
the checker regression tests separately with:

    make check-controls

This target requires Perl and XML::Parser (the libxml-parser-perl package on
Debian and Ubuntu) and runs explicitly in GitHub CI and release validation.
It does not require monitor hardware. The list-control
check rejects unused entries in db/known-empty-list-controls, so remove an
exception when its control is fixed or removed.
The check follows explicit caps add/remove changes through includes, starting
with all VCP addresses available as ddccontrol -i does. Controls disabled before
their definitions are reached do not require list values or exceptions.

Validate every monitor profile with an installed ddccontrol command:

    make check-db

This target validates a temporary XML-only copy, so existing generated CBOR
cannot hide edits to the maintained XML. It does not require the generator.

Translation maintainers can regenerate the gettext template and merge it into
the PO files. This target requires gettext and Perl:

    make update-po

Create gzip, bzip2, and xz release archives with compiled translations. This
maintainer target additionally requires Git and tar with gzip, bzip2, and xz
support:

    make dist

Remove generated files with `make clean`, or generated files and release
archives with `make distclean`.

CBOR dual distribution
----------------------

XML remains the maintained source. `make` generates one uncompressed
`db/ddccontrol-db.cbor` and `db/ddccontrol-db.snapshot` from the exact same XML
snapshot. Both are installed beside options.xml and monitor/*.xml; translation
catalogues remain unchanged. No end date for XML distribution is defined.

Git builds require ddccontrol-dbgen. Release archives include CBOR, a SHA-256
source manifest and compiled translations, so installation does not require
the generator, Rust, Python or gettext. The source manifest also records the
generator source pin. Edits, additions and deletions invalidate reuse even when
timestamps are preserved; regeneration requires the selected generator.
`make check-cbor` uses it to validate the whole database, frozen fixtures,
reproducibility and the build/install regression cases.

A generation failure removes stale CBOR and snapshot outputs and fails the
build. The standalone generator also atomically replaces each successful
output. Packaging tools should stage an entire installation before replacing
an installed database. A reader must pin its chosen source for its load session.

See doc/cbor-distribution.md for converter, validator and readable dump commands.
