Kurzfassung Branching-Strategie und ein gesperrter Build-Pool bringen nur so weit. Der Build braucht trotzdem genau die Libraries, die das Projekt pinnt, auf jedem Agent, bei jedem Build.
.library-Dateien vom Netzlaufwerk zu kopieren übersteht weder eine zweite Maschine noch eine zweite TwinCAT-Version noch eine zweite Release-Linie. Beckhoffs TcPkg ist das Werkzeug, das die Maschine aufsetzt: TwinCAT-Workloads und offizielle Beckhoff-Libraries auf der Box. Twinpack ist der projektbezogene Paketmanager: Abhängigkeiten in.Zeugwerk/config.json, mit Version und Branch als Teil der Referenz, damit “neueste aufrelease/1.x” eine echte Antwort ist. In der Pipeline ruft man Twinpack meist nicht von Hand auf:zkmake build --update-snapshotsstellt die Libraries über Twinpack wieder her und kompiliert und testet danach.
Das ist der fünfte Beitrag unserer Serie zu CI/CD für TwinCAT. Die früheren behandeln Build-Tooling-Optionen, CLI-Verteilung auf Nodes, Branching für Maschinensoftware und Exklusiv-Locking auf einer Windows-Build-Farm. Dieser greift die Zeile auf, die in diesen Beiträgen immer wieder vorkommt und nie richtig eigenen Raum bekommt: Dependency Resolution.
Der Build, der seine Libraries nicht findet
Ein TwinCAT-Projekt kompiliert nicht aus dem Quelltext allein. Es braucht jede referenzierte Library auf der Build-Maschine, in der Version, die das Projekt erwartet, für die TwinCAT-Runtime, die auf diesem Agent läuft. Fehlt eines davon, ist der Fehler oft kein sauberes “Package not found”. Es ist ein fehlender Typ, eine falsche Signatur oder eine Library, die still auf das aufgelöst hat, was gerade auf dieser Box installiert war.
Auf einem einzelnen Entwickler-PC bleibt das lange unsichtbar. Libraries sammeln sich auf der Maschine. Das Projekt “baut einfach”. Sobald CI dazukommt, ist die Unsichtbarkeit vorbei. Ein frischer Agent hat keine dieser Libraries. Jemand kopiert einen Ordner vom Netzlaufwerk auf den Node, nennt das erledigt, und eine Weile funktioniert auch das, bis zum zweiten Agent, zur zweiten TwinCAT-Version oder zum Hotfix auf release/1.x, der immer noch die Library-Linie vom letzten Jahr braucht.
Die Fehlermodi sind langweilig und teuer:
- Agent A hat
AcmeConveyor 1.4.0.12. Agent B noch1.3.0.8. Derselbe Commit, unterschiedliche Ergebnisse. - Eine Library wurde auf dem Share aktualisiert und nie gepinnt. Freitags grüner Build, montags Interface-Mismatch auf einer Maschine im Feld.
release/1.xundrelease/2.xbauen auf demselben Pool. Eine globale “Latest”-Installation auf dem Agent kann beides nicht ehrlich bedienen.- Der Ingenieur, der wusste, welches ZIP zu welchem Projekt gehört, geht. Der Share bleibt. Das Wissen geht mit.
Das ist kein TwinCAT-spezifisches Problem. So sieht jedes Ökosystem aus, bevor es einen Paketmanager bekommt. Python hatte das vor pip. JavaScript vor npm. TwinCAT hat es in vielen Betrieben immer noch.
Was “Restore” für TwinCAT heißen muss
In Web-CI ist npm ci oder pip install -r requirements.txt eine gelöste Geste. Für TwinCAT hat diese Geste drei Teile, die allgemeines Tooling nicht kennt:
- Auflösen, welche Package-Versionen das Projekt wirklich will, inklusive transitiver Library-Abhängigkeiten.
- Herunterladen dieser Packages von einer maßgeblichen Quelle in einen bekannten lokalen Cache.
- Installieren in das TwinCAT-Library-Repository auf dieser Maschine, damit der Compiler sie sieht.
Schritt 3 ist der unangenehme. Das TwinCAT-Library-Repository ist kein Ordner, den man beliebig aus jedem Prozess heraus umbauen kann. Headless-Tooling kann Dateien herunterladen und ablegen; die Installation in die laufende TwinCAT-Installation geht üblicherweise über Beckhoffs Automation Interface oder RepTool.exe. Ein CI-tauglicher Paketmanager muss diesen Unterschied offen benennen, statt so zu tun, als reiche ein Dateikopiervorgang.
Außerdem muss er etwas verstehen, das der Branching-Beitrag schon argumentiert hat: TwinCATs eigene Referenzsyntax kennt nur eine exakte vierstellige Version oder *. Es gibt keine eingebaute Schreibweise für “neueste innerhalb von release/1.x”. Sobald zwei Major-Linien im Feld laufen, merkt man diese Lücke sofort.
Beckhoff liefert bereits einen Paketmanager
Seit TwinCAT 3.1.4026 gibt es TcPkg: den TwinCAT Package Manager. TcPkg ist im Kern das Werkzeug, das die Maschine aufsetzt. TwinCAT als Workloads installieren. Offizielle Beckhoff-PLC-Libraries auf die Box ziehen (tcpkg install TwinCAT.XAE.PLC.Lib.…). Einmal einen Entwickler-PC oder CI-Agent so vorbereiten, dass TwinCAT selbst da ist. Twinpack kann Beckhoffs öffentlichen Feed sogar als eine seiner Quellen nutzen, sodass diese Libraries und die eigenen im selben Katalog auftauchen.
Das ist ein anderer Job als projektbezogenes Restore. TcPkg liegt nicht neben dem PLC-Projekt wie package.json oder requirements.txt. Es deklariert nicht pro Repository, welche eigenen Libraries diese Maschinenlinie auf release/1.x braucht, und führt diese Deklaration nicht vor jedem Compile auf jedem Agent erneut aus.
Man kann es in diese Richtung erweitern: eigene Library-Packages in einen TcPkg-Feed legen. Diese Packages sind NuGet-Archive im Chocolatey-Format. Beckhoffs Packaging-Templates legen die .library neben tools/chocolateyinstall.ps1. Die Library wird nicht dadurch installiert, dass sie im Archiv liegt. Sie wird durch dieses PowerShell-Skript installiert, das beim Packen in die nupkg eingebacken wird und auf der Zielmaschine RepTool.exe finden und aufrufen muss. Die veröffentlichten Beispiele machen das mit Pfad-Wildcards gegen einen festen Installationsbaum, ungefähr so:
$RepToolLocations = @(
Join-Path "C:\Program Files (x86)\Beckhoff\TwinCAT\3.1\Components\Plc\Build_4026.*\" `
"Common\RepTool.exe" -Resolve
)
Das funktioniert am Tag, an dem man die nupkg packt, auf einer Maschine, die aussieht wie die getestete. Jahre später, oder auf einem CI-Image mit anderem TwinCAT-Layout, anderem Laufwerk oder einem Build-Ordner, den der Wildcard nicht mehr trifft, schlägt das Skript fehl oder tut nichts. Die .library in dem Package ist weiterhin in Ordnung. Das Package als Ganzes ist unbrauchbar, weil die Installationslogik nicht mehr zur Umgebung passt. Jede Custom-Library, die man so veröffentlicht, versioniert nicht nur die Binary, sondern auch eine eingefrorene Annahme darüber, wo TwinCAT auf jeder Maschine liegt, auf der sie jemals installiert wird.
TcPkg löst auch das Release-Linien-Problem aus dem Branching-Beitrag nicht. Maschinen-Setup kann ein benanntes Beckhoff-Package installieren. Es gibt den eigenen Produkt-Libraries keinen erstklassigen branch: release/1.x mit version: null für “neueste auf dieser Linie”, wiederhergestellt aus einer Datei in Git.
Die Trennung ist also einfach: TcPkg für den Agent. Twinpack für das Projekt.
Twinpacks Antwort: einmal deklarieren, bei jedem Build wiederherstellen
Twinpack ist unser Open-Source-, projektbezogener Paketmanager für TwinCAT-Libraries. Auf der IDE-Seite ist das der Katalog unter dem References-Knoten. Auf der CI-Seite ist es dieselbe Abhängigkeitsdatei, die der Catalog schreibt.
Abhängigkeiten liegen in .Zeugwerk/config.json im Repository. Jeder Package-Eintrag trägt mindestens Namen, Version und Branch:
{
"name": "MyConveyorLib",
"version": null,
"branch": "release/1.x"
}
version: null bedeutet neueste, aber neueste auf diesem Branch. Der Twinpack-Server filtert Kandidaten zuerst nach Branch und wählt dann die höchste Version unter ihnen. Ein Maschinenprojekt auf release/1.x bekommt weiterhin die v1-Wartungsbuilds und niemals 2.0.0. Eine exakte vierstellige Version funktioniert weiterhin, wenn man bitgenau pinnen will.
Das ist das Modell. Die Pipeline muss es trotzdem auf jedem Agent, bei jedem Build, vor dem Compile ausführen. Twinpack selbst stellt das als twinpack restore --headed bereit: aus der Config auflösen, die .library nach .Zeugwerk/libraries herunterladen, über das Automation Interface auf dieser Maschine zur Restore-Zeit in TwinCAT installieren. Der Installationsweg ist kein PowerShell-Skript aus der Package vom letzten Jahr. Frischer Checkout, leerer Agent, dieselben Libraries wie beim Entwickler, der das Projekt zuletzt angefasst hat.
Headed und headless. Standardmäßig läuft twinpack restore headless und arbeitet nur auf Dateien. Das reicht zum Herunterladen und Ablegen der Packages; für die Installation in das lebende TwinCAT-Library-Repository auf dem Agent reicht es nicht. Dafür braucht man --headed (Automation Interface) oder danach einen eigenen Beckhoff-RepTool-Schritt. In der Praxis nehmen wir headed. Das Automation Interface ist auf der Build-Maschine ohnehin da, weil TwinCAT dort ohnehin da ist, und headed Restore ist der Weg, der zum Compile selbst passt.
Quellen sind konfigurierbar. Derselbe Restore funktioniert gegen:
- den Twinpack-Server (öffentliche Open-Source-Packages; Enterprise-Kunden bekommen privates Hosting und Feature-Branches),
- den eigenen NuGet-Server für On-Prem-Libraries, die das Netz nicht verlassen dürfen,
- das Beckhoff Library Repository ab TwinCAT 3.1.4026+.
Das Muster heißt also nicht “alles zu Zeugwerk hochladen”. Es heißt “ein deklariertes Abhängigkeitsset, wiederhergestellt aus den Quellen, die die Security-Policy zulässt.”
Was man tatsächlich in die Pipeline schreibt
Man könnte twinpack restore --headed als eigenen Schritt verdrahten und danach das Compile-Tool aufrufen. Das ist ehrlich und funktioniert. In den Setups, die wir betreiben und ausliefern, ist Restore keine eigene Zeile in der Pipeline. Es ist das Erste, was zkmake macht, wenn man mit Snapshot-Updates baut:
build:
tags: [windows]
script:
- scoop update zkmake zkdoc
- zkmake build --update-snapshots --kill-all
--update-snapshots ist der Schalter, der zkmake anweist, Packages über Twinpack wiederherzustellen (Download, dann Installation über das Automation Interface), bevor es kompiliert und Tests ausführt. Der Autor der Pipeline sieht einen Befehl. Darunter gehört die Auflösung weiterhin Twinpack: dieselbe config.json, dasselbe branch-bewusste “Latest”, derselbe Cache unter .Zeugwerk/libraries.
Diese Trennung ist Absicht und passt zu dem, wofür diese Serie da ist. Twinpack ist das offene Stück, das Abhängigkeitsidentität über Entwickler, Agents und Release-Linien hinweg portabel macht. zkmake ist die Build-CLI, die daraus ohne Handmontage von Restore, Install, Compile und Test eine grüne oder rote Pipeline macht. Der Scoop-Beitrag hat diese Job-Form schon für die Tool-Verteilung gezeigt; dieser Beitrag erklärt, warum die Restore-Hälfte dieses Befehls existiert.
Ein paar Details zählen trotzdem, egal welchen Weg man nimmt:
- Die Config committen, nicht die Binaries.
.Zeugwerk/config.jsongehört in Git. Der Download-Cache unter.Zeugwerk/librariesüblicherweise nicht. - Pinnen, wenn man pinnt meint. Exakte Versionen für ausgelieferte Maschinenlinien;
nullplus ein expliziterbranchfür “diese Release-Linie verfolgen.” - TwinCAT-
*-Referenzen nicht als Wahrheitsquelle lassen. Twinpack kann wiederherstellen, was die Config sagt. Es kann kein Projekt retten, das TwinCAT weiterhin nach “was gerade auf diesem Agent das Neueste ist” fragt. - Bei jedem Build wiederherstellen, nicht einmal beim Aufsetzen des Agents. Agents werden gewischt, gepatcht und ersetzt. Die Config ist der dauerhafte Beleg.
Warum das erst greift, wenn der Rest der Serie steht
Restore ersetzt die früheren Entscheidungen nicht. Es macht sie betriebsfähig.
Ohne Branching weist branch: "release/1.x" in der Config auf kein reales Ziel. Der Branching-Beitrag ist der Ort, an dem diese Linie real wird.
Ohne versioniertes Tooling auf dem Node ist man wieder bei “irgendeinem Twinpack- oder zkmake-Binary, das jemand auf den Agent kopiert hat.” Scoop hält diese CLIs über die Farm hinweg gepinnt und authentifiziert.
Ohne Exklusiv-Locking treten zwei Restores und zwei Compiles auf derselben Windows-Maschine irgendwann in dasselbe TwinCAT-Library-Repository. Der Locking-Beitrag ist der Grund, warum diese Maschine für die gesamte Dauer des Builds exklusiv gehört.
Anders gesagt: Die Schichtentabelle aus dem Locking-Beitrag ist kein Menü. Dependency Resolution ist die Zeile, die zuletzt auffällt und am teuersten wehtut, weil alles darüber grün aussehen kann, während still die falsche Library gewinnt.
Wo das vorerst steht
Mit Restore hat eine TwinCAT-CI-Pipeline die Teile, die entscheiden, ob ein grüner Build ehrlich ist: ein Branching-Modell, das zu den Maschinen im Feld passt, Agents, die sich nicht gegenseitig in die Quere kommen, Tools in bekannter Version und Libraries, die auf jedem Node gleich aufgelöst werden. Was sie noch nicht entscheidet: wann dieser grüne Build zum Package wird, das andere nehmen dürfen. Das ist die Publish-Topologie: Build, Staging, Deploy. Eigener Beitrag, dieselbe Serie.
Twinpack ist kostenlos und Open Source. Die Produktseite und die Docs decken IDE-Setup, Quellen und die vollständige CLI ab. zkmake und der Rest von DevTools liegen darüber, wenn Restore und Build ein Pipeline-Schritt sein sollen. Wer eines von beiden lieber in eine echte Farm verdrahtet haben will als in eine Laptop-Demo, genau dafür arbeiten wir mit Teams.
