пятница, 7 апреля 2017 г.

Автоматическая сборка LaTeX-проекта с GitHub и TravisCI

По умолчанию TravisCI не умеет нативно собирать LaTeX-проекты, однако он позволяет запускать Docker-контейнеры.
Моя задача состоит в том, что у меня есть некий проект, в котором после каждого коммита нужно собирать новый PDF-файл с помощью XeTeX и релизить этот PDF-файл на GitHub.
Можно собирать проект на рабочей машине, но если не хочется устанавливать LaTeX-окружение, то можно воспользоваться Docker.

Расскажу как это реализовано в репозитории: https://github.com/Amet13/master-thesis

1. Идем в TravisCI, по ссылке https://travis-ci.org/profile/Amet13, где Amet13 - это имя юзера на GitHub и включаем репозиторий:


2. Далее добавляем в свой репозиторий файл .travis.yml, вот пример моего:
language: generic

services:
  - docker

script:
  - make docker

deploy:
  provider: releases
  api_key: $TOKEN
  file: master-thesis.pdf
  skip-cleanup: true

Тут мы указали, что используем сервис docker и после этого запускаем команду make docker.
Тут используется переменная TOKEN, которая содержит API-токен GitHub, создать токен можно вот по этой ссылке: https://github.com/settings/tokens

Токен мы сгенерировали, теперь надо добавить переменную в TravisCI, сделать это можно в разделе Settings, или по ссылке аналогичной: https://travis-ci.org/Amet13/master-thesis/settings

В таком случае переменная TOKEN зашифрована и вы не спалите свой токен.

3. Так как мы используем Docker, то для сборки контейнера должен быть Dockerfile, вот пример моего:
FROM ubuntu
MAINTAINER Amet13 <[email protected]>

ENV DIR /master-thesis
RUN mkdir $DIR

RUN echo "deb http://archive.ubuntu.com/ubuntu/ trusty multiverse" | tee -a /etc/apt/sources.list.d/multiverse.list && \
   echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | debconf-set-selections

RUN apt update && \
   apt install -y git make wget apt-transport-https && \
   apt install -y texlive-base texlive-latex-extra texlive-xetex texlive-lang-cyrillic latexmk texlive-fonts-extra texlive-math-extra

RUN apt install -y --reinstall ttf-mscorefonts-installer

RUN wget -O /usr/share/fonts/xits-math.otf https://github.com/khaledhosny/xits-math/raw/master/xits-math.otf && \
   fc-cache -f -v

VOLUME $DIR
WORKDIR $DIR

Суть этого контейнера такова, что на чистую Ubuntu устанавливаются нужные пакеты для работы LaTeX и устанавливаются шрифты используемые в проекте.

4. В файле .travis.yml у меня была указана команда запуска make docker, для того чтобы эта команда сработала у меня есть Makefile:
all: build run

build:
latexmk -xelatex -synctex=1 -jobname=master-thesis main.tex
...
clean:
rm *.aux \
*.fdb_latexmk \
*.fls \
*.lof \
*.lot \
*.log \
*.out \
*.synctex.gz \
*.toc

docker:
docker build -t docker-latex .
docker run -ti -v ${PWD}:/master-thesis:Z docker-latex bash -c "make build && make clean"

То есть при запуске команды make docker, по очереди выполняются две команды:
docker build -t docker-latex .
docker run -ti -v ${PWD}:/master-thesis:Z docker-latex bash -c "make build && make clean"

Первая команда собирает образ Docker с именем docker-latex, а вторая запускает Docker-контейнер на основе этого образа. Сборка занимает около 10 минут, так как скачивается очень много пакетов. Возможно для ускорения сборки я залью когда-нибудь на docker hub образ.

В этот Docker-контейнер монтируется каталог с исходниками проекта и в контейнере запускается команда make build && make clean, что означает сборку проекта и очистку мусорных файлов.
После того как проект собрался в Docker-контейнере, он удаляется, а все изменения сохранены в окружении TravisCI, так как мы монтировали каталог внутрь Docker-контейнера.

5. Выходит что проект собран, осталось только свежесобранный PDF-файл выкатить на GitHub.
Если мы указали в TravisCI корректный токен, то TravisCI выкатит новый релиз, который можно посмотреть по аналогичной этой ссылке: https://github.com/Amet13/master-thesis/releases

Комментариев нет: