Configuring latexmk
latexmk
is a standard tool in LaTeX distributions which will call the latex compiler (pdflatex
or lualatex
) the correct amount of times to have things such as references and citations filled out correctly.
An alternative to using your LaTeX editor to handle the compilation would be to run the following in the command line:
latexmk -pdf -pvc file.tex
This compiles the file.tex
file to a PDF and opens a preview; but also watches for any changes in relevant files and rebuilds the document when necessary.
For more of this, check out this guide for another introduction to latexmk
mainly geared around immediate usage advice.
If after reading that, you want a bit more examples to see whether latexmk
is for you, read on.
Why should I know about latexmk?
Even if you use an editor to handle the compilation and preview of your document, there's a good chance that it already uses latexmk
under the hood, or can be configured to do so.
This means that by adding a latexmk
configuration file for your project, you could configure the way your document is built in a way that's agnostic to the editor.
This could be a benefit if you...
- want the flexibility to use different tools on different computers for the same project
- have multiple people on a project with different editors
- want to reduce your dependence on specific tools
And by "configuration", I mean things including:
- name and location of the output file (here)
- whether to use
lualatex
orpdflatex
(here) - extra options to pass to the above, such as:
- whether to ask for interaction when there's an error
- whether to allow "shell escape" (necessary for some packages)
- whether to use an existing "format file" (see preamble precompilation)
- locations of extra places for packages or
.tex
files (here) - what to do when a file is not found (with the
-use-make
flag, not discussed here) - set the PDF viewer to use with the preview
latexmk
options (here)
Useful configurations for latexmk
To configure latexmk
for a project, add a file called latexmkrc
in the same directory.
When you call latexmkrc
in the same directory this file will be read,
saving you having to pass these configurations as command line arguments to latexmk
(what is typically done by LaTeX editors).
Configurations which are project agnostic could go in a global
latexmkrc
file instead (location specified here)
Full documentation for latexmk
can be found here,
but to get started here are a few things you might consider putting in your latexmkrc
file:
Enabling PDF mode
Most likely relevant good in all your projects, to build PDFs (as opposed to other targets).
This saves calling latexmk
with the -pdf
flag, and should really be the default setting.
$pdf_mode = 1;
Specifying the main TeX file
@default_files = ('file.tex');
By default, latexmk
will find all .tex
files in the current directory and try to compile them if you didn't specify any.
If there are extra .tex
files for sections or chapters, attempting to compile them individually will result in errors
anyway, so you might as well make sure that latexmk
knows which is the main file.
Specifying the command to compile LaTeX
The $pdflatex
variable can be defined to specify what command to be run in place of pdflatex
. This can be used to specify to use lualatex
instead, but also to specify any extra command line arguments to use.
You may consider using one of the following examples as a starting point:
$pdflatex = 'pdflatex %O %S';
$pdflatex = 'pdflatex -interaction=nonstopmode %O %S'; # Do not ask to fix errors interactively
# (^ if a package was not installed, I'm not going happen to have the sty file somewhere and type out its path! Just cancel the run and let me install the package before trying again!!)
$pdflatex = 'lualatex %O %S';
$pdflatex = 'lualatex -shell-escape %O %S'; # necessary for some packages which run shell commands
The
%O
and%S
are placeholders for extra options and the file to compile, respectively.
Specify an output location
$out_dir = 'OUTPUT_FOLDER';
# e.g. $out_dir = 'output';
Instead of scrolling through a sea of auxiliary files to find the tex file or PDF, put the output files (including the PDF) in the location specified.
Specify a location for the auxiliary files
$aux_dir = 'AUX_FOLDER';
# e.g. $aux_dir = 'aux_files';
Put all the auxiliary files (random files produced by LaTeX) in the location specified.
Gives a similar benefit of decluttering.
Also simplifies your .gitignore
file if you use git
.
Base name of output files
LaTeX compilers can be provided with a "jobname" which is used to name the output files, including the PDF.
$jobname = 'PAPER_TITLE';
Specify extra locations to look for files
Maybe you want to use a tex file or package that's in a different folder, you can make you LaTeX compile search
this folder by adding it to the TEXINPUTS
environment variable.
This could be done in the command line, in you shell init script (such as .bashrc
),
or you could enforce this in the latexmkrc
file like so:
ensure_path('TEXINPUTS', 'PATH_TO_OTHER_STY_OR_TEX_FILES');
However you may want to consider alternatives:
- put personal preambles or packages in you TEXMF tree
- specify the relative path of sub-parts of your document directly (e.g.
\input{../other_folder/other_file.tex}
or\import{../other_folder/}{other_file.tex}
)
Allow LaTeX compiler to run even more times
By default, latexmk
will run the LaTeX compiler until the references and citations are filled out correctly,
but a maximum of 5 times.
If for whatever reason, you need to run the compiler more times, you can specify this in the latexmkrc
file:
$max_repeat = 6;