| Travis CI |
|---|
 |
| Build History |
|---|
In diesem Repository ist eine LaTeX Vorlage für eine Bachelorarbeit, die Arbeit ist nach der "Vorlage & Formulare\AufbauDokumentation" auf dem SharePoint Ordner I_Projektschiene der HSLU strukturiert.
Die einzelnen Kapitel sind in separate TeX-Dateien im Ordner include ausgelagert und werden über den Befehl \include{Datei.tex} in das Hauptdokument eingebunden.
Die Ordnerstruktur ist die folgende:
Hauptordner
|- .github Konfigurationsdatei für HG-Workflow
|- appendix Alle Dokumente für den Anhang (PDFs in diesem Ordner werden durch das .gitignore nicht erfasst)
|- img Alle Bilder (werden durch den \graphicspath im Hauptdokument gefunden)
|- include Alle Kapitel-Dateien welche in das Hauptdokument eingebunden werden (inklusive Präambel)
|- web-abstract Ordner für das Web Abstract
|- .gitignore
|- .travis.yml Konfigurationsdatei für Travis
|- .env Hilfsdatei für die Konfiguration von CI (Travis, GH-Workflow)
|- BA-Dokumentation-Template.tex Hauptdatei
|- Referenzen.bib BibTeX Datei / Referenzbibliothek
|- texlive.profile Hilfsdatei für das Installskript
|_ texlive_install.sh Installskript
Ich (Pascal) empfehle euch mit TeXStudio zu arbeiten, Dane eher den TeXMaker (er kann das Layout von TS nicht leiden). Egal welchen Editor ihr verwendet, da wir sowohl ein Glossar wie auch ein verbessertes Bibliotheksbackend (Biber) verwenden, kann man das Dokument nicht einfach mit F5 in TeXStudio bauen.
- pdflatex (Referenzen werden gesammelt)
- Biber (Referenzen werden in einem Bibliotheksfile zusammengefasst)
- makeglossaries (Glossarfile wird erstellt)
- pdflatex (Bibliotheksfile und Glossar werden gesammelt und im Dokument richtig eingebunden und verwiesen)
- pdflatex (Inhaltsverzeichnis wird mit korrekten Seitenzahlen gefüllt)
In TeXStudio könnt ihr euch diesen Befehl über Options>Configure TeXStudio>Build>User Commands einrichten
Über den Rollgabelschlüssel an der rechten Seite den neuen Befehl bearbeiten
Und die jeweiligen Befehle per "Add" dem Command hinzufügen
Ausgeführt wird der Befehl über Tools>User>Jeweiliger UserCommand
Jeder Commit auf den Branch "master" oder bei Pull Requests, wird über eine verfügbare CI Pipeline generiert. Dafür muss die spezifische CI Pipeline aber zuerst konfiguriert werden.
Travis
Dafür muss Travis-CI.org oder Travis-CI.com zuerst die diesbezüglichen Berechtigungen erhalten, und für dieses Repo aktiviert sein. Danach muss der Dateiname in travis.yml nachgetragen werden. Damit das Deployment funktioniert, muss ein OAuth Token generiert werden und in Travis hinterlegt werden.
Jeder commit wird über Travis gebaut und bei einer Änderung auf dem Master direkt als "Pre-Release" deployed.
Generiere über die Anleitung von Github ein OAuth Token für dein Konto mit den Berechtigungen repo oder nur public_repo. Danach kopierst du den erhaltenen Hash in eine Environment Variable namens GIT_AUTH in den Einstellungen von Travis für dein jeweiliges Repo.
GH-Workflow
Hierfür muss nichts Spezielles konfiguriert werden. Es ist allerdings zu beachten, dass jeder Run zu den "gratis" runner Minutes dazuzählt. Also kurz überprüfen, damit es keine unschönen Überraschungen gibt.
Die generierte Dokumentation wird bei den Artefakts des Jobs abgelegt.
GitLab
GitLab muss einen Runner haben, damit die CI ausgeführt werden kann. Dafür kann z.B. ein eigener registriert werden: https://docs.gitlab.com/runner/
Mindestanforderungen für diesen sind:
- Docker (CI Benutzer muss Container starten können)
Nicht vergessen, die tags in der Datei .gitlab-ci.yml anzupassen, damit GitLab den richtigen Runner verwendet.
Die generierte Dokumentation wird bei den Artefakts des Jobs abgelegt.
Unsere Versionierung folgt dem Schema v.(Major).(Minor).(Buildnummer - Automatisch), dies aus dem Grund damit die Version sicher immer automatisch inkrementiert wird, und keine identischen Versionsnummern für verschiedene Dokumente existieren können. Major und Minor sind in der Datei .env spezifiziert, während die CI die Buildnummer automatisch einfügt.
Weitere weit verbreitete konfigurationen können auch direkt in der Datei .env gemacht werden. Wie z.B:
FILE_NAME<= Name des generierten Dokuments
In einer ersten Version installierten wir die ganze TeXLive Suite für jeden Build. Dies hat jeweils um die zehn Minuten gedauert. Im Vergleich dazu lief der Build der Datei jeweils maximal eine Minute. Diese Diskrepanz wollten wir angehen. Daher installieren wir eine minimale Umgebung über das Installierskript texlive_install.sh. Damit aber unser Build nicht failt, müssen wir alle fehlenden Packete (und deren Abhängigkeiten) nachinstallieren. Und dazu kommt noch, dass wir die LaTeX-Build Fähigkeit auf Travis hinaufsetzen, da TeX/LaTeX nicht offiziell unterstützt wird.
Am einfachsten sucht man im tlmgr Repository nach der fehlenden Datei/Packet und fügt danach das fehlende Packet zur tlmgr install Linie im Skript.
tlmgr search --global -all <filename here>*...
install:
-
[...]
- tlmgr install [...] new_package
...Das Reglement der HSLU für Wirtschafts- und Bachelorarbeiten verlangt für die Abgabe von WebAbstract und Dokumentation die Einhaltung des PDF/A-Dateiformats. Wir erreich dies über das Packet pdfx und legen über \usepackage[a-2b,latxmp]{pdfx} sowohl den Standard (2A Basic) und eine externe Metadatendatei fest. Damit wird unser Dokument direkt in ein PDF/A2b-PDF kompiliert.
Erstens ist es wichtig, dass die .xmpdata-Datei genau gleich heisst wie die .tex-Datei, da sie ansonsten von pdfx nicht erkannt wird. Zweitens verwenden wir nur ein Subset der verfügbaren Befehle für pdfx, genauere Details sind in der Dokumentation auf CTAN zu finden. Wichtig ist, dass Werte in gewissen Feldern (zum Beispiel die Autoren oder Keywords) mit einem speziellen Separator \sep getrennt werden können. Ein Beispiel:
...
\Author{AUTOR01\sep AUTOR02}
\Title{TITEL}
...Kurzgesagt (unsere Hypothese): Die Schriftart die wir benutzen hat Sonderzeichen welche eine Breite von 0 angeben, was nicht akzeptiert ist. Es gibt nun zwei Arten mit diesem Fehler umzugehen:
- Ignorieren, da das generierte PDF dennoch als PDF/A im gängigen Acrobat Reader erkannt wird
- Eine andere Schriftart verwenden (zum Beispiel die standardmässige von KomaScript verwendete)
Wir hoffen unsere Vorlage nimmt euch ein Bisschen Arbeit ab, damit ihr euch auf die Arbeit konzentrieren könnt. Viel Erfolg! Pascal & Dane