FMTUTIL(1)

💖 NAME 💖

okay bestie, this is the FMTUTIL(1) page from the User Commands section 🧚 it covers three names that all do format stuff ✨

• fmtutil — manage TeX formats and Metafont bases, per-user 🫶
• fmtutil-sys — manage TeX formats and Metafont bases, system-wide 🌈
• mktexfmt — create a TeX format or Metafont base 🦋

---

🎀 SYNOPSIS 🎀

fmtutil [-user|-sys] [OPTION] ... [COMMAND]
fmtutil-sys [OPTION] ... [COMMAND]
fmtutil-user [OPTION] ... [COMMAND]
mktexfmt FORMAT.fmt|BASE.base|FMTNAME

---

📖 DESCRIPTION 📖

okay so the version here is fmtutil version r68962 (2023-11-25 00:01:43 +0100) 💅

This tool rebuilds and manages TeX fmts and Metafont bases. we call them all "formats" here, no cap 💜 (MetaPost doesn't use the old "mems" anymore, that's so last season 🙈)

If you're not in mktexfmt mode, you need exactly one command. filename suffixes should generally be left off, no non-option arguments are allowed, and you're allowed to generate multiple formats at once ✨

If the command name ends in mktexfmt, only one format can be created 🍓 The only options it supports are --help and --version. Your command line has to be either a format name with its extension, or a plain name that gets passed as the argument to --byfmt (more on that below). The full name of the generated file (if any) gets written to stdout, and nothing else 🫶 It uses the system directories if they're writable, otherwise the user directories.

By default, the return status is zero if every requested format builds successfully, and nonzero if not 🥺

---

🌸 OPTIONS 🌸

• --sys — use TEXMFSYS{VAR,CONFIG} 🌈
• --user — use TEXMF{VAR,CONFIG} 💖
• --cnffile FILE — read FILE instead of fmtutil.cnf. you can give it multiple times, and then all the files get used 🧚
• --dry-run, -n — don't actually build the formats 🙈
• --fmtdir DIR — write formats under DIR instead of TEXMF[SYS]VAR 🦋
• --no-engine-subdir — don't use the engine-specific subdir of the fmtdir 💅
• --no-error-if-no-format — exit successfully if no format is selected 🫶
• --no-error-if-no-engine=ENGINE1,ENGINE2,... — exit successfully even if a required ENGINE is missing, as long as it's in the list ✨
• --no-strict — exit successfully even if a format fails to build 🌸
• --nohash — don't update ls-R files 🍓
• --recorder — pass the -recorder option and save .fls files 📝
• --refresh — only recreate format files that already exist 🔄
• --status-file FILE — append status info about built formats to FILE 💜
• --quiet — be silent 🤫
• --catcfg — (does nothing, only here for compatibility) 🫠
• --dolinks — (does nothing, only here for compatibility) 🫠
• --force — (does nothing, only here for compatibility) 🫠
• --test — (does nothing, only here for compatibility) 🫠
• --version — show version info and exit 👑
• --help — show this message and exit 💖

💅 Commands (exactly one must be specified): 💅

• --all — recreate all format files 🔥
• --missing — create all the missing format files 🌈
• --byengine ENGINE — (re)create formats built with ENGINE ✨
• --byfmt FORMAT — (re)create format FORMAT 🦋
• --byhyphen HYPHENFILE — (re)create formats that depend on HYPHENFILE 🧚
• --enablefmt FORMAT[/ENGINE] — enable FORMAT, as built with ENGINE 💖
• --disablefmt FORMAT[/ENGINE] — disable FORMAT, as built with ENGINE. if multiple formats share the same name but use different engines, you need the /ENGINE specifier 🙈
• --listcfg — list the (enabled and disabled) configurations, filtered down to the formats that are actually available 📝
• --showhyphen FORMAT — print the name of the hyphen file for FORMAT 🍓

---

🌍 ENVIRONMENT 🌍

🗺️ Explanation of trees and files normally used: 🗺️

okay so if you pass --cnffile on the command line (once or several times), those values are what get used. otherwise, fmtutil reads every fmtutil.cnf file that kpsewhich -all fmtutil.cnf finds, in whatever order kpsewhich returns them 🧚 Files given through --cnffile get loaded directly first, and if they aren't found and their names don't include directory parts, they get searched for via kpsewhich 💅

Either way, if there are multiple fmtutil.cnf files, all the format definitions from all of them get merged 🫶

So if fmtutil.cnf files exist in every tree and you're using the default layout that ships with TeX Live, these are read, in this order:

For fmtutil-sys:

TEXMFSYSCONFIG $TEXLIVE/YYYY/texmf-config/web2c/fmtutil.cnf
TEXMFSYSVAR    $TEXLIVE/YYYY/texmf-var/web2c/fmtutil.cnf
TEXMFLOCAL     $TEXLIVE/texmf-local/web2c/fmtutil.cnf
TEXMFDIST      $TEXLIVE/YYYY/texmf-dist/web2c/fmtutil.cnf

For fmtutil-user:

TEXMFCONFIG    $HOME/.texliveYYYY/texmf-config/web2c/fmtutil.cnf
TEXMFVAR       $HOME/.texliveYYYY/texmf-var/web2c/fmtutil.cnf
TEXMFHOME      $HOME/texmf/web2c/fmtutil.cnf
TEXMFSYSCONFIG $TEXLIVE/YYYY/texmf-config/web2c/fmtutil.cnf
TEXMFSYSVAR    $TEXLIVE/YYYY/texmf-var/web2c/fmtutil.cnf
TEXMFLOCAL     $TEXLIVE/texmf-local/web2c/fmtutil.cnf
TEXMFDIST      $TEXLIVE/YYYY/texmf-dist/web2c/fmtutil.cnf

(where YYYY is the TeX Live release version 🌸)

depending on the action, fmtutil might update one of the existing cnf files or make a brand new fmtutil.cnf, as described below ✨

📂 Where format files are written: 📂

by default, format files get (re)written in $TEXMFSYSVAR/ENGINE by fmtutil-sys, and in $TEXMFVAR/ENGINE by fmtutil-user. the /ENGINE part is a subdirectory named after the engine used, like pdftex 🦋

for mktexfmt, TEXMFSYSVAR gets used if it's writable, otherwise TEXMFVAR 🧚

if you pass --fmtdir=DIR, then DIR is used instead of TEXMF[SYS]VAR, but the /ENGINE subdir still gets used by default 💅

in every case, if you pass --no-engine-subdir, the /ENGINE subdir gets left out 🙈

💾 Where configuration changes are saved: 💾

if config files are given on the command line, the first one given is where any changes from --enable or --disable get saved 🫶

if the config files come from kpsewhich output, it gets a little more complicated 🥺

1. if $TEXMFCONFIG/web2c/fmtutil.cnf or $TEXMFHOME/web2c/fmtutil.cnf shows up in the list of used files, then the one listed first by kpsewhich --all (aka the one returned by "kpsewhich fmtutil.cnf") gets used 💖
2. if neither of those is present and changes are made, a new config file gets created at $TEXMFCONFIG/web2c/fmtutil.cnf ✨

the big idea is this: if a config file isn't writable, a higher-level one can be used instead 🌈 That way the distribution's settings can be overridden system-wide using TEXMFLOCAL, and system settings can be overridden again in a particular user's TEXMFHOME or TEXMFCONF 👑

🥇 Resolving multiple definitions of a format: 🥇

if a format is defined in more than one config file, the definition from the first-listed fmtutil.cnf wins 🔥

🚫 Disabling formats: 🚫

fmtutil.cnf files with higher priority (listed earlier) can disable formats in lower-priority (listed later) fmtutil.cnf files. to do it, write a line like this in the higher-priority file:

#! <fmtname> <enginename> <hyphen> <args>

the #! has to be at the very start of the line, with at least one space or tab after it, and there has to be whitespace between each word in the list 🧚

for example, you can disable the luajitlatex format by creating $TEXMFCONFIG/web2c/fmtutil.cnf with this line:

#! luajitlatex luajittex language.dat,language.dat.lua lualatex.ini

(ngl the luajittex formats are exactly why --no-error-if-no-engine exists, since luajittex can't be compiled everywhere. so you don't need the line above 🙈)

👯 fmtutil-user (fmtutil -user) vs. fmtutil-sys (fmtutil -sys): 👯

when fmtutil-sys runs, or you use the -sys option, TEXMFSYSCONFIG and TEXMFSYSVAR get used instead of TEXMFCONFIG and TEXMFVAR. that's the main difference between fmtutil-sys and fmtutil-user 💅

check https://tug.org/texlive/scripts-sys-user.html for the deets 🔗

other locations might get used if you pass them on the command line, if these trees don't exist, or if you aren't using the original TeX Live 🌸

🛠️ Supporting development binaries: 🛠️

if an engine name ends in -dev, formats get created in the matching directory with the -dev stripped off. this means you can run development binaries side by side with the released ones 🔥

---

🌍 ENVIRONMENT 🌍

this script runs TeX and Metafont to generate the fmt/base file, so all the normal environment variables and search path rules for TeX/MF apply 🫶

---

🐛 REPORTING BUGS 🐛

report bugs to: tex-live@tug.org 💌 TeX Live home page: <https://tug.org/texlive/> 🏠

---

Bye bestie! This was the TeX Live February 2024 build of FMTUTIL(1) 🦋💖✨