Why use ci in latex projects?
Nowadays, it is common for software projects to use continuous integration (ci) services to automate building, testing and deployment. If you view and handle a LaTeX project as a software development project then using ci might add a lot of benefits.
For example it is crucial to have always a clean and error-free output build. This applies especially, when it comes to collaboration between multiple authors or template developers. Compiling large latex files can consume quite a time. The ci services gives you the benefit of saving this time by running in the background while you focus on writing. The services allow to include a status icon, indicating the current build status. Seen this icon before?
It also checks integrity when merging pull requests on github. This ensures, that your pdf output is created by the new source file. There are also many private options from several ci providers, if you consider your work as private or not available for the public.
The following guide shows you step-by-step how to create a ci setup for your latex project with the example of travis-ci as the ci service.
Imagine a simple latex project setup, which consists of the following structure:
main --- main.tex --- main.pdf --- test.sh --- .travis.yml
We have a single main file with an already created output pdf, a shell script to test our build success and finally our travis settings file. The example project can also be viewed and downloaded here.
Create a test script
Make sure at first, that your project compiles locally. I like to use a bash script for this purpose, basically because I can directly reuse it in my travis pipeline. If there are more than one files to compile, the script can be easily re-used by accepting the build location as a parameter.
#!/usr/bin/env bash # change into the desired folder cd $1 # remove pdf if present [ -f $2.pdf ] && rm $2.pdf || echo "continue without remove" # test if pdf is removed, fail if still present [ -f $2.pdf ] && exit 1 || echo "continue building pdf output" # build pdf from source pdflatex $2.tex # exit successfully if pdf is present or with error if not present [ -f $2.pdf ] && exit 0 || exit 1
In this scrip $1 represents the folder, wehre your file to build is present. The second parameter represents the name of your file to build. I usually use main.tex but this, of course, may vary on each user. Summarized, you can call the script via command line (and later in travis) like so:
test.sh ./ main
This does basically the same as if you run the build via your latex editor. It is just a call to the underlying pdflatex binary which starts to build your pdf output. If your script runs locally and exits without errors then you are just two steps away from building it on travis.
Register on travis and add your project
You need to register, if you haven’t a travis account yet. If you haven’t even used git for latex, you should immediately drop all activities and start reading first, why you should definitively use git for latex. You need to integrate your github repository in order to allow travis to make builds, based on your latest repository push activities.
Once your project is activated you may push some code changes to your project, assuming you have your .travis.yml file included and configured. The next step will show and explain an example configuration, specified for our example project.
Configure your travis build for latex
Travis fetches your project on every push to your github repo (or by custom settings) and starts building, based on a settings file, called .travis.yml. There is a whole universe of settings for travis environments, so I will just focus on those relevant for latex. Look at the following code:
sudo: require dist: xenial language: bash before_install: - sudo apt-get -qq update - sudo apt-get install -y texlive-base texlive-latex-base texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra script: - bash test.sh ./ main
The file contains first some settings for the container environment, which is here set to Ubuntu 16.04. The language focus is bash, because we will basically run our test script as above to create our build. In the “before_install” section it installs minimal requirements to get (most) latex code into an output format. Note, that this part may require some tweaking, based on your tex environments and how fancy your tex commands and packages are. The final script part calls our script as in our local build.
Pushing your code and starting the build
Once you push new code to your project, travis will trigger the new build. The yellow color indicates a new build is in progress.
The whole build passes, if all installations and our test script exit without errors.
From here you may use further steps after to script to e.g. rename the output file and release it to a website.
I hope this post brings you a bit closer to the benefits of a ci service in your latex project. Here are the main messages to take home.
- You should always track your latex code with git to manage collaboration and versioning.
- You can use a ci service to compile your output in the background.
- Ci services can help you the check for successful builds, when merging pull requests. This can support your decision to accept or reject contributions.
- Your work can be directly be published or updated if your build succeeds. All in one step.
- Large projects with high versioning and revision rate become less error prone.
- Travis files need good care on complex project setups. There may be a lot builds failing before getting the configuration right.
- You still need to build locally to ensure
- High learning curve, if you are new to git and command line usage.
- Small projects with low version rate might not benefit so much.