1LUAOTFLOAD-TOOL(1) text processing LUAOTFLOAD-TOOL(1)
2
6 luaotfload-tool - generate and query the Luaotfload font names database
7
9 luaotfload-tool [ -bcDfFiIlLnpqRSuvVhw ]
10 luaotfload-tool --update [ --force ] [ --quiet ] [ --verbose ]
12 [ --prefer-texmf ] [ --dry-run ] [ --formats=[+|-]EXTENSIONS ] [
13 --no-compress ] [ --no-strip ] [ --local ] [ --max-fonts=N ]
14 luaotfload-tool --find=FONTNAME [ --fuzzy ] [ --info ] [ --inspect ]
16 [ --no-reload ]
17 luaotfload-tool --flush-lookups
19 luaotfload-tool --cache=DIRECTIVE
21 luaotfload-tool --list=CRITERION[:VALUE] [ --fields=F1,F2,...,Fn ]
23 luaotfload-tool --bisect=DIRECTIVE
25 luaotfload-tool --help
27 luaotfload-tool --version
29 luaotfload-tool --show-blacklist
31 luaotfload-tool --diagnose=CHECK
33 luaotfload-tool --conf=FILE --dumpconf
35
37 luaotfload-tool accesses the font names database that is required by
38 the Luaotfload package. There are two general modes: update and query.
39 • update: update the database or rebuild it entirely;
41 • query: resolve a font name or display close matches.
43
45 update mode
46 --update, -u
47 Update the database; indexes new fonts.
48 --force, -f
50 Force rebuilding of the database; re-indexes all fonts.
51 --local, -L
53 Include font files in $PWD. This option will cause large parts
54 of the database to be rebuilt. Thus it is quite inefficient.
55 Additionally, if local font files are found, the database is
56 prevented from being saved to disk, so the local fonts need to
57 be parsed with every invocation of luaotfload-tool.
58 --no-reload, -n
60 Suppress auto-updates to the database (e.g. when --find is
61 passed an unknown name).
62 --no-compress, -c
64 Do not filter the plain text version of the font index through
65 gzip. Useful for debugging if your editor is built without zlib.
66 --prefer-texmf, -p
68 Organize the file name database in a way so that it prefer fonts
69 in the TEXMF tree over system fonts if they are installed in
70 both.
71 --formats=EXTENSIONS
73 Extensions of the font files to index. Where EXTENSIONS is a
74 comma-separated list of supported file extensions (otf, ttf,
75 ttc). If the list is prefixed with a + sign, the given list is
76 added to the currently active one; - subtracts. Default:
77 otf,ttf,ttc. Examples:
78 1. --formats=-ttc,ttf would skip TrueType fonts and font collec‐
80 tions;
81 2. --formats=otf would scan only OpenType files;
83 3. --formats=+afm includes binary Postscript files accompanied
85 by an AFM file.
86 query mode
88 --find=NAME
89 Resolve a font name; this looks up <name> in the database and
90 prints the file name it is mapped to. --find also understands
91 request syntax, i.e. --find=file:foo.otf checks whether foo.otf
92 is indexed.
93 --fuzzy, -F
95 Show approximate matches to the file name if the lookup was un‐
96 successful (requires --find).
97 --info, -i
99 Display basic information to a resolved font file (requires
100 --find).
101 --inspect, -I
103 Display detailed information by loading the font and analyzing
104 the font table; very slow! For the meaning of the returned
105 fields see the LuaTeX documentation. (requires --find).
106 --list=CRITERION
108 Show entries, where CRITERION is one of the following:
109 1. the character *, selecting all entries;
111 2. a field of a database entry, for instance version or format*,
113 according to which the output will be sorted. Information in
114 an unstripped database (see the option --no-strip above) is
115 nested: Subfields of a record can be addressed using the ->
116 separator, e. g. file->location, style->units_per_em, or
117 names->sanitized->english->prefmodifiers. NB: shell syntax
118 requires that arguments containing -> be properly quoted!
119 3. an expression of the form field:value to limit the output to
121 entries whose field matches value. The value can contain * to
122 match an arbitrary number of characters.
123 For example, in order to output file names and corresponding
125 versions, sorted by the font format:
126 ./luaotfload-tool.lua --list="format" --fields="file->base,version"
128 This prints:
130 otf latinmodern-math.otf Version 1.958
132 otf lmromancaps10-oblique.otf 2.004
133 otf lmmono8-regular.otf 2.004
134 otf lmmonoproplt10-bold.otf 2.004
135 otf lmsans10-oblique.otf 2.004
136 otf lmromanslant8-regular.otf 2.004
137 otf lmroman12-italic.otf 2.004
138 otf lmsansdemicond10-oblique.otf 2.004
139 ...
140 --fields=FIELDS
142 Comma-separated list of fields that should be printed. Informa‐
143 tion in an unstripped database (see the option --no-strip above)
144 is nested: Subfields of a record can be addressed using the ->
145 separator, e. g. file->location, style->units_per_em, or
146 names->sanitized->english->subfamily. The default is plain‐
147 name,version*. (Only meaningful with --list.)
148 font and lookup caches
150 --flush-lookups
151 Clear font name lookup cache (experimental).
152 --cache=DIRECTIVE
154 Cache control, where DIRECTIVE is one of the following:
155 1. purge -> delete Lua files from cache;
157 2. erase -> delete Lua and Luc files from cache;
159 3. show -> print stats.
161 debugging methods
163 --show-blacklist, -b
164 Show blacklisted files (not directories).
165 --dry-run, -D
167 Don’t load fonts when updating the database; scan directories
168 only. (For debugging file system related issues.)
169 --no-strip
171 Do not strip redundant information after building the database.
172 Warning: this will inflate the index to about two to three times
173 the normal size.
174 --max-fonts=N
176 Process at most N font files, including fonts already indexed in
177 the count.
178 --bisect=DIRECTIVE
180 Bisection of the font database. This mode is intended as as‐
181 sistance in debugging the Luatex engine, especially when track‐
182 ing memleaks or buggy fonts.
183 DIRECTIVE can be one of the following:
185 1. run -> Make luaotfload-tool respect the bisection progress
187 when running. Combined with --update and possibly --force
188 this will only process the files from the start up until the
189 pivot and ignore the rest.
190 2. start -> Start bisection: create a bisection state file and
192 initialize the low, high, and pivot indices.
193 3. stop -> Terminate the current bisection session by deleting
195 the state file.
196 4. good | bad -> Mark the section processed last as “good” or
198 “bad”, respectively. The next bisection step will continue
199 with the bad section.
200 5. status -> Print status information about the current bisec‐
202 tion session. Hint: Use with higher verbosity settings for
203 more output.
204 A bisection session is initiated by issuing the start directive.
206 This sets the pivot to the middle of the list of available font
207 files. Now run luaotfload-tool with the --update flag set as
208 well as --bisect=run: only the fonts up to the pivot will be
209 considered. If that task exhibited the issue you are tracking,
210 then tell Luaotfload using --bisect=bad. The next step of --bi‐
211 sect=run will continue bisection with the part of the files be‐
212 low the pivot. Likewise, issue --bisect=good in order to con‐
213 tinue with the fonts above the pivot, assuming the tested part
214 of the list did not trigger the bug.
215 Once the culprit font is tracked down, good or bad will have no
217 effect anymore. run will always end up processing the single
218 font file that was left. Use --bisect=stop to clear the bisec‐
219 tion state.
220 miscellaneous
222 --verbose=N, -v
223 Set verbosity level to n or the number of repetitions of -v.
224 --quiet
226 No verbose output (log level set to zero).
227 --log=CHANNEL
229 Redirect log output (for database troubleshooting), where CHAN‐
230 NEL can be
231 1. stdout -> all output will be dumped to the terminal (de‐
233 fault); or
234 2. file -> write to a file to the temporary directory (the name
236 will be chosen automatically.
237 --version, -V
239 Show version numbers of components as well as some basic infor‐
240 mation and exit.
241 --help, -h
243 Show help message and exit.
244 --diagnose=CHECK
246 Run the diagnostic procedure CHECK. Available procedures are:
247 1. files -> check Luaotfload files for modifications;
249 2. permissions -> check permissions of cache directories and
251 files;
252 3.
254 environment -> print relevant
256 environment and kpse variables;
257 4. repository -> check the git repository for new releases,
259 5. index -> check database, display information about it.
261 Procedures can be chained by concatenating with commas, e.g.
263 --diagnose=files,permissions. Specify thorough to run all
264 checks.
265 --conf=FILE
267 Read the configuration from FILE. See luaotfload.conf(%) for
268 documentation concerning the format and available options.
269 --dumpconf
271 Print the currently active configuration; the output can be
272 saved to a file and used for bootstrapping a custom configura‐
273 tion files.
274
276 The font name database is usually located in the directory
277 texmf-var/luatex-cache/generic/names/ ($TEXMFCACHE as set in texmf.cnf)
278 of your TeX Live distribution as a zlib-compressed file luaot‐
279 fload-names.lua.gz. The experimental lookup cache will be created as
280 luaotfload-lookup-cache.lua in the same directory. These Lua tables
281 are not used directly by Luaotfload, though. Instead, they are com‐
282 piled to Lua bytecode which is written to corresponding files with the
283 extension .luc in the same directory. When modifying the files by hand
284 keep in mind that only if the bytecode files are missing will Luaot‐
285 fload use the plain version instead. Both kinds of files are safe to
286 delete, at the cost of regenerating them with the next run of LuaTeX.
287
289 luaotfload.conf(5), luatex(1), lua(1)
290 • texdoc luaotfload to display the manual for the Luaotfload package
292 • Luaotfload development https://github.com/latex3/luaotfload
294 • LuaLaTeX mailing list http://tug.org/pipermail/lualatex-dev/
296 • LuaTeX http://luatex.org/
298 • ConTeXt http://wiki.contextgarden.net
300 • Luaotfload on CTAN http://ctan.org/pkg/luaotfload
302
304 Tons, probably.
305
307 Luaotfload was developed by the LuaLaTeX dev team (‐
308 https://github.com/lualatex/). It is currently maintained by the LaTeX
309 Project Team at https://github.com/latex3/luaotfload The fontloader
310 code is provided by Hans Hagen of Pragma ADE, Hasselt NL (‐
311 http://pragma-ade.com/).
312 This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
314
316 GPL v2.0
3173.17 2021-01-08 LUAOTFLOAD-TOOL(1)