Background

Developers (and pipelines) check out a repository into a local environment, or container, as follows:

git clone https://hostname/repositories/project

This project contains fonts, images, and documents ready for typesetting. We'd like to typeset by passing the font directory into ConTeXt via the command-line, such as:

mtxrun --arguments=fontsdir=/path/to/project/fonts

Every developer has a different path to the fonts directory (e.g., $HOME/repos/project/fonts) because we don't control the repository's clone path.

Environment

mtx-context     | current version: 2025.04.28 14:29

Problem

The issue is that the fonts, after being checked out from the repository, aren't being picked up by ConTeXt. This makes sense because we haven't told it where to find the fonts, which can be found relative to the project's root directory.

While we could tell the developers to update OSFONTDIR and run mtxrun --script fonts --reload, it's a bit cumbersome. Preferably, the path could be passed in:

mtxrun --arguments=fontsdir=$HOME/repos/project/fonts

Code

What we want is to run the following code (or similar) before typesetting starts:

\ctxlua{
  os.setenv(
    "RUNTIMEFONTS",
    context( "\env{fontsdir}" )
  )
}

This is just one idea. The result of running that code is the path to the fonts directory is typeset into the document. That tells us the path is correct, but it also means that the RUNTIMEFONTS value isn't set.

Even hard-coding the path, in place of calling context(...) doesn't work, so setting the RUNTIMEFONTS variable is not feasible.

Ideas

Environment variables

We updated the Makefile to set the environment variables, but requires running mtxrun twice (once with --generate; using --autogenerate doesn't work to autodetect the cache directory), such as:

guide:
  command -v mtxrun || { echo "Install ConTeXt"; exit 1; }

  TEXMFCACHE="/tmp" OSFONTDIR="$(THEME_DIR)/fonts//" \
  mtxrun --generate

  TEXMFCACHE="/tmp" OSFONTDIR="$(THEME_DIR)/fonts//" \
  mtxrun --autogenerate ...

This allows make guide without having to pass environment variables to make.

\usefontpath

We modified "setups.tex" (the main entry point for our documentation's .tex files) with the following line:

\doifdocumentargument{fontsdir{%
  \usefontpath[\getdocumentargument{fontsdir}]
}

And added fontsdir to specify the fully qualified path to the fonts directory:

mtxrun \
 --autogenerate \
 --script mtx-context \
 --batchmode \
 --nonstopmode \
 --purgeall \
 --environment=main \
 --arguments=fontsdir=/path/to/fonts

The fonts did not get used, likely because getdocumentargument{fontsdir} is returning an empty string:

  \startdocument
    FONTDIR:\getdocumentargument{fontsdir}

    % ... etc.    
  \stopdocument

Using \usefontpath[\env{fontsdir}] did not work to find the files, despite \env{fontsdir} being a valid and fully qualified directory containing the font files.

Question

What is the best way to dynamically set a font directory at runtime using ConTeXt? (Recursively would be ideal, but all the fonts are in a flat directory structure, so recursion isn't needed for our purposes.)