Umbrellix Left politics, programming, and self-hosted Internet services: experiences, lessons and hope

The slashpackage quick reference handbook

Initially written starting 20:24 UTC on the 9th of October, 2022 a.d. by Amelia Bjornsdottir (she, they)

This page wouldn’t exist without J. de B. P.’s page on the same matter. This page is meant to be a comprehension of that one, with

General structure of a package (folk will be confused if this is not followed)

Directories, by purpose. Sorted by second column (purposes grouped together, no particular order) if possible.

Authority Directory Stage Purpose
J. de B. P. source/
src/
Input (read-only, ideally) This directory holds all input files to compilation and interpretation tools.
J. de B. P. build/ Work (writable) Used during compilation. Not guaranteed to exist.
djb (/pkg/cr.yp.to/admin/daemontools-0.76/package) compile/ Work (writable, non-persistent) Used during compliation. Is created by package/compile.
J. de B. P. config/ Output “built configuration files” - ambiguous
J. de B. P. library/ Output Output directory for both statically and dynamically linked libraries.
J. de B. P. include/ Output Output directory for development headers the package provides.
skarnet library/ Output Output directory for statically linked libraries.
skarnet library.so/ Output Output directory for dynamically linked libraries.
J. de B. P. manual/
man/
Output This directory contains compiled manuals.
- doc/ Ambiguous - not work This directory contains documentation in packages that ship documentation locally. It’s ambiguous whether this is input or output. Treat it as input.
P. R. Jarc conf-compile/ Input (writable) cr.yp.to/admin/sptools expects to write to files here to configure a package
P. R. Jarc conf-compile/defaults/ Input (read-only) Defaults used by sptools-compatible packages
Myself head/ Input This directory contains development headers used in source/ or src/.

Structure of package/

TODO: fill this out based on packages as well as the J. de B. P. page on the matter.

Structure of conf-compile (Jarc)

Jarc’s sptools shell scripts are as thick as stirred cornflour wash with his own idioms. Here is the best I could make. I also downloaded and unpacked /pkg/cr.yp.to/prog/prjlibs-2020.05.04 for study, which has provided some edification (although the git repository underlying it did not - it doesn’t contain everything you need to compile a development snapshot of prjlibs. Neither does the sptools counterpart).

Putative get_confcompile_variable function

In pseudocode:

string get_confcompile_variable (string variable)
{
 string filename = "conf-compile/";
 string deffilename = "conf-compile/defaults/";
 filename += variable;
 deffilename += variable;
 if exists(filename) {
  get_firstline(filename);
 } otherwise {
  get_firstline(deffilename) or panic;
 }
}

In English: If exists a file named variable in conf-compile, the value is the first line of the file named variable in conf-compile. Otherwise, it is the first line of the file named variable in defaults in conf-compile. In default of even that, unstudied as of this revision.

conf-compile variables (Jarc)

Unless specified as host/n/…, all packages named here are to be assumed as named under the authority of cr.yp.to, and to be visible in the filesystem at /pkg/cr.yp.to and /package.

Variable Description of value Seen in packages Requirement level
package_home This is where the package is meant to be found at runtime. prog/prjlibs, admin/runwhen, admin/sptools Apparently mandatory.
compile_user This is the user the compilation is to proceed as. prog/prjlibs, admin/runwhen, admin/sptools Defaults to current user.
host_compile.sh
host_library.sh
host_link.sh
Shell snippets (not scripts) which describe the way to compile to an object, create a ranlib library, and link an executable. All except link seen in both admin/runwhen and prog/prjlibs. Link seen in runwhen. All absent in sptools Different build systems may use different filenames for the same purpose, or use an environment file rather than shell snippets. An auto-testing script could set these values.