LUAOTFLOAD-TOOL(1)

📦
version 74324 · 6 versions
, in arch rolling, debian trixie, fedora 44, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 luaotfload-tool — text processing, bestie 💅

okay so you found the manual for luaotfload-tool, and honestly? iconic. it's a section 1 (general commands) page from text processing, and it's literally the tool that builds and interrogates the Luaotfload font names database. let's get into it 🫶

✨ NAME ✨

luaotfload-tool — generate and query the Luaotfload font names database

🌸 SYNOPSIS 🌸

luaotfload-tool [ -bcDfFiIlLnpqRSuvVhw ]

luaotfload-tool --update [ --force ] [ --quiet ] [ --verbose ]
       [ --prefer-texmf ] [ --dry-run ] [ --formats=[+|-]EXTENSIONS ] [
       --no-compress ] [ --no-strip ] [ --local ] [ --max-fonts=N ]

luaotfload-tool --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]
       [ --no-reload ]

luaotfload-tool --flush-lookups

luaotfload-tool --cache=DIRECTIVE

luaotfload-tool --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]

luaotfload-tool --bisect=DIRECTIVE

luaotfload-tool --help

luaotfload-tool --version

luaotfload-tool --show-blacklist

luaotfload-tool --diagnose=CHECK

luaotfload-tool --conf=FILE --dumpconf

💖 DESCRIPTION 💖

luaotfload-tool is your girl for getting at the font names database that the Luaotfload package literally cannot function without. and there are two whole general modes, so pick your vibe:

  • update: update the database or rebuild it entirely;
  • query: resolve a font name or display close matches.

👑 OPTIONS 👑

🔥 update mode

  • --update, -u — updates the database; indexes new fonts. fresh fonts, fresh me.
  • --force, -f — forces a full rebuild of the database; re-indexes every single font. no shortcuts, no mercy.
  • --local, -L — includes font files sitting in $PWD. heads up bestie, this causes large parts of the database to be rebuilt, so it is quite inefficient. and on top of that: if local font files are found, the database is prevented from being saved to disk, which means those local fonts need to be parsed every single time you invoke luaotfload-tool. 😭
  • --no-reload, -n — suppresses auto-updates to the database (like when --find gets handed a name it doesn't know). no surprise rebuilds, tyvm.
  • --no-compress, -c — do not filter the plain text version of the font index through gzip. useful for debugging if your editor is built without zlib. vintage editor core. 🙈
  • --prefer-texmf, -p — organizes the file name database so it prefers fonts in the TEXMF tree over system fonts whenever a font is installed in both places.
  • --formats=EXTENSIONS — which font file extensions get indexed. EXTENSIONS here is a comma-separated list of supported file extensions (otf, ttf, ttc). if the list is prefixed with a + sign, the given list is added to the currently active one; - subtracts instead. default is otf,ttf,ttc. examples, because we love a demo:
    1. --formats=-ttc,ttf would skip TrueType fonts and font collections;
    2. --formats=otf would scan only OpenType files;
    3. --formats=+afm includes binary Postscript files accompanied by an AFM file.

🦋 query mode

  • --find=NAME — resolves a font name. it looks up <name> in the database and prints the file name it's mapped to. --find also understands request syntax, i.e. --find=file:foo.otf checks whether foo.otf is indexed. so versatile.
  • --fuzzy, -F — shows approximate matches to the file name if the lookup flopped (requires --find). bestie behavior, honestly.
  • --info, -i — displays basic information for a resolved font file (requires --find).
  • --inspect, -I — displays detailed information by loading the font and analyzing the font table. very slow! for the meaning of the returned fields, see the LuaTeX documentation. (requires --find).
  • --list=CRITERION — shows entries, where CRITERION is one of the following:
    1. the character *, selecting all entries;
    2. a field of a database entry, for instance version or format*, according to which the output will be sorted. information in an unstripped database (see the option --no-strip above) is nested: subfields of a record can be addressed using the -> separator, e. g. file->location, style->units_per_em, or names->sanitized->english->prefmodifiers. NB: shell syntax requires that arguments containing -> be properly quoted!
    3. an expression of the form field:value to limit the output to entries whose field matches value. the value can contain * to match an arbitrary number of characters.

for example, in order to output file names and corresponding versions, sorted by the font format:

./luaotfload-tool.lua --list="format" --fields="file->base,version"

this prints:

otf latinmodern-math.otf  Version 1.958
otf lmromancaps10-oblique.otf 2.004
otf lmmono8-regular.otf 2.004
otf lmmonoproplt10-bold.otf 2.004
otf lmsans10-oblique.otf  2.004
otf lmromanslant8-regular.otf 2.004
otf lmroman12-italic.otf  2.004
otf lmsansdemicond10-oblique.otf  2.004
...
  • --fields=FIELDS — comma-separated list of fields that should be printed. information in an unstripped database (see the option --no-strip above) is nested: subfields of a record can be addressed using the -> separator, e. g. file->location, style->units_per_em, or names->sanitized->english->subfamily. the default is plainname,version*. (only meaningful with --list.)

🎀 font and lookup caches

  • --flush-lookups — clears the font name lookup cache (experimental). 🔬
  • --cache=DIRECTIVE — cache control, where DIRECTIVE is one of the following:
    1. purge -> delete Lua files from cache;
    2. erase -> delete Lua and Luc files from cache;
    3. show -> print stats.

🧚 debugging methods

  • --show-blacklist, -b — shows blacklisted files (not directories).
  • --dry-run, -D — don't load fonts when updating the database; scan directories only. (for debugging file system related issues.)
  • --no-strip — do not strip redundant information after building the database. warning: this will inflate the index to about two to three times the normal size. 💀
  • --max-fonts=N — processes at most N font files, including fonts already indexed in the count.
  • --bisect=DIRECTIVE — bisection of the font database. this mode is intended as assistance in debugging the Luatex engine, especially when tracking memleaks or buggy fonts.

DIRECTIVE can be one of the following:

  1. run -> make luaotfload-tool respect the bisection progress when running. combined with --update and possibly --force, this will only process the files from the start up until the pivot and ignore the rest.
  2. start -> start bisection: create a bisection state file and initialize the low, high, and pivot indices.
  3. stop -> terminate the current bisection session by deleting the state file.
  4. good | bad -> mark the section processed last as "good" or "bad", respectively. the next bisection step will continue with the bad section.
  5. status -> print status information about the current bisection session. hint: use with higher verbosity settings for more output.

a bisection session is initiated by issuing the start directive. this sets the pivot to the middle of the list of available font files. now run luaotfload-tool with the --update flag set as well as --bisect=run: only the fonts up to the pivot will be considered. if that task exhibited the issue you are tracking, then tell Luaotfload using --bisect=bad. the next step of --bisect=run will continue bisection with the part of the files below the pivot. likewise, issue --bisect=good in order to continue with the fonts above the pivot, assuming the tested part of the list did not trigger the bug.

once the culprit font is tracked down, good or bad will have no effect anymore. run will always end up processing the single font file that was left. use --bisect=stop to clear the bisection state.

🌈 miscellaneous

  • --verbose=N, -v — set verbosity level to n, or to the number of repetitions of -v.
  • --quiet — no verbose output (log level set to zero). shhh. 🤫
  • --log=CHANNEL — redirect log output (for database troubleshooting), where CHANNEL can be
    1. stdout -> all output will be dumped to the terminal (default); or
    2. file -> write to a file to the temporary directory (the name will be chosen automatically.
  • --version, -V — show version numbers of components as well as some basic information and exit.
  • --help, -h — show help message and exit.
  • --diagnose=CHECK — run the diagnostic procedure CHECK. available procedures are:
    1. files -> check Luaotfload files for modifications;
    2. permissions -> check permissions of cache directories and files;

3.

environment -> print relevant
       environment and kpse variables;
  1. repository -> check the git repository for new releases,
  2. index -> check database, display information about it.

procedures can be chained by concatenating with commas, e.g. --diagnose=files,permissions. specify thorough to run all checks.

  • --conf=FILE — read the configuration from FILE. see luaotfload.conf(%) for documentation concerning the format and available options.
  • --dumpconf — print the currently active configuration; the output can be saved to a file and used for bootstrapping a custom configuration files.
  • --aliases — dump the font name database as a kpathsea aliases file. this option is experimental and might go away.

🍓 FILES 🍓

the font name database is usually located in the directory texmf-var/luatex-cache/generic/names/ ($TEXMFCACHE as set in texmf.cnf) of your TeX Live distribution as a zlib-compressed file luaotfload-names.lua.gz. the experimental lookup cache will be created as luaotfload-lookup-cache.lua in the same directory. these Lua tables are not used directly by Luaotfload, though. instead, they are compiled to Lua bytecode which is written to corresponding files with the extension .luc in the same directory. when modifying the files by hand, keep in mind that only if the bytecode files are missing will Luaotfload use the plain version instead. both kinds of files are safe to delete, at the cost of regenerating them with the next run of LuaTeX. 💅

✨ SEE ALSO ✨

ok so like, the whole squad of related pages, bestie:

and then the little link-dump corner, which is honestly iconic:

💀 BUGS 💀

Tons, probably.

no like genuinely. that's the whole section. that's it. it's giving "we're aware, we're all aware, moving on" energy and honestly? relatable 🙈

👑 AUTHORS 👑

Luaotfload was developed by the LuaLaTeX dev team (→ https://github.com/lualatex/). It is currently maintained by the LaTeX Project Team at https://github.com/latex3/luaotfload 💅

The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt NL (→ http://pragma-ade.com/) — king behaviour fr fr.

This manual page was written by Philipp Gesang <phg@phi-gamma.net> 🎀

GPL v2.0 — periodt.

and that's a wrap on the whole page, bestie!! every last flag, path, file, signal and footnote is in there, no cap. go forth and load them fonts. 🦋

this was LUAOTFLOAD-TOOL(1) version 3.29, dated 2024-12-03 — hope she served you well, mwah 💖

📦 where this page comes from