context-minimals

A reproducible ConTeXt LMTX distribution. Sources checked and updated weekly.

Run me with Nix!

These are some common ad-hoc usages.

# run context by default; or luametatex, luatex, mtxrun by specifying them
nix run github:usertam/context-minimals
nix run github:usertam/context-minimals#mtxrun

# get a shell with all the goodies
nix shell github:usertam/context-minimals

Setup with binary cache

Now comes with binary cache at context-minimals.cachix.org! However, only x86_64-linux and x86_64-darwin are cached as of now, because GitHub Actions.

# add to $HOME/nix/nix.conf (user) or /etc/nix/nix.conf (system)
extra-experimental-features = nix-command flakes
extra-substituters = https://context-minimals.cachix.org
extra-trusted-public-keys = context-minimals.cachix.org-1:pYxyH24J/A04fznRlYbTTjWrn9EsfUQvccGMjfXMdj0=

Tex PDFs declaratively, with flakes

In flake.nix, use mkCompilation in modules/lib/default.nix to compile main.tex.

{
  inputs.context-minimals.url = "github:usertam/context-minimals";
  inputs.photo.url = "https://unsplash.com/photos/.../download";  # include extra files, but only in `nix build`
  inputs.photo.flake = false;

  outputs = { self, context-minimals, ... }@inputs: let
    fonts = [ "source-han-serif" ]; # include nixpkgs-provided fonts
    fcache = [ "sourcehanserif" ];  # force build font caches, useful for slow CJK fonts
  in {
    packages = context-minimals.lib.mkCompilation {
      inherit fonts fcache;
      src = self;
      nativeBuildInputs = [ "imagemagick" ];  # include tools to use in `postUnpack`
      postUnpack = "convert -quality 100% -despeckle ${inputs.photo} $sourceRoot/photo.jpeg";
    };
    apps = context-minimals.lib.mkCompilationApps {
      inherit fonts fcache;
    };
  };
}

Remarks

By default, installing ConTeXt LMTX requires downloading a prebuilt mtxrun to bootstrap the installation. The installation script mtx-install.lua is then run, downloading and extracting archives in the process; after which the modules would need to be installed separately. While the defaults focus on the ease of maintaince (running mtx-update), the internals are harder to dissect.

The installation script is a lengthy lua script, making the fetching and extracting steps unclear from first glance. The two-part installation, platform-dependent setups and install steps also didn't make it easy to follow. Along with the use of unpinned prebuilt binaries, it was challenging to reproduce an installation that could be used out-of-the-box.

Solution

The project didn't follow the installation script, but rather reconstructs the tex structure based on the sources and by looking at the artifact. The reworked steps are then trimmed down and implemented in default.nix, building binaries luametatex and luatex from source. Fonts and font caches are another can of worms, and needed a number of patches to stay deterministic but functional.

Apart from the reproducibility of the ConTeXt installation, the deterministic compilation of PDFs is another goal of the project. ConTeXt does offer flags like randomseed, nodates and trailerid to disable non-deterministic PDF subtleties, but not well-documented. Therefore, functions like lib.mkCompilation are provided to offer "standard" ways to compile PDFs.

Note that non-determinism can still be introduced by macros like \date. For MetaPost, randomseed := 0; is still needed to make uniformdeviate deterministic.