There are many different ways to automate the compilation of a LaTeX project.

I would like to start a discussion, what would be the most flexible and elegant and omnipotent way to provide a project which is compilable quickly on all operation systems, in most programs and for all users.

The example scenario: I am uploading a "super complex project" to BitBucket or alike. I want to work on it on Linux and Windows. If others want to contribute something, they just have to read my README.md saying for example "Install arara and make, open main.tex in vim and run :make on Linux or :! make on Windows! Ready!"

I have not used rubber or latexmk but am keen to learn about. Please comment on that, if you like it.

My routine for now is:

Using arara in the main.tex

% arara: lualatex: { shell: yes }
% arara: biber
% arara: makeglossaries
% !arara: indent: { overwrite : yes, trace : yes, files: [ header.tex, main.tex, chapter/Foo.tex, chapter/Bar.tex] }

Edit this file in vim and run :make with the following Makefile (excerpt)

target = main

all: ararabuild


    arara --log --verbose $(target)

view: ararabuild viewonly

    evince $(target).pdf || AcroRd32.exe $(target).pdf

    biber $(target)

%.pdf: %.tex
    ararabuild $<

    find . -name "*.log" | xargs rm -vf
    find . -name "*.aux" | xargs rm -vf
    find . -name "*.toc" | xargs rm -vf
    find . -name "*.blg" | xargs rm -vf
    find . -name "*.out" | xargs rm -vf
    find . -name "build" | xargs rm -vf

This runs good for me (except the cross-platform view stuff). But I just would like to see what techniques are around, what is best practice... or simple: How to get rid of all the configurations of different LaTeX-programs, the explanations of compiling routines and so on. Just imagine a TeX-template for a company. Much easier to provide if they just have to input their text using some familiar editor and then (for example) double click on some batch file...

I hope it is allowed to start such a discussion here. TeX automation tools are cool, but their use isn't that popular until now and cool using examples are still missing i.m.o.

  • 3
    Are we allowed to cheat and use two different tools? For example, for LaTeX3 development we use make on Unix but batch files on Windows. The batch files are called make.bat, so the interface is platform-independent. – Joseph Wright Aug 20 '13 at 16:12
  • Of course. I am using arara and make. Insert what ever you want into your project folder and write a "README.md for idiots". – LaRiFaRi Aug 20 '13 at 16:15
  • I haven't had to write a latex build script after trying latexmk – Clayton Stanley Aug 21 '13 at 6:21
  • It depends on what "super complex project" means. For the case illustrated by your example, latexmk is an appropriate tool. It automatically determines dependencies and the necessary number of repeated runs (of pdflatex or lualatex, or whatever). All you do is run the command as latexmk main. Since you use lualatex and makeglossaries, you'll need a latexmrc file to configure latexmk appropriately (it would be about 4 lines). This is all platform independent. – John Collins Aug 21 '13 at 12:50
  • You could use lake, which is a build engine written in Lua, with LuaTeX. – Martin Schröder Aug 21 '13 at 15:05

To allow convenient use of latexmk for making/building the project, put a file latexmkrc in the same directory is its primary source file main.tex. For the project described in the question, appropriate contents of latexmkrc are

$pdf_mode = 1;
$dvi_mode = $postscript_mode = 0;
$pdflatex = 'lualatex %O %S';
@default_files = ( 'main.tex' );

The first two lines simply tell latexmk to make a .pdf file instead of its default .dvi. The third line configures latexmk to use lualatex instead of its default of pdflatex, since the question indicates that this is required by the project. The fourth line specifies the name of the primary source file (taken from the question).

Then to do the compilation from the command line, the user should just change directory to the main directory of the project, and then run the command latexmk. That will take care of running lualatex, biber, and makeindex as needed. There is no need to specify any of the files on which the project depends other than main.tex; those dependencies are all determined by latexmk.

Platform independence

Latexmk is installed by default in both the major distributions, TeXLive and MiKTeX. It runs on all the major OSs. Its only requirements are to have a correct TeX installation and to have Perl available. Perl is installed by default on Linux and OS-X, and is included with the MS-Windows version of TeXLive. But a user running MiKTeX on MS-Windows may need to install Perl.


The question also indicated that the project uses glossaries. In the latexmk distribution see http://www.ctan.org/tex-archive/support/latexmk/example_rcfiles to find some examples of how to configure latexmk for special situations. One of the examples covers the case of glossaries.

Use with front ends

For a user who prefers not to use the command line from a terminal, front ends like TeXShop, TeXWorks, etc can be configured to use latexmk. The user should consult the documentation for his/her preferred front end program and/or do the appropriate Google search. Experts on each of these programs could add to this answer pointers to where these instructions are to be found.

  • Thanks for your answer. I was waiting for more interesting examples but the discussion is not getting in a roll... Therefore I mark your good answer as such. – LaRiFaRi Sep 9 '13 at 7:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.