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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
\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:
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:
1 2 3 4 5 6 7 8 9 |
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:
1 2 3 4 5 6 7 8 9 10 11 |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
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' |
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
subsec:depth:sgdu:approximation‘ on page 1 undefined on input line 23Reference
Reference
subsec:depth:sgdu:approximation' on page 1 undefined on input line 26
tbl:middlebury2014_mae_nobp‘ on page 1 undefined on input line 428Reference
=== 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
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.