# $Id: README 98 2026-11-05 12:28:43Z peter $

sapupra
=======

A simple management system for a personal library: books, records,
films and other media of one individual, counted in thousands.
Barcodes are scanned with a smartphone, the bibliographic information
is looked up on the Internet, and the catalogue is consulted from any
browser of the local network. Everything but the lookup stays local.

Status (0.50.0): architecture adopted for a first prototype, around an
MQTT broker, with the handling of failed lookups and an entry module
for what cannot be scanned; Design.org designs the programs, in C++17
with Qt 6. Written so far: their common library, the gateway (sppgate,
which receives the scans of the phones and hands them to the broker),
the worker (sppwork, which records them, looks them up in Open Library,
the BnF, MusicBrainz, the German national library and, with YAZ, the
national libraries of Hungary and Italy and the Library of Congress, and catalogues them in a SQLite database), the
entry module (sppentry, the pages where the scans that failed are
settled by hand, by ISBN, by a search by author and title, or set aside,
and Binary Eye's history is imported, and the catalogue is searched
and read: pages of our own, in English or in French, Datasette being an optional extra), the
consultation program (sppconsult, those pages of the catalogue and no others, to be put behind
a proxy, Caddy or nginx, for a reader outside the local network), the
printer of labels (spplabel, which draws the codes with libzint), the
lister (spplist, which writes the catalogue as an Org document of tables
by author, by title and by location, to be exported to PDF or HTML), a
generator of invented catalogues to try them on (sppgen), their
unit tests (make check), and a maintainer tool, orgdoc-check, that
checks the documents. Manual.org describes what can already be
installed and tried (the phone applications, the broker, the gateway,
the worker, the entry module, the catalogue pages). See Concept.org and FutureResearch.org.

The name is a romanized abbreviation of the Sanskrit phrase "saral
pustakalaya prabandhan pranali", "simple library management system".


Documents
---------

Start at Index.org (Index.pdf / Index.html once built) for the full,
linked document set:
- Concept.org --- goal, the collection, prior art, architecture,
  glossary.
- Design.org --- the design of the programs: messages, database,
  configuration.
- Manual.org --- the guide to installing and using sapupra, by role:
  user, admin, developer and prototyping.
- FutureResearch.org --- open questions and decisions, in order.
- DevelopmentStandard.org --- coding, documentation, build, and
  packaging rules.
- ResearchJournal.org --- dated record of decisions and rationale,
  with the sources of every finding.

Two documents are deliberately not published: Constitution.org
(private) and SessionHandoff.org (an internal, terse, continuously
rewritten continuity note).


Layout
------

Flat: every source file lives at the project root, no subdirectory
(a rule of DevelopmentStandard.org). A figure is a fig-NAME.dot
Graphviz source; its SVG and PDF are built, never kept.


Build prerequisites
-------------------

./configure checks every prerequisite of what is built, lists all the
missing ones at once, each with the package to install on Debian and
on FreeBSD, and stops: make never discovers one. What is not wanted is
left out with --disable-pdf, --disable-html or --disable-programs.

Always:
- GNU Make (on FreeBSD this is usually `gmake`, not `make`).
- bash.

The programs and their tests (unless --disable-programs):
- a C++17 compiler, pkg-config, Qt 6.4 or later (Core, Network, Test),
  libmosquitto 2.0 or later, and the mosquitto program, which the
  tests start for themselves (a running broker is not needed).
  Debian: apt install g++ pkg-config qt6-base-dev libqt6sql6-sqlite
  libmosquitto-dev mosquitto; FreeBSD: pkg install pkgconf qt6-base
  qt6-base_sqldriver-sqlite mosquitto.
- optionally YAZ 5, for the Z39.50 sources of the national libraries of
  Hungary and Italy. Debian: apt install libyaz-dev (the development
  package: not just `yaz`, which has only yaz-client); FreeBSD: pkg
  install yaz. Without it the programs are built without those two
  sources, and configure says so at its end; --without-yaz leaves them
  out on purpose, --with-yaz makes YAZ a prerequisite.
- optionally libzint (Zint), for spplabel, the printer of labels.
  Debian: apt install libzint-dev; FreeBSD: pkg install zint. Without
  it spplabel is not built, and configure says so at its end;
  --without-zint leaves it out on purpose, --with-zint makes it a
  prerequisite. On FreeBSD the library is in /usr/local, which the
  compiler does not search and which has no .pc file: configure tries
  /usr/local and /opt/local by itself, and --with-zint=DIR names another
  prefix (the one with include/zint.h and lib/libzint.so).
  A warning of the compiler is an error (-Werror); ./configure
  --disable-werror is there for a compiler newer than the code.

The documents, PDF and HTML (unless --disable-pdf and --disable-html):
- Emacs 29+ with Org 9.6+, and Graphviz (dot) for the figures.

The PDF documents (unless --disable-pdf):
- LuaLaTeX, with kpsewhich and luaotfload-tool, and the LaTeX packages
  of the documents (configure names any that is missing; on Debian
  most are in texlive-latex-extra, texlive-plain-generic and
  texlive-luatex; on FreeBSD, texlive-full has them all);
- the fonts DejaVu Sans Mono and Noto Sans Devanagari (the latter for
  Concept.pdf, which quotes the project's name in Devanagari script;
  Debian: fonts-noto-core; FreeBSD 14.5: noto-sans-devanagari and
  noto-serif-devanagari);
- latexmk is optional: without it, four explicit LuaLaTeX passes.
configure compiles the documents' preamble, so that a package missing
behind another is found too.

The HTML documents (unless --disable-html):
- groff, for the manual pages in HTML: on Debian the package groff, not
  groff-base, which has the program and not the HTML device (configure
  tries the device).

`make check` runs the unit tests of the programs' library (unless
configured with --disable-programs), then ./orgdoc-check, which checks
the Org-mode documents against the markup rules of
DevelopmentStandard.org (orgdoc-check(1)); orgdoc-check needs only
bash and awk.


Building
--------

    ./bootstrap          # regenerate configure/Makefile.in (only needed
                         # after a fresh checkout or editing configure.ac/
                         # Makefile.am)
    ./configure          # checks every prerequisite; optionally
                         # INDEX=URL, the HTML home link, and
                         # --disable-programs, --disable-pdf,
                         # --disable-html
    make                 # builds the programs' libraries, the gateway,
                         # sppgate, and the worker, sppwork, with
                         # their service files
    make check           # unit tests, then orgdoc-check
    make install         # installs sppgate and sppwork, their manual pages,
                         # sapupra.ini.sample and the reader documents
                         # in their PDF version (under /usr/local; make
                         # pdf first); not the Org sources, nor the
                         # research journal nor the future research list
    make pdf             # builds Index.pdf, Concept.pdf, Design.pdf,
                         # Manual.pdf, FutureResearch.pdf,
                         # DevelopmentStandard.pdf, ResearchJournal.pdf
    make html            # builds the same seven as a linked HTML set
    make html-export     # both, bundled for a web server
    make clean           # removes the above and version.org
    make maintainer-clean # additionally removes configure, Makefile.in, etc.

Keeping a working copy clean. Unpacking a newer archive over an older
tree leaves the files that the newer one dropped. Every archive
carries a MANIFEST, the list of the files it ships; ./stale-files
lists the files of the directory that it does not list. Run directly
or by `make stale` it reports them as an error (exit 1); a plain make,
make check, make install, make pdf, make html, make figures and make
html-export run it as a warning and carry on; the clean targets do not
run it. ./stale-files --delete removes them; files of your own that are
meant to stay go in .stale-ignore, one path or glob per line. Best of
all, unpack each archive into an empty directory.


Delivery
--------

The project's delivery archive is produced by `./make-archive`, which
packages the whole source tree as `sapupra-VERSION.tar.xz` (every file
at the top level of the archive), honouring `.tar-exclude`, and
refuses a top-level file that Makefile.am does not name. Run it after
a documentation build and a `make maintainer-clean`. `make dist` is
not the delivery mechanism (DevelopmentStandard.org, "Delivery
Archive").


License
-------

GNU General Public License v3 or later. See COPYING.
