[Tex/LaTex] the most elegant way to provide a cross-platform project with automated compilation routine

araracompilinglatexmkmakefilerubber

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

full: 
    ararabuild
    ararabuild
    ararabuild

ararabuild:
    arara --log --verbose $(target)

view: ararabuild viewonly

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

bib: 
    biber $(target)

%.pdf: %.tex
    ararabuild $<

clean:
    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.

Best Answer

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.

Glossaries

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.

Related Question