Werkzeuge

Native Bibliotheken mit `antra native`

Pakete wie Antra::Raylib, Antra::SDL oder Antra::SQLite laden eine C-Bibliothek über Antra::FFI. Damit ein Programm läuft, muss diese Bibliothek auf dem Rechner liegen — und für ein Release auch beim Nutzer. antra native nimmt dir beides ab: Es lädt die passenden Bibliotheken für jedes Betriebssystem in dein Projekt und packt sie samt Lizenztexten für ein Release zusammen.

Kurz: drei Kommandos#

antra native install          # Bibliotheken aus native.and für diesen Rechner holen
antra native list             # was ist wofür installiert?
antra native bundle           # Release-Ordner dist/ mit Bibliotheken + Lizenzen

antra native sucht native.and im aktuellen Verzeichnis und darüber, du kannst es also aus jedem Unterordner des Projekts aufrufen.

Die Datei `native.and`#

Mit einer Projektdatei antra.and (Kapitel 21) steht derselbe Inhalt dort unter native:; antra native liest dann sie und ignoriert eine native.and daneben.

Im Projektordner listet native.and die Bibliotheken mit Version — im Datenformat AND, # leitet Kommentarzeilen ein:

# native Bibliotheken für das Spiel
%{raylib: "6.2", sdl2: "2.32.10", sqlite: "3.50.4"}

Wer möchte, schreibt das Tag dazu, dann sagt die Datei selbst, was sie ist: %NativeDeps{raylib: "6.2"}. Ein anderes Tag ist ein Fehler.

Wo die Bibliotheken landen#

antra native install legt alles unter native/<os>-<arch>/ neben native.and ab, zum Beispiel:

mein-spiel/
  native.and
  src/main.ant
  native/
    linux-x86_64/
      libraylib.so
      licenses/raylib.txt
      lock.and

Antra::FFI sucht beim Laden automatisch in native/<os>-<arch>/ — neben dem Skript und bis zu drei Ordner darüber (also auch für src/main.ant) sowie unter jedem -I-Verzeichnis. Im Programm ändert sich nichts:

import Antra::Raylib as RL
val app = RL.window("Demo", 640, 360).!   # findet native/<plattform>/libraylib.so

lock.and merkt sich, welche Version installiert ist. Ein zweites install meldet dann nur up to date; --force installiert neu.

Die Plattform des laufenden Programms liefert System.platform() ("linux-x86_64"), einzeln System.os() (:linux, :macos, :windows) und System.arch() (:x86_64, :aarch64).

Für andere Betriebssysteme installieren#

Mit --target holst du die Bibliotheken für ein anderes System, etwa um vom Linux-Rechner aus ein Windows-Release zu bauen:

antra native install --target windows-x86_64
antra native install --target all       # alle bekannten Plattformen

Plattformen: linux-x86_64, linux-aarch64, macos-x86_64, macos-aarch64, windows-x86_64.

Ein Release bauen: `antra native bundle`#

antra native bundle --out dist

kopiert die installierten Bibliotheken aller Plattformen nach dist/native/<os>-<arch>/ und schreibt dist/THIRD-PARTY-NOTICES.txt mit den Lizenztexten. Lege deine Skripte daneben (oder dist/ in dein Projekt), dann findet Antra::FFI die Bibliotheken auch beim Nutzer. Mit --target beschränkst du das Bundle auf einzelne Plattformen.

Bibliotheken, die von einem System selbst kommen (siehe unten), landen nicht im Bundle; bundle sagt das in seiner Ausgabe.

Ein komplettes, startfertiges Programm — antra selbst, deine Skripte, Assets und die Bibliotheken als ein Zip pro System — baut antra pack, siehe 23-programme-weitergeben.md.

Mitgelieferte Rezepte#

Bibliothek	Linux	macOS	Windows	Lizenz
`raylib`	Release von GitHub	Release von GitHub	Release von GitHub	zlib
`sdl2`	Systempaket	Systempaket (Homebrew)	Release von GitHub	zlib
`sqlite`	Systempaket	im System enthalten	Download von sqlite.org	Public Domain

Wo es keine offiziellen Fertigpakete gibt, nennt install den passenden Installationsbefehl (sudo apt install libsdl2-2.0-0, brew install sdl2, …) statt etwas herunterzuladen.

Eigene Bibliotheken#

Statt einer Versionsnummer darf ein Eintrag ein ganzes Rezept sein — für jede Bibliothek, die als Archiv (.zip, .tar.gz, .tar) im Netz liegt:

%{mylib: %{version: "1.4", license: "MIT", homepage: "https://mylib.example",
           platforms: %{"linux-x86_64" => %{url: "https://mylib.example/mylib-{version}-linux.tar.gz",
                                          files: %{"libmylib.so" => "mylib-{version}/lib/libmylib.so"},
                                          license_file: "mylib-{version}/LICENSE"},
                        "windows-x86_64" => %{url: "https://mylib.example/mylib-{version}-win64.zip",
                                            files: %{"mylib.dll" => "mylib-{version}/bin/mylib.dll"}}}}}

url: das Archiv; {version} wird ersetzt. Eine URL ohne http(s):// ist ein lokaler Pfad.
files: installierter Name ⇒ Pfad im Archiv. Den installierten Namen wählst du so, wie FFI.open ihn sucht (lib<name>.so, lib<name>.dylib, <name>.dll).
license_file: Lizenztext im Archiv; fehlt er, steht license im Bundle.
system (optional): %{linux: "…", macos: "…"}, ein Installationshinweis für Plattformen ohne Download.

Cache, Mirror und Proxys#

Downloads werden einmal pro Rechner zwischengespeichert: in ANTRA_CACHE, sonst $XDG_CACHE_HOME/antra, ~/.cache/antra bzw. %LOCALAPPDATA%\antra\cache.
ANTRA_DEPS_MIRROR ersetzt die Download-Adresse bis zum Dateinamen — ein Verzeichnis oder eine URL. So geht es offline oder über einen Firmen-Mirror.
Der eingebaute HTTP-Client nutzt die Zertifikate des Systems und HTTPS_PROXY. Kommt er durch einen Proxy nicht durch, versucht antra native es automatisch mit curl (unter Windows 10+, macOS und Linux vorhanden).

Lizenzen#

Alle mitgelieferten Rezepte erlauben das Weitergeben der Bibliotheken in eigenen Programmen. bundle legt die nötigen Texte in THIRD-PARTY-NOTICES.txt ab:

zlib (raylib, SDL2): praktisch keine Pflichten; eine Nennung ist erwünscht, aber nicht nötig. Geänderte Quellen als geändert kennzeichnen.
Public Domain (SQLite): keine Pflichten.
Bei eigenen Rezepten bist du selbst dafür verantwortlich, dass die Lizenz das Weitergeben erlaubt und welche Texte mitmüssen (z. B. MIT/BSD: Lizenztext beilegen).

Gibst du auch den Interpreter selbst weiter, gehört dessen THIRD-PARTY-NOTICES.txt (PCRE2, Boehm-GC) mit ins Release.

Bausteine für eigene Werkzeuge#

antra native ist selbst in Antra geschrieben (Antra::NativeDeps) und nutzt drei kleine Pakete, die auch für eigene Skripte taugen:

import Antra::Net::Fetch
import Antra::Archive
import Antra::System

Fetch.download("https://example.org/data.tar.gz", "data.tar.gz").!
Archive.extract("data.tar.gz", "data").!     # .zip, .tar, .tar.gz/.tgz
println(System.platform())                   # "linux-x86_64"

Antra::NativeDeps lässt sich auch direkt aufrufen, etwa NativeDeps.install(dir, targets: ["windows-x86_64"]) oder NativeDeps.bundle(dir, "dist"); beide liefern %Ok[zeilen] bzw. %Err[...].

Quelle dieser Seite

Native Bibliotheken mit antra native