summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/fmtutil.1
blob: cabf6638349f61082172539264a4aa431532e3fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.48.2.
.TH FMTUTIL "1" "May 2021" "TeX Live" "User Commands"
.SH NAME
fmtutil \- manage TeX formats and Metafont bases, per-user
.br
fmtutil-sys \- manage TeX formats and Metafont bases, system-wide
.br
mktexfmt \- create a TeX format or Metafont base
.SH SYNOPSIS
.B fmtutil
[\fI\,-user|-sys\/\fR] [\fI\,OPTION\/\fR] ... [\fI\,COMMAND\/\fR]
.br
.B fmtutil-sys
[\fI\,OPTION\/\fR] ... [\fI\,COMMAND\/\fR]
.br
.B fmtutil-user
[\fI\,OPTION\/\fR] ... [\fI\,COMMAND\/\fR]
.br
.B mktexfmt
\fI\,FORMAT.fmt|BASE.base|FMTNAME\/\fR
.SH DESCRIPTION
fmtutil version r58961 (2021\-04\-22 02:55:07 +0200)
.PP
Rebuild and manage TeX fmts and Metafont bases, collectively called
"formats" here. (MetaPost no longer uses the past\-equivalent "mems".)
.PP
If not operating in mktexfmt mode, exactly one command must be given,
filename suffixes should generally not be specified, no non\-option
arguments are allowed, and multiple formats can be generated.
.PP
If the command name ends in mktexfmt, only one format can be created.
The only options supported are \fB\-\-help\fR and \fB\-\-version\fR, and the command
line must be either a format name, with extension, or a plain name that
is passed as the argument to \fB\-\-byfmt\fR (see below).  The full name of the
generated file (if any) is written to stdout, and nothing else.  The
system directories are used if they are writable, else the user directories.
.PP
By default, the return status is zero if all formats requested are
successfully built, else nonzero.
.SH OPTIONS
.TP
\fB\-\-sys\fR
use TEXMFSYS{VAR,CONFIG}
.TP
\fB\-\-user\fR
use TEXMF{VAR,CONFIG}
.TP
\fB\-\-cnffile\fR FILE
read FILE instead of fmtutil.cnf
(can be given multiple times, in which case
all the files are used)
.TP
\fB\-\-dry\-run\fR, \fB\-n\fR
don't actually build formts
.TP
\fB\-\-fmtdir\fR DIR
write formats under DIR instead of TEXMF[SYS]VAR
.TP
\fB\-\-no\-engine\-subdir\fR
don't use engine\-specific subdir of the fmtdir
.TP
\fB\-\-no\-error\-if\-no\-format\fR
exit successfully if no format is selected
.TP
\fB\-\-no\-error\-if\-no\-engine\fR=\fI\,ENGINE1\/\fR,ENGINE2,...
exit successfully even if a required ENGINE
.IP
is missing, if it is included in the list.
.TP
\fB\-\-no\-strict\fR
exit successfully even if a format fails to build
.TP
\fB\-\-nohash\fR
don't update ls\-R files
.TP
\fB\-\-recorder\fR
pass the \fB\-recorder\fR option and save .fls files
.TP
\fB\-\-refresh\fR
recreate only existing format files
.TP
\fB\-\-status\-file\fR FILE
append status information about built formats to FILE
.TP
\fB\-\-quiet\fR
be silent
.TP
\fB\-\-catcfg\fR
(does nothing, exists for compatibility)
.TP
\fB\-\-dolinks\fR
(does nothing, exists for compatibility)
.TP
\fB\-\-force\fR
(does nothing, exists for compatibility)
.TP
\fB\-\-test\fR
(does nothing, exists for compatibility)
.SS "Commands:"
.TP
\fB\-\-all\fR
recreate all format files
.TP
\fB\-\-missing\fR
create all missing format files
.TP
\fB\-\-byengine\fR ENGINE
(re)create formats built with ENGINE
.TP
\fB\-\-byfmt\fR FORMAT
(re)create format FORMAT
.TP
\fB\-\-byhyphen\fR HYPHENFILE
(re)create formats that depend on HYPHENFILE
.TP
\fB\-\-enablefmt\fR
FORMAT[/ENGINE]  enable FORMAT, as built with ENGINE
.TP
\fB\-\-disablefmt\fR FORMAT[/ENGINE]
disable FORMAT, as built with ENGINE
If multiple formats have the same name and
.IP
different engines, \fI\,/ENGINE\/\fP specifier is required.
.TP
\fB\-\-listcfg\fR
list (enabled and disabled) configurations,
filtered to available formats
.TP
\fB\-\-showhyphen\fR FORMAT
print name of hyphen file for FORMAT
.TP
\fB\-\-version\fR
show version information and exit
.TP
\fB\-\-help\fR
show this message and exit
.SH ENVIRONMENT
.PP
Explanation of trees and files normally used:
.IP
If \fB\-\-cnffile\fR is specified on the command line (possibly multiple
times), its value(s) are used.  Otherwise, fmtutil reads all the
fmtutil.cnf files found by running "kpsewhich \fB\-all\fR fmtutil.cnf", in the
order returned by kpsewhich.  Files specified via \fB\-\-cnffile\fR are
first tried to be loaded directly, and if not found and the file names
don't contain directory parts, are searched via kpsewhich.
.IP
In any case, if multiple fmtutil.cnf files are found, all the format
definitions found in all the fmtutil.cnf files are merged.
.IP
Thus, if fmtutil.cnf files are present in all trees, and the default
layout is used as shipped with TeX Live, the following files are
read, in the given order.
.nf
.IP
For fmtutil\-sys:
TEXMFSYSCONFIG \fI\,$TEXLIVE/YYYY/texmf\-config/web2c/fmtutil.cnf\/\fP
TEXMFSYSVAR    \fI\,$TEXLIVE/YYYY/texmf\-var/web2c/fmtutil.cnf\/\fP
TEXMFLOCAL     \fI\,$TEXLIVE/texmf\-local/web2c/fmtutil.cnf\/\fP
TEXMFDIST      \fI\,$TEXLIVE/YYYY/texmf\-dist/web2c/fmtutil.cnf\/\fP
.IP
For fmtutil\-user:
TEXMFCONFIG    $HOME/.texliveYYYY/texmf\-config/web2c/fmtutil.cnf
TEXMFVAR       $HOME/.texliveYYYY/texmf\-var/web2c/fmtutil.cnf
TEXMFHOME      \fI\,$HOME/texmf/web2c/fmtutil.cnf\/\fP
TEXMFSYSCONFIG \fI\,$TEXLIVE/YYYY/texmf\-config/web2c/fmtutil.cnf\/\fP
TEXMFSYSVAR    \fI\,$TEXLIVE/YYYY/texmf\-var/web2c/fmtutil.cnf\/\fP
TEXMFLOCAL     \fI\,$TEXLIVE/texmf\-local/web2c/fmtutil.cnf\/\fP
TEXMFDIST      \fI\,$TEXLIVE/YYYY/texmf\-dist/web2c/fmtutil.cnf\/\fP
.IP
(where YYYY is the TeX Live release version).
.fi
.IP
According to the actions, fmtutil might update one of the existing cnf
files or create a new fmtutil.cnf, as described below.
.PP
Where format files are written:
.IP
By default, format files are (re)written in \fI\,$TEXMFSYSVAR/ENGINE\/\fP by
fmtutil\-sys, and \fI\,$TEXMFVAR/ENGINE\/\fP by fmtutil\-user, where \fI\,/ENGINE\/\fP is
a subdirectory named for the engine used, such as "pdftex".
.IP
For mktexfmt, TEXMFSYSVAR is used if it is writable, else TEXMFVAR.
.IP
If the \fB\-\-fmtdir\fR=\fI\,DIR\/\fR option is specified, DIR is used instead of
TEXMF[SYS]VAR, but the \fI\,/ENGINE\/\fP subdir is still used by default.
.IP
In all cases, if the \fB\-\-no\-engine\-subdir\fR option is specified, the
\fI\,/ENGINE\/\fP subdir is omitted.
.PP
Where configuration changes are saved:
.IP
If config files are given on the command line, then the first one
given will be used to save any changes from \fB\-\-enable\fR or \fB\-\-disable\fR.
.IP
If the config files are taken from kpsewhich output, then the
algorithm is more complicated:
.IP
1) If \fI\,$TEXMFCONFIG/web2c/fmtutil.cnf\/\fP or \fI\,$TEXMFHOME/web2c/fmtutil.cnf\/\fP
appears in the list of used files, then the one listed first by
kpsewhich \fB\-\-all\fR (equivalently, the one returned by
"kpsewhich fmtutil.cnf"), is used.
.IP
2) If neither of the above two are present and changes are made, a
new config file is created in \fI\,$TEXMFCONFIG/web2c/fmtutil.cnf\/\fP.
.IP
In general, the idea is that if a given config file is not writable, a
higher\-level one can be used.  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.
.PP
Resolving multiple definitions of a format:
.IP
If a format is defined in more than one config file, then the definition
coming from the first\-listed fmtutil.cnf is used.
.PP
Disabling formats:
.IP
fmtutil.cnf files with higher priority (listed earlier) can disable
formats in lower priority (listed later) fmtutil.cnf files by
writing a line like this in the higher\-priority fmtutil.cnf file:
.IP
#! <fmtname> <enginename> <hyphen> <args>
.IP
The #! must be at the beginning of the line, with at least one space
or tab afterward, and there must be whitespace between each word on
the list.
.IP
For example, you can disable the luajitlatex format by creating
the file \fI\,$TEXMFCONFIG/web2c/fmtutil.cnf\/\fP with the line
.IP
#! luajitlatex luajittex language.dat,language.dat.lua lualatex.ini
.IP
(As it happens, the luajittex\-related formats are precisely why the
\fB\-\-no\-error\-if\-no\-engine\fR option exists, since luajittex cannot be
compiled on all platforms. So this is not needed.)
.PP
fmtutil\-user (fmtutil \fB\-user\fR) vs. fmtutil\-sys (fmtutil \fB\-sys\fR):
.IP
When fmtutil\-sys is run or the command line option \fB\-sys\fR is used,
TEXMFSYSCONFIG and TEXMFSYSVAR are used instead of TEXMFCONFIG and
TEXMFVAR, respectively. This is the primary difference between
fmtutil\-sys and fmtutil\-user.
.IP
See https://tug.org/texlive/scripts\-sys\-user.html for details.
.IP
Other locations may be used if you give them on the command line, or
these trees don't exist, or you are not using the original TeX Live.
.PP
Supporting development binaries:
.IP
If an engine name ends with "\-dev", formats are created in
the respective directory with the \fB\-dev\fR stripped.  This allows for
easily running development binaries in parallel with the released
binaries.
.SH "REPORTING BUGS"
Report bugs to: tex\-live@tug.org
.br
TeX Live home page: <https://tug.org/texlive/>