Werkzeuge

Projekte mit antra.and

Ein Skript braucht kein Projekt: antra spiel.ant läuft einfach. Wächst das Programm, kommen Assets, eigene Pakete, C-Bibliotheken und irgendwann Pakete für andere Systeme dazu. Dann beschreibt eine Datei im Projektordner, was das Projekt ist und wie es ausgeliefert wird: die antra.and, wie package.json bei npm oder Cargo.toml bei Rust.

Sie fasst zusammen, was bisher in zwei Dateien stand: native.and (C-Bibliotheken, Kapitel 22) und app.and (antra pack, Kapitel 23). Beide gehen weiterhin; mit einer antra.and braucht man sie nicht mehr.

Ein Projekt anlegen: antra init#

$ antra init "My Game"
created antra.and
created main.ant
created .gitignore
next: cd My Game && antra main.ant

antra init legt den Ordner an (ohne Namen: im aktuellen Ordner) und darin:

• antra.and mit dem Projektnamen aus dem Ordnernamen, bereinigt (My Game wird my-game), Version 0.1.0 und dem Autor aus git config user.name;
• main.ant, außer es gibt schon main.ant oder genau ein anderes Skript, das dann main wird;
• .gitignore mit dist/ und .antra/; eine vorhandene wird nur ergänzt.

antra init überschreibt nie etwas. Gibt es schon eine antra.and, bricht es ab.

Die Datei#

Die angelegte antra.and sieht so aus. Nicht gewählte Optionen stehen auskommentiert darin, als eingebaute Doku:

# antra.and: the project (docs/21-projekte-und-abhaengigkeiten.md)
%Project{
  name: "my-game",
  version: "0.1.0",
  authors: ["Ada"],
  main: "main.ant",

  # C libraries for Antra::FFI; `antra native install` fetches them
  # native: %{raylib: "6.2"},

  # antra pack: ship it
  pack: %{
    targets: ["macos-aarch64"],         # or "windows-x86_64", "linux-x86_64", ...
    # onefile: true,                    # one single file instead of a folder
    # macos_app: true,                  # macOS: a double-clickable .app bundle
    # display_name: "My Game",          # the name in Finder and Dock
    # icon: "icon.png",                 # square PNG (up to 1024 px) or .icns
    # exclude: ["tests", "*.tmp"],      # not shipped
    # cwd: "keep",                      # for command-line tools (default: "main")
  }
}

%Project{...} sagt, was die Datei ist; eine ungetaggte Map %{...} geht auch.

antra pack nimmt name, version und main von oben und den Rest aus pack:; pack: %{main: "..."} startet beim Ausliefern ein anderes Skript. antra native install und antra native list lesen native:. Beide Kommandos suchen die antra.and im aktuellen Ordner und darüber, antra pack also auch aus einem Unterordner heraus.

Tippfehler fallen auf#

Eine Projektdatei ist klein; ein vertippter Schlüssel soll nicht still nichts tun. Unbekannte Schlüssel sind deshalb ein Fehler, mit Vorschlag:

error: unknown key 'dpes' in /home/ada/my-game/antra.and; did you mean 'deps'?
error: unknown key 'onefil' in /home/ada/my-game/antra.and (pack:); did you mean 'onefile'?

Genauso geprüft werden die Form des Namens, die Typen (version ist ein String, pack eine Map, ...) und dass name und version oben stehen und nicht in pack:.

Die Projektwurzel und lib/#

Die Projektwurzel ist der nächste Ordner mit einer antra.and, gesucht ab dem Ordner des gestarteten Skripts aufwärts bis zum Home-Ordner. Ihr lib/ kommt in den Suchpfad, nach dem Skriptordner und dessen lib/, vor der Standardbibliothek. Damit importiert ein Skript in t/, tools/ oder src/ die Pakete des Projekts, ohne -I:

my-game/
  antra.and
  lib/Level.ant          package Level { ... }
  src/main.ant           import Level
  t/level_test.ant       import Level

Auch --check findet die Pakete so. antra pack liefert die antra.and mit aus, damit die gepackte App ihr lib/ ebenso findet.

Eine Bibliothek anlegen#

$ antra init --lib json_kit
created antra.and
created lib/JsonKit.ant
created t/json_kit_test.ant
created .gitignore

Die antra.and einer Bibliothek hat kein main und kein pack, dafür package: "JsonKit". lib/JsonKit.ant enthält ein kleines Paket, t/json_kit_test.ant einen Test dafür, der sofort läuft:

$ antra t/json_kit_test.ant
1..1
ok 1 - hello
# 1 passed; 0 failed

Von app.and und native.and umsteigen#

antra init in einem Ordner mit den alten Dateien übernimmt sie: name, version und main aus app.and nach oben, die übrigen Einstellungen nach pack:, den Inhalt von native.and nach native:. Die alten Dateien bleiben liegen; init sagt, dass man sie löschen kann:

created antra.and
took over app.and; it is ignored now and can be deleted
took over native.and; it is ignored now and can be deleted
next: antra breakout.ant

Gibt es neben der antra.and noch eine app.and oder native.and, gilt die antra.and, und antra pack bzw. antra native warnen:

warning: app.and is ignored because antra.and exists; move its settings into pack:

Ohne antra.and bleibt alles wie bisher.

Was noch kommt#

Die antra.and ist der Anfang einer Projektverwaltung. Geplant sind (Spec: specs/spec_project_file.md):

• deps:: Antra-Bibliotheken von GitHub, einer URL oder einem lokalen Ordner, mit antra install und einer Lock-Datei mit Prüfsummen. Die Einträge werden schon geprüft, aber noch nicht installiert.
• scripts: mit antra run test.
• antra add, antra remove, antra update und ein Paketindex mit kurzen Namen.

Quelle dieser Seite