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
96 unsuccessful (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.
122 For example, in order to output file names and corresponding
124 versions, sorted by the font format:
125 ./luaotfload-tool.lua --list="format" --fields="file->base,version"
127 This prints:
129 otf latinmodern-math.otf Version 1.958
131 otf lmromancaps10-oblique.otf 2.004
132 otf lmmono8-regular.otf 2.004
133 otf lmmonoproplt10-bold.otf 2.004
134 otf lmsans10-oblique.otf 2.004
135 otf lmromanslant8-regular.otf 2.004
136 otf lmroman12-italic.otf 2.004
137 otf lmsansdemicond10-oblique.otf 2.004
138 ...
139 --fields=FIELDS
141 Comma-separated list of fields that should be printed. Informa‐
142 tion in an unstripped database (see the option --no-strip above)
143 is nested: Subfields of a record can be addressed using the ->
144 separator, e. g. file->location, style->units_per_em, or
145 names->sanitized->english->subfamily. The default is plain‐
146 name,version*. (Only meaningful with --list.)
147 font and lookup caches
149 --flush-lookups
150 Clear font name lookup cache (experimental).
151 --cache=DIRECTIVE
153 Cache control, where DIRECTIVE is one of the following:
154 1. purge -> delete Lua files from cache;
156 2. erase -> delete Lua and Luc files from cache;
158 3. show -> print stats.
160 debugging methods
162 --show-blacklist, -b
163 Show blacklisted files (not directories).
164 --dry-run, -D
166 Don’t load fonts when updating the database; scan directories
167 only. (For debugging file system related issues.)
168 --no-strip
170 Do not strip redundant information after building the database.
171 Warning: this will inflate the index to about two to three times
172 the normal size.
173 --max-fonts=N
175 Process at most N font files, including fonts already indexed in
176 the count.
177 --bisect=DIRECTIVE
179 Bisection of the font database. This mode is intended as assis‐
180 tance in debugging the Luatex engine, especially when tracking
181 memleaks or buggy fonts.
182 DIRECTIVE can be one of the following:
184 1. run -> Make luaotfload-tool respect the bisection progress
186 when running. Combined with --update and possibly --force
187 this will only process the files from the start up until the
188 pivot and ignore the rest.
189 2. start -> Start bisection: create a bisection state file and
191 initialize the low, high, and pivot indices.
192 3. stop -> Terminate the current bisection session by deleting
194 the state file.
195 4. good | bad -> Mark the section processed last as “good” or
197 “bad”, respectively. The next bisection step will continue
198 with the bad section.
199 5. status -> Print status information about the current bisec‐
201 tion session. Hint: Use with higher verbosity settings for
202 more output.
203 A bisection session is initiated by issuing the start directive.
205 This sets the pivot to the middle of the list of available font
206 files. Now run luaotfload-tool with the --update flag set as
207 well as --bisect=run: only the fonts up to the pivot will be
208 considered. If that task exhibited the issue you are tracking,
209 then tell Luaotfload using --bisect=bad. The next step of
210 --bisect=run will continue bisection with the part of the files
211 below the pivot. Likewise, issue --bisect=good in order to con‐
212 tinue with the fonts above the pivot, assuming the tested part
213 of the list did not trigger the bug.
214 Once the culprit font is tracked down, good or bad will have no
216 effect anymore. run will always end up processing the single
217 font file that was left. Use --bisect=stop to clear the bisec‐
218 tion state.
219 miscellaneous
221 --verbose=N, -v
222 Set verbosity level to n or the number of repetitions of -v.
223 --quiet
225 No verbose output (log level set to zero).
226 --log=CHANNEL
228 Redirect log output (for database troubleshooting), where CHAN‐
229 NEL can be
230 1. stdout -> all output will be dumped to the terminal
232 (default); or
233 2. file -> write to a file to the temporary directory (the name
235 will be chosen automatically.
236 --version, -V
238 Show version numbers of components as well as some basic infor‐
239 mation and exit.
240 --help, -h
242 Show help message and exit.
243 --diagnose=CHECK
245 Run the diagnostic procedure CHECK. Available procedures are:
246 1. files -> check Luaotfload files for modifications;
248 2. permissions -> check permissions of cache directories and
250 files;
251 3.
253 environment -> print relevant
255 environment and kpse variables;
256 4. repository -> check the git repository for new releases,
258 5. index -> check database, display information about it.
260 Procedures can be chained by concatenating with commas, e.g.
262 --diagnose=files,permissions. Specify thorough to run all
263 checks.
264 --conf=FILE
266 Read the configuration from FILE. See luaotfload.conf(%) for
267 documentation concerning the format and available options.
268 --dumpconf
270 Print the currently active configuration; the output can be
271 saved to a file and used for bootstrapping a custom configura‐
272 tion files.
273
275 The font name database is usually located in the directory
276 texmf-var/luatex-cache/generic/names/ ($TEXMFCACHE as set in texmf.cnf)
277 of your TeX Live distribution as a zlib-compressed file luaot‐
278 fload-names.lua.gz. The experimental lookup cache will be created as
279 luaotfload-lookup-cache.lua in the same directory. These Lua tables
280 are not used directly by Luaotfload, though. Instead, they are com‐
281 piled to Lua bytecode which is written to corresponding files with the
282 extension .luc in the same directory. When modifying the files by hand
283 keep in mind that only if the bytecode files are missing will Luaot‐
284 fload use the plain version instead. Both kinds of files are safe to
285 delete, at the cost of regenerating them with the next run of LuaTeX.
286
288 luaotfload.conf(5), luatex(1), lua(1)
289 · texdoc luaotfload to display the manual for the Luaotfload package
291 · Luaotfload development https://github.com/lualatex/luaotfload
293 · LuaLaTeX mailing list http://tug.org/pipermail/lualatex-dev/
295 · LuaTeX http://luatex.org/
297 · ConTeXt http://wiki.contextgarden.net
299 · Luaotfload on CTAN http://ctan.org/pkg/luaotfload
301
303 Tons, probably.
304
306 Luaotfload was developed by the LuaLaTeX dev team (‐
307 https://github.com/lualatex/). It is currently maintained by Ulrike
308 Fischer and Marcel Krüger at https://github.com/u-fischer/luaotfload
309 The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt NL
310 (http://pragma-ade.com/).
311 This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
313
315 GPL v2.0
3162.97 2019-05-18 LUAOTFLOAD-TOOL(1)