LaTeX is a fantastic, sometimes forgotten typesetting system - with a radically different workflow compared to most WYSIWYG editors. The fact that, in
LaTeX, what you edit (a
.tex file), and what you produce (typically a
.ps file) are totally different files can take a bit of getting used to. This idea of treating ‘documents as source-code’ has some powerful benefits, however. Many people already use VCS as a repository for storing
LaTeX markup - which has numerous benefits when it comes to managing multiple different versions of a document, and writing with multiple contributors. This post takes this markup-as-code' idea one step further and uses another tool familiar to software developers - build servers such as Jenkins1
Some of you may be asking: Why use a build server to produce
LaTeX documents?. Why not simply compile the PDF on your local machine, and copy it into Dropbox/Google Drive/an email? Whilst certainly an overkill addition to any small
LaTeX project, there are numerous advantages when writing long-running documents with multiple contributors:
- No need to install a (sizable)
LaTeXenvironment on your main development machine (especially useful if you use a number of packages not in the minimal
- Automatically produces a PDF from the latest version checked into VCS - no more forgetting to email your boss the most up-to-date copy (oops).
- Ensures anybody else working on your document can build the latest version successfully
If nothing else - it’s a great learning opportunity.
Set up your build server
There are numerous guides on the internet for setting up Jenkins. Here, however, we want to install an additional plugin - to send our produced
publish-to-dropbox2 Jenkins plugin prevents us from having to do this, or messing with the Dropbox API via CURL (yuck).
Install the plugin from ‘Manage Jenkins’ -> ‘Manage Plugins’ -> ‘Available’, and search for ‘Publish Over Dropbox’. Once installed (you’ll need to restart Jenkins), and generate a Dropbox API token. To do this, browse to ‘Credentials’ -> ‘Global Credentials’ -> ‘Add Credentials’ and select ‘Dropbox API Token’ via the dropdown. Generate and save the credential.
You’ll also need to configure the Dropbox location you wish to send the resulting
Configure your build agent(s)
Once your build agent(s) are set up, make sure
LaTeX is installed. There are numerous guides for configuration a
TeX environment on either Linux or Windows, but on Ubuntu Server (which I was using), a full TeX environment can be installed via apt-get:
sudo apt-get install --no-install-recommends texlive-fonts-recommended texlive-latex-extra texlive-fonts-extra dvipng texlive-latex-recommended
Configure your project in Jenkins
Creating a new project in Jenkins is simple - simply login and hit the
New Item button.
As with any other Jenkins project, you’ll need to give your VCS details. I use Git here.
Configure Jenkins to poll VCS reasonably often (or use a post-commit hook), and execute
pdflatex as the only build step:
Finally, archive the produced
Advanced settings will allow you the option of flattening the output directory structure (advisable), using a DateTime as part of the folder name and/or clearing out the folder before transferring files. This last option might tempt you - but remember that Dropbox will overwrite any files with the same name when you push new files to it. Furthermore, it will treat the new file as a version of the old one - which will allow you to restore the older version should you wish.
Run the build
And we’re done! Obviously, once you’ve got a basic build set up for
LaTeX documents, all sorts of things are possible. You could run a spell checker as part of the build process, or notify a mailing list of a new version of the document. Hopefully, however, this has been enough to get you started - happy writing!