root ﬁlename. This is the base name for the main te xﬁ le.
source ﬁle (e.g., the name of the dvi ﬁle when con verting a dvi ﬁle to ps).
The name of the primary texﬁ ﬁ le.
Name of directory for auxiliary output ﬁles (see the conﬁguration v ariable$aux_dir). A directory
separation character ('/') is appended if$aux_diris non-empty and does not end in a suitable char-
acter, with suitable characters being those appropriate to UNIX and MS-Windows, i.e., ':', '/' and
Name of directory for output ﬁles (see the conﬁguration v ariable$out_dir). A directory separation
character ('/') is appended if$out_diris non-empty and does not end in a suitable character, with
suitable characters being those appropriate to UNIX and MS-Windows, i.e., ':', '/' and '\'.
If for some reason you need a literal % character in your string not subject to the above rules, use a pair of
these characters. Thus with the command speciﬁcation $ps_pre viewer = 'latex -ad=%%Sﬁle.ad %S', the
%%S will become %S when the command is executed, but the %S will be replaced by the source ﬁlename,
which in this case would be the name of a postscript ﬁle to be viewed.
Appropriate quoting will be applied to the ﬁlename substitutions, so you mustn' tsupply them yourself even
if the names of your ﬁles ha ve spaces in them. (But if your TeX ﬁlenames ha ve spaces in them, beware that
manyversions of the TeX program cannot correctly handle ﬁlenames containing spaces.) In case late xmk's
quoting does not work correctly on your system, you can turn it off -- see the documentation for the vari-
The distinction between %B and %R needs a bit of care, since they are often the same, but not always. For
example on a simple document, the basename of a bibtex run is the same as for the texﬁle. But in a docu-
ment with several bibliographies, the bibliography ﬁ ﬁ les will have a variety of names. Since bibtex is
invokedwith the basename of the bibliographyﬁ ﬁ le, the setting for the bibtexcommand should therefore be
$bibtex= 'bibtex%O %B';
Generally, you should use %B rather than %R. Similarly for most purposes, the name %T of the primary
texﬁle is not a useful placeholder.
See the default values in the section "List of conﬁguration v ariables usable in initialization ﬁles" for what is
normally the most appropriate usage.
If you omit to supply any placeholders whatever in the speciﬁcation of a command, , latexmk will supply
what its author thinks are appropriate defaults. This gives compatibility with conﬁguration ﬁles for pre vi-
ous versions oflatexmk, which didn'tuse placeholders.
"Detaching" a command:Normally whenlatexmkruns a command, it waits for the command to run to
completion. This is appropriate for commands like latex, of course. But for previewers, the command
should normally run detached, so thatlatexmk gets the previewer running and then returns to its next task
(or exits if there is nothing else to do). To achieve this effect of detaching a command, you need to precede
the command name with "start ", as in
$dvi_previewer = 'start xdvi %O %S';
This will be translated to whatever is appropriate for your operating system.
Notes: (1) In some circumstances,latexmk will always run a command detached. This is the case for a pre-
viewer in preview continuous mode, since otherwise previewing continuously makes no sense. (2) This
precludes the possibility of running a command named start. (3) If the word start occurs more than once at
the beginning of the command string, that is equivalent to having just one. (4) Under cygwin, some com-
plications happen, since cygwin amounts to a complicated merging of UNIX and MS-Windows. See the
source code for howI'v ehandled the problem.
Command names containing spaces:Under MS-Windows it is common that the name of a command
24 February 2016
includes spaces, since software is often installed in a subdirectory of "C:\Program Files". Such command
names should be enclosed in double quotes, as in
$lpr_pdf = '"c:/Program Files/Ghostgum/gsview/gsview32.exe"/p%S';
$pdf_previewer = 'start "c:/Program Files/SumatraPDF/SumatraPDF.exe" %O %S';
$pdf_previewer = 'start "c:/Program Files/SumatraPDF (x86)/SumatraPDF.exe" %O %S';
(Note about the above example: Forward slashes are equivalent to backslashes in ﬁlenames under MS-W in-
dows, provided that the ﬁlename is inside double quotes. It is easier to use forward slashes in examples like
the one above, since then one does not have to worry about the rules for dealing with forward slashes in
strings in the Perl language.)
Command names under Cygwin:Iflatexmk is executed by Cygwin'sPerl, , be particularly certain that
pathnames in commands haveforward slashesnot the usual backslashes for the separator of pathname
components. See the above examples. Backslashes often get misinterpreted by the Unix shell used by
Cygwin's Perl to execute external commands. Forward slashes don't suffer from this problem, and (when
quoted, as above) are equally acceptable to MS-Windows.
Using MS-Windows ﬁle associations: A useful trick under modern versions of MS-Windows (e.g.,
WinXP) is to use just the command 'start' by itself:
$dvi_previewer = 'start %S';
Under recent versions of MS-Windows, this will cause to be run whatever program the system has associ-
ated with dvi ﬁles. (The same applies for a postscript vie wer and a pdf viewer.) Butnote that this trick is
not always suitable for the pdf previwer, if your system has acroread for the default pdf viewer. As
explained elsewhere, acroread under MS-Windows does not work well withlatex andlatexmk, because
acroread locks the pdf ﬁle.
Not using a certain command:Ifacommand is not to be run, the command name NONE is used, as in
$lpr = 'NONE lpr';
This typically is used when an appropriate command does not exist on your system. The string after the
"NONE" is effectively a comment.
Options to commands:Setting the name of a command can be used not only for changing the name of the
command called, but also to add options to command. Suppose you wantlatexmk to use latex with source
specials enabled. Then you might use the following line in an initialization ﬁle:
$latex= 'latex--src-specials %O %S';
Running a subroutine instead of an external command:Use a speciﬁcation starting with "internal", as in
$latex= 'internal mylatex%O %S';
my @args = @_;
#Possible preprocessing here
return system 'latex', @args;
For some of the more exotic possibilities that then become available, see the section "ADVANCED CON-
FIGURATION: Some extra resources and advanced tricks". Also see some of the examples in the directory
example_rcﬁles in the latexmkdistribution.
Advanced tricks:Normally one speciﬁes a single command for the commands in n vokedbylatexmk. Natu-
rally, if there is some complicated additional processing you need to do in your special situation, you can
write a script (or batch ﬁle) to do the processing, and then conﬁgure
latexmkto use your script in place of
24 February 2016
the standard program.
You can also use a Perl subroutine instead of a script -- see above. This is generally the most ﬂexible and
It is also possible to conﬁgure e latexmk to run multiple commands. For example, if when running pdﬂate x
to generate a pdf ﬁle from a te x ﬁ ﬁ le you need to run another program after pdﬂate x toperform some extra
processing, you could do something like:
$pdﬂate x= 'pdﬂate x--shell-escape %O %S; pst2pdf_for_latexmk %B';
This deﬁnition assumes you are using a UNIX-lik e system (which includes Linux and OS-X), so that the
twocommands to be run are separated by the semicolon in the middle of the string.
If you are using MS-Windows, you would replace the above line by
$pdﬂate x= 'cmd /c pdﬂate x--shell-escape %O %S'
.'&& pst2pdf_for_latexmk %B';
Here, the UNIX command separator ; is replaced by &&. In addition, there is a problem that some versions
ofPerlon MS-Windows do not obeythe command separator; this problem is overcome by explicitly invok-
ing the MS-Windows command-line processorcmd.exe.
LIST OF CONFIGURATION VARIABLES USABLE IN INITIALIZATION FILES
Default values are indicated in brackets.
Whether ps and pdf ﬁles are initially to be made in a temporary directory and then mo ved to the
ﬁnal location. (This applies to dvips, dvipdf, and ps2pdf operations, and the ﬁltering operators on
dvi and ps ﬁles. It does not apply to pdﬂatex, unfortunately.)
This use of a temporary ﬁle solves a problem that the making of these ﬁles can occup y a substan-
tial time. If a viewer sees that the ﬁle has changed, it reads the ne w ﬁ ﬁ le, and this can cause havoc
if the program writing the ﬁle has not yet ﬁnished its work.
See the$pvc_view_ﬁle_via_temporary variable for a setting that applies only if preview-continu-
ous mode (-pvc option) is used. See$tmpdirfor the setting of the directory where the temporary
ﬁle is created.
Whether to automatically read the standard initialization (rc) ﬁles, which are the system RC ﬁle,
the user's RCﬁ ﬁ le, and the RC ﬁle in the current directory . The command line option-norc can be
used to turn this setting off. Each RC ﬁle could also turn this setting off, i.e., it could set
$auto_rc_useto zero to prevent automatic reading of the later RC ﬁles.
This variable does not affect the reading of RC ﬁles speciﬁed on the command line by the
The directory in which auxiliary ﬁles (aux, log, etc) are to be written by a run of (pdf)late x. If this
variable is not set, but$out_diris set, then$aux_diris set to$out_dir, which is the directory to
which general output ﬁles are to be written.
Important note: The effect of $aux_dir, if different from $out_dir, is s achieved d by giving
24 February 2016
(pdf)latex the-aux-directory. Currently (Dec. 2011 and later) this only works on the MiKTeX
version of (pdf)latex.
See also the documentation of$out_dirfor some complications on what directory names are suit-
If nonzero, the banner message is printed across each page when converting the dvi ﬁle to
postscript. Without modifying the variable$banner_message, this is equivalent to specifying the
Note that if f $banner is nonzero, the e $postscript_mode is assumed and the postscript ﬁle is
always generated, evenif itis newer than the dvi ﬁle.
Equivalent to the-bi option, this is a decimal number between 0 and 1 that speciﬁes ho w dark to
print the banner message. 0 is black, 1 is white. The default is just right if your toner cartridge
isn'trunning too low.
The banner message to print across each page when converting the dvi ﬁle to postscript. This is
equivalent to the-bm option.
Adecimal number that speciﬁes ho w large the banner message will be printed. Experimentation is
necessary to get the right scale for your message, as a rule of thumb the scale should be about
equal to 1100 divided by the number of characters in the message. The Default is just right for 5
character messages. This is equivalent to the-bs option.
This is an array variable, now mostly obsolete, that speciﬁes directories where e latexmk should look
for .bib ﬁles. By default it is set from the BIBINPUTS en vironment variable of the operating sys-
tem. Ifthat environment variable is not set, a single element list consisting of the current directory
is set. The format of the directory names depends on your operating system, of course. Examples
for setting this variable are:
@BIBINPUTS = ( ".", "C:\\bibﬁles" );
@BIBINPUTS = ( ".", "\\server\bibﬁles" );
@BIBINPUTS = ( ".", "C:/bibﬁles" );
@BIBINPUTS = ( ".", "//server/bibﬁles" );
@BIBINPUTS = ( ".", "/usr/local/texmf/bibtex/bib" );
Note that under MS Windows, either a forward slash "/" or a backward slash "\" can be used to
separate pathname components, so the ﬁrst tw oand the second twoexamples are equivalent. Each
backward slash should be doubled to avoid running afoul ofPerl's rules for writing strings.
Important note:This variable is nowmostly obsolete in the current version oflatexmk,since it has
abetter method of searching for ﬁles using the kpsewhich command. However, if your system is
an unusual one without the kpsewhich command, you may need to set the variable@BIBINPUTS.
$biber ["biber %O %S"]
The biber processing program.
Switch(es)for the biber processing program when silent mode is on.
24 February 2016
$bibtex ["bibtex %O %S"]
The BibTeX processing program.
Switch(es)for the BibTeX processing program when silent mode is on.
Under what conditions to run BibTeX or biber. Whenlatexmk discovers from the log ﬁle that one
(or more) BibTeX/biber-generated bibliographies are used, it can run BibTeX or biber whenever it
appears necessary to regenerate the bbl ﬁle(s) from their source bib database ﬁle(s).
But sometimes, the bib ﬁle(s) are not a vailable (e.g., for a document obtained from an external
archive), but the bbl ﬁles are pro vided. Inthat case use of BibTeX or biber will result in incorrect
overwriting of the precious bbl ﬁles. The variable$bibtex_usecontrols whether this happens. Its
possible values are: 0: never use BibTeX or biber. 1: only use BibTeX or biber if the bib ﬁles
exist. 2:run BibTeX or biber whenever itappears necessary to update the bbl ﬁles, without testing
for the existence of the bib ﬁles.
If nonzero, speciﬁes that cleanup also deletes ﬁles that are generated by custom dependencies.
(When doing a clean up, e.g., by use of the-C option, custom dependencies are those listed in the
.fdb_latexmkﬁle from a previous run.)
If nonzero, speciﬁes that cleanup also deletes ﬁles that are detected in log ﬁle as being generated
(see the \openout lines in the log ﬁle). It will also include ﬁles made from these ﬁrst generation
If nonzero, speciﬁes cleanup mode: 1 for full cleanup, 2 for cleanup except for dvi, ps and pdf
ﬁles, 3 for cleanup except for dep and aux ﬁles. (There is also extra cleaning as speciﬁed by the
$clean_ext, $clean_full_extand @generated_extsvariables.)
This variable is equivalent to specifying one of the-c or-C options. But there should be no need
to set this variable from an RC ﬁle.
Extra extensions of ﬁles for r latexmk to remove when any of the clean-up options (-c or-C ) is
selected. Thevalue of this variable is a string containing the extensions separated by spaces.
It is also possible to specify a more general pattern of ﬁle to be deleted, by using the place holder
%R, as in commands, and it is also possible to use wildcards. Thus setting
$clean_ext = "out %R-blx.bib %R-ﬁgures*.log";
in an initialization ﬁle will imply that when a clean-up operation is speciﬁed, not only is the stan-
dard set of ﬁles deleted, but also ﬁles of the form FOO.out, FOO-blx.bib, and %R-ﬁgures*.log,
where FOO stands for the basename of the ﬁle being processed (as in FOO.tex).
Extra extensions of ﬁles for r latexmk to remove when the-C option is selected, i.e., extensions of
ﬁles to remo ve when the .dvi, etc ﬁles are to be cleaned-up.
More general patterns are allowed, as for$clean_ext.
24 February 2016
$compiling_cmd [undeﬁned], $failure_cmd [undeﬁned], $success_cmd [undeﬁned]
These variables specify commands that are executed at certain points of compilations during pre-
view-continuous mode. One motivation for their existance is to allow convenient visual indica-
tions of compilation status evenwhen the window receiving the screen output of the compilation is
The commands are executed at the following points: $compiling_cmd at the start of compilation,
$success_cmd at the end of a successful compilation, and $failure_cmd at the end of an unsuccess-
ful compilation. If any of above variables is undeﬁned (the def ault situation) or blank, then the
corresponding command is not executed.
An example of a typical setting of these variables is as follows
$compiling_cmd = "xdotool search --name \"%D\" set_window --name \"%D compiling\"";
$success_cmd ="xdotool search --name \"%D\" set_window --name \"%D OK\"";
$failure_cmd = "xdotool search --name \"%D\" set_window --name \"%D FAILURE\"";
These assume that the programxdotoolis installed, that the previewer is using an X-Window sys-
tem for display, and that the title of the window contains the name of the displayed ﬁle, as it nor -
mally does. When the commands are executed, the placeholder string %D is replaced by the name
of the destination ﬁle, which is the pre viewed ﬁle. The abo ve commands result in an appropriate
string being appended to the ﬁlename in the windo w title: " compiling", " OK", or " FAILURE".
Other placeholders that can be used are %S, %T, and %R, with %S and %T normally being identi-
cal. These can be useful for a command changing the title of the edit window. The visual indica-
tion in a window title can useful, since the user does not have tokeep shifting attention to the (pos-
sibly hidden) compilation window toknow the status of the compilation.
Custom dependencylist -- see section on "Custom Dependencies".
Whenlatexmk is invokedwith no ﬁles speciﬁed on the command line, then, by def ault, it will pro-
cess all ﬁles in the current directory with the e xtension .tex. (In general, it will process the ﬁles
speciﬁed in the e @default_ﬁles variable.)
But sometimes you want to exclude particular ﬁles from this default list. In that case you can
specify the excluded ﬁles in the array y @default_excluded_ﬁles . For example if you wanted to pro-
cess all .tex ﬁ ﬁ les with the exception of common.tex, which is a not a standard alone LaTeX ﬁle b ut
aﬁ le input by some or all of the others, you could do
@default_ﬁles = ("*.tex");
@default_excluded_ﬁles = ("common.tex");
If you have a variable or large number of ﬁles to be processed, this method sa ves you from having
to list them in detail in@default_ﬁles and having to update the list every time you change the set
of ﬁles to be processed.
Notes: 1. This variable has no effect except when no ﬁles are speciﬁed on the
line. 2.Wildcards are allowed in@default_excluded_ﬁles .
24 February 2016
Documents you may be interested
Documents you may be interested