Continuous-Delivery-Pipelines für LaTeX-Dokumente

23. August 2019

Einführung LaTeX

LaTeX ist eine mittlerweile schon in die Jahre gekommene textuelle Textsatzsprache, die besonders im wissenschaftlichen Bereich genutzt wird. Statt dass Dokumente im WYSIWYG-Modus direkt während der Eingabe auf dem Bildschirm in ihrem finalen Layout angezeigt werden, wird eine reine Textdatei verwendet, die später in eine Ausgabedatei wie PDF, PostScript oder auch DVI und andere übersetzt wird.

Eine solche Textdatei main.tex kann beispielsweise wie folgt aussehen:

\documentclass [a4paper]{article}
 \usepackage{german}
 \usepackage [latin1]{inputenc}
 \begin {document}
  \section {Ein kleines Testdokument}
  \subsection {Ein normaler Text}
   Dies ist ein kleiner Text 
  \subsection {Formel im Text}
   Man kann eine Formel wie diese hier im
   Text einbetten: $\sum^{n}_{k=0}\frac{k}{2}$
  \subsection {Formel ausserhalb}
   Oder auch so:
   \[\sum^{n}_{k=0}\frac{k}{2}\]
  \subsubsection{Dies ist eine weitere Untersektion}
\end {document}

\documentclass [a4paper]{article}

\usepackage{german}

\usepackage [latin1]{inputenc}

\begin {document}

\section {Ein kleines Testdokument}

\subsection {Ein normaler Text}

Dies ist ein kleiner Text

\subsection {Formel im Text}

Man kann eine Formel wie diese hier im

Text einbetten: $\sum^{n}_{k=0}\frac{k}{2}$

\subsection {Formel ausserhalb}

Oder auch so:

\[\sum^{n}_{k=0}\frac{k}{2}\]

\subsubsection{Dies ist eine weitere Untersektion}

\end {document}

Kompiliert ergibt diese reine Textdatei dann eine PDF-Datei main.pdf mit folgendem Inhalt:

Noch viele weitere unterschiedliche Gestaltungsmerkmale und Features sind möglich. LaTeX verfügt über einen weitreichenden Plugin-Katalog, mit dem auch außergewöhnliche Elemente gesetzt werden können.

Vor- und Nachteile LaTeX

Ein Nachteil von LaTeX und ähnlichen Systemen ist, dass man Dokumente nicht intuitiv erstellen kann, sondern eine Textsatzsprache erlernen muss. Nach einer ersten Eingewöhnung wird man feststellen, dass diese Sprache jedoch nicht allzu kompliziert ist.

Nun beginnen die Vorteile zu überwiegen. Die mit LaTeX gesetzten Dokumente sehen auch nach Jahren nach einer Neukompilierung noch genauso aus, wie zuvor, da die Software anderes als moderne Textverarbeitungen sehr stabil ist. Auch große Dokumente wie beispielsweise Bachelor-, Master- oder Doktorarbeiten lassen sich problemlos setzen und ohne Fehler erzeugen. Auch wissenschaftliche Papers in den naturwissenschaftlichen Fächern werden meist mit LaTeX geschrieben, da dieses Format problemlos zu einem großen Dokument, um beispielsweise einen Tagungsband zu erstellen, weiterverarbeitet werden kann. LaTeX macht es dem Autor einfach, die logische Struktur des Textes von seinem Design zu trennen. Statt mit Schrift-Größen und -Arten zu hantieren, definiert er Überschriften und Blöcke.

Versionskontrollsysteme wie GIT oder SVN

Ein letzter großer Vorteil von LaTeX, der hier genannt werden soll, ist das Format in einer reinen Textdatei. Dies ermöglicht es, das gesamte Dokument unter ein Versionskontrollsystem wie etwa SVN oder GIT zu stellen und mit Hilfe der Versionskontrolle seine Geschichte nachzuvollziehen. Auch ein Arbeiten mit mehreren Personen an demselben Dokument wird so effektiv möglich. Die Features, die in Teams in moderner Softwareentwicklung erfolgreich genutzt werden, kommen auch hier so zu tragen.

Continuous Integration-Systeme

Seit geraumer Zeit sind sogenannte Continuous Integration-Systeme (CI) verfügbar. Diese sorgen dafür, dass der Sourcecode, welcher sich in einem Repository eines Versionskontrollsystems befindet, automatisch ausgecheckt, kompiliert und getestet wird. Eine Erweiterung dieser Idee ist im Continuous Delivery-System (CD) verwirklicht. Diese Software archiviert das Artefakt, welches bei der Kompilierung entstanden und durch die Tests geprüft worden ist, so dass dieses Artefakt später in Produktion gebracht werden kann. Ein Continuous Deployment-System (CD) geht noch einen Schritt weiter und deployt das Artefakt auch automatisch produktiv. Mit Hilfe dieser Methode schaffen es Unternehmen mehrfach täglich Softwareänderungen an ihrem System durchzuführen. Voraussetzung hierfür ist eine gute Testabdeckung des Systems, so dass ein Pipelinedurchlauf fehlschlägt, wenn durch eine Änderung im Sourcecode ein Fehler entstanden ist und somit der Fehler nicht deployt wird. Generell ist es aber so, dass hiermit jeder Checkin ins Versionskontrollsystem zu einem produktiven Ausrollen der Änderung führt.

Unterschiedliche Anbieter haben in den vergangenen Jahren vor allen Dingen in Kombination mit dem Versionskontrollsystem GIT Cloudlösungen für einen CI/CD-System bereitgestellt. Somit ist kein eigenständiger CI/CD-Server mehr notwendig, sondern vorhandene Resourcen können mitgenutzt werden. Diese CI/CD-Systeme fußen teilweise auf Docker-Lösungen. Docker ist eine Containerierungsplattform, auf welcher abgekapselt eigene Software bereitgestellt und betrieben werden kann. Durch die Nutzung von Docker ist eine sehr weitläufige Anpassung des Buildprozesses möglich, was uns zu dem Ziel dieses Artikels bringt:

LaTeX-Dokumente innerhalb eines GIT-Repositories verwalten und mit Hilfe eines Cloud-CI/CD-Systems bei einem Checkin automatisch bauen lassen, so dass das entstehende PDF direkt aus dem CI/CD-System herunterladbar ist.

Das Docker-Image

Das Docker-Image beinhaltet alle Dateien, die für den Buildprozess des LaTeX-Files notwendig sind. Dies ist vor allen Dingen die LaTeX-Umgebung aber auch Betriebssystemdateien.

Das Docker-Image in unserem Fall wird mit Hilfe der unter https://github.com/ctornau/latex hinterlegten Dateien gebaut und ist unter Docker Hub als vollständiges Image mit der Referenz ctornau/latex verfügbar. Dieses Image beinhaltet ein Ubuntu-Linux als Basis sowie die TeX Live-Distribution, welche die umfangreichste Distribution darstellt.

Wenn Deine LaTeX-Datei mit Namen main.tex in dem lokalen Verzeichnis c:\dok\arbeit liegt, dann kann bei einem installierten Docker ein lokaler Build mit dem folgenden Kommando angestoßen werden:

docker run -v c:\dok\arbeit\:/latex ctornau/latex /bin/sh -c "cd latex &amp;&amp; latexmk -pdf main.tex"

1	docker run -v c:\dok\arbeit\:/latex ctornau/latex /bin/sh -c "cd latex && latexmk -pdf main.tex"

CI/CD-Umgebung GitLab

Das Docker-Image kann im GitLab-Buildprozess mit Hilfe der Datei .gitlab-ci.yml wie folgt genutzt werden:

image: ctornau/latex

build:
  stage: build
  artifacts:
    paths:
      - main.pdf
  script:
    - latexmk -pdf main.tex

image: ctornau/latex

build:

stage: build

artifacts:

paths:

- main.pdf

script:

- latexmk -pdf main.tex

Bitte den Link https://gitlab.com/tornau/latex zu einem Beispiel GitLab-Projekt nutzen.

CI/CD-Umgebung BitBucket

Wenn BitBucket die präferierte Lösung ist, dann muss die Datei bitbucket-pipelines.yml in das GIT-Repository eingecheckt werden:

image: ctornau/latex

pipelines:
    default:
        - step:
            name: Build and Upload PDF
            script:
                - latexmk -pdf main.tex
                - curl -X POST "https://${BB_AUTH_STRING}@api.bitbucket.org/2.0/repositories/${BITBUCKET_REPO_OWNER}/${BITBUCKET_REPO_SLUG}/downloads" --form files=@"main.pdf"
            artifacts:
                - main.pdf

image: ctornau/latex

pipelines:

default:

- step:

name: Build and Upload PDF

script:

- latexmk -pdf main.tex

- curl -X POST "https://${BB_AUTH_STRING}@api.bitbucket.org/2.0/repositories/${BITBUCKET_REPO_OWNER}/${BITBUCKET_REPO_SLUG}/downloads" --form files=@"main.pdf"

artifacts:

- main.pdf

Um das Artefakt in den internen BitBucket-Bereich zu transferieren, wird die secret variable BB_AUTH_STRING benötigt, die innerhalb des Repositories manuell einmalig angelegt werden muss. Eine Anleitung, wie dies zu tun ist, ist hier verfügbar.

Bitte den Link https://bitbucket.org/tornau/latex folgen, um ein Beispiel in einem BitBucket-Repository zu finden.

Azure DevOps

Auch bei den großen Public-Cloud-Anbietern gibt es CI/CD-Lösungen. Innerhalb von Azure DevOps kann beispielsweise mit der Datei azure-pipelines.yml eine entsprechende Pipeline aufgebaut werden. Dabei ist zu beachten, dass Azure keine Container, sondern virtuelle Maschinen für den Build zur Verfügung stellt. Man könnte in eine solche virtuelle Maschine LaTeX on-the-fly hinein installieren. Jedoch ist im folgenden nochmals der Weg über Docker gegangen:

image: ctornau/latex
trigger:
- master

pool:
  vmImage: 'ubuntu-latest'

container: ctornau/latex:latest   

steps:
- script: latexmk -pdf main.tex
  displayName: 'Run latexmk'
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: 'main.pdf'
    ArtifactName: 'PDF'
    publishLocation: 'container'

image: ctornau/latex

trigger:

- master

pool:

vmImage: 'ubuntu-latest'

container: ctornau/latex:latest

steps:

- script: latexmk -pdf main.tex

displayName: 'Run latexmk'

- task: PublishBuildArtifacts@1

inputs:

PathtoPublish: 'main.pdf'

ArtifactName: 'PDF'

publishLocation: 'container'

Die Schritte in Azure DevOps zum Herunterladen des PDFs

Nick:

2. April 2020 um 12:52 Uhr

Vielen Dank fuer die Anleitung. Gibt es eine Moeglichkeit, failende Builds zu erkennen.

Die sind meine „famous last words“. Ich wuerde gerne, dass die Pipeline in Bitbucket failed, wenn referencen nicht aufgeloest werden koennen.

Citation ‚Zweig2016ARXIV‘ on page 33 undefined on input line 297
Reference sec:method' on page 1 undefined on input line 525 Referencesubsec:depth:sgdu:approximation‘ on page 1 undefined on input line 23
Reference subsec:depth:sgdu:approximation' on page 1 undefined on input line 26 Referencetbl:middlebury2014_mae_nobp‘ on page 1 undefined on input line 428
=== TeX engine is ‚pdfTeX‘
Biber error: [269] Utils.pm:316> ERROR – Cannot find ‚bib/bibliography_long.bib‘!
Latexmk: Biber did’t find bib file [bib/bibliography_long.bib]
Latexmk: Summary of warnings from last run of (pdf)latex:
Latex failed to resolve 5 reference(s)
=====Latex reported missing or unavailable character(s).
=====See log file for details.
Latex failed to resolve 262 citation(s)
Latexmk: All targets () are up-to-dat

Christoph Tornau:

2. April 2020 um 23:07 Uhr

Die Pipeline sollte fehlschlagen, wenn der Exit-Code des Prozesses nicht 0 ist. Scheinbar gibt pdfTeX hier nicht den richtigen Error-Code zurück bzw. meint, dass es das Dokument trotzdem so ausgeben kann. Man kann einmal in die Referenz von BibTeX schauen, wie der Exit Code gesetzt werden kann.

Christoph Tornau