# Using Travis CI with LaTeX documents

## What is CI?

Continuous integration is a software development practice of frequently commiting source code changes, often several times per day, into a shared pipeline. Then, automated tools are used to build and test this code at an accelerated pace. This allows for any issues or faults to be identified quickly and therefore be corrected quickly. Furthermore, the continual process of merging new work with the exisiting code base ensures that any single person cannot veer too far off course. This avoids the integration hell that frequently occurs for large projects.

We can utilize the same concepts for our LaTeX documents and ensure that the manuscripts are consitently able to be built and available for others to view. The key concepts invovled here are common to any software project and can be readily extended:

1. Version control using Github
2. Continuous Integration using Travis CI
3. Building/Compiling source code LaTeX into the end product

The specifics of version control, continuous integration, or LaTeX are not explained here but might be topics for a future post.

## Setup Travis

1. Go to Travis and sign up for an account and connect it to your Github account.
2. Enable the CI for your repository by flipping the switch. You can adjust related settings here as well if desired.

1. First, it’s assumed that you already have your manuscript tracked by git, if not you should really start now! In addition, you want to ensure that you Github repository is publically available.

2. Add a .travis.yml file to the root directory of your repo. This file is used by Travis to adjust the settings for the remote system that will build and test your document. There are many settings you can modify by reading through the Travis documentation. Here’s a simple example that should work well for LaTeX repositories.

 sudo: false
language: generic
matrix:
include:
- os: linux
cache:
directories:
- "/tmp/texlive"
- "$HOME/.texlive" timeout: 3600 before_install: - travis_wait 45 bash ./utilities/travis_setup.sh - export PATH="/tmp/texlive/bin/x86_64-linux:$PATH"
script:
- latexmk -pdf -interaction=nonstopmode -halt-on-error manuscript.tex


On every commit to your repo, Travis will instantiate a Linux virtual machine, setup LaTeX and build the manuscript. Installing LaTeX is defined in the ./utilities/travis_setup.sh directory as:

 #!/bin/bash

# setup script to install texlive and add to path
texlive_year="2018"

sudo apt-get -qq update
export PATH=/tmp/texlive/bin/x86_64-linux:\$PATH

if ! command -v pdflatex > /dev/null; then
echo "Texlive not installed"
wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
tar -xzf install-tl-unx.tar.gz
./install-tl-*/install-tl --profile=./utilities/texlive.profile

echo "Finished install TexLive"
fi

echo "Now updating TexLive"
# update texlive
tlmgr option -- autobackup 0
tlmgr update --self --all --no-auto-install

echo "Finished updating TexLive"

git clone https://github.com/skulumani/texmf.git ~/texmf


The last line is used to clone my texmf tree to the virual machine and provide me access to my shared bibliography and LaTeX settings. Using texlive.profile allows for many of the installation settings to be programmatically defined.

 selected_scheme scheme-full
TEXDIR /tmp/texlive
TEXMFCONFIG ~/.texlive/texmf-config
TEXMFHOME ~/texmf
TEXMFLOCAL /tmp/texlive/texmf-local
TEXMFSYSCONFIG /tmp/texlive/texmf-config
TEXMFSYSVAR /tmp/texlive/texmf-var
TEXMFVAR ~/.texlive/texmf-var
option_doc 0
option_src 0

3. Once all of the files are commited, you can push to Github which will set off Travis to build your manuscript. You can visit your Travis dashboard and watch the progress.

## Automatic releases on tags

An additional benefit of Travis/Github working together is that you can automatically release or display your compiled PDFs. I typically use this with Git tags to identify important milestones, such as drafts or journal submissions. With this setup, Travis will automatically create a Github release with your PDF for every tagged commit.

1. Install Travis CLI
2. Use the travis gem to encrypt a Github key to enable releases by running the following in your repo.

 travis setup releases

3. This will setup a section similar to the following in your .travis.yml

 deploy:
provider: releases
api_key:
secure: <github key>
file: manuscript.pdf
skip_cleanup: true
on:
repo: skulumani/2018_JGCD
tags: true

4. Profit

## Examples

Most of my work is using this setup. This includes both LaTeX documents as well as other software.