Package Metadata/de

Other languages:

Einleitung

Beginnend mit FreeCAD Version 0.20 können externe Addons (Arbeitsbereiche, Makros, Voreinstellungspakete, Bundleseingeführt in 1.1 und "andere", allgemeine Werkzeugsammlungeneingeführt in 1.1) mit einer Metadaten-Datei vertrieben werden, die den Inhalt des Pakets beschreibt. Ist die Datei "package.xml" vorhanden, wird sie von FreeCAD ausgelesen und ihre Inhalte in verschiedenen Bereichen der Benutzerschnittstelle verwendet. Derzeit ist es für Arbeitsbereiche und Makros optional und für Voreinstellungspakete erforderlich. Diese Seite dokumentiert das Format dieser Metadaten-Datei. Das Format (und der Inhalt dieser Wikiseite) basiert auf REP 149.

Gesamtdateiformat

Dieses Dokument beschreibt derzeit das Datenformat in Version 1.

Die Metadaten-Datei muss ein gültiges, wohlgeformtes XML 1.0-Dokument sein. Sie muss "package.xml" genannt werden und sie muss im Basisverzeichnis jedes angezeigten Zweiges des Software-Pakets in ihrem git-Speicher vorhanden sein (wie in der Datei AddonCatalog.json des FreeCAD-Addons angegeben). Es wird von jedem Zweig erwartet, eine unabhängige Datei package.xml zu enthalten, die eigens zu dem Zweig gehört. (z.B. sollte ein Entwicklungszweig eine Versionsnummer angeben, die verdeutlicht, dass es sich um einen Entwicklungszweig handelt usw.). Alle bekannten XML-Tags werden kleingeschrieben, aber unbekannte Tags sind "keine" Fehler. Die meisten Tags sind optional und einige betreffen nur bestimmte Arten von Paketinhalten (z.B. stellen nur Aufgabenbereiche ein "classname"-Element zur Verfügung). Nicht benötigte und unbekannte Elemente werden ignoriert.

Jeder in package.xml angegebener Pfadname muss den Schrägstrich ("/") als Verzeichnistrenner verwenden; auf Systemen, die während der Ausführung ein anderes Trennzeichen erwarten (z.B. Windows), wandelt FreeCAD diese automatisch in das korrekte Trennzeichen um.

Inhaltselemente

<package>

Das einzige zulässige Element der obersten Ebene ist <package>, und die Datei darf nur ein <package>-Element enthalten. Unmittelbar darunter befinden sich mehrere erforderliche oder optionale Elemente, die hier definiert sind. Unter dem <package>-Element sind keine weiteren Tags zulässig. 

<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">

Das <package>-Tag ist das eindeutige obere-Ebene-Tag in einer package.xml-Datei. Alle anderen Tags sind darunter verschachtelt.

Attribute

Erforderliche untergeordnete Tags

Das oberste Element <package> muss mindestens die folgenden Tags enthalten:

Optionale untergeordnete Tags

<name>

ERFORDERLICH

Der Name dieses Pakets. Darf nur Zeichen enthalten, die für Dateinamen zulässig sind (unzulässige Zeichen sind /\?%*:|"<> ).

<version>

ERFORDERLICH

Eine Versionsnummer, die entweder dem Semantic Versioning 2.0 Standard (z. B. 1.0.2-beta) oder dem CalVer-Stil (z. B. 2021.12.08) entspricht. Es muss beachtet werden, dass nicht beide Typen verwendet werden können und ein Wechsel zwischen den Typen nicht unterstützt wird. Intern spielt es für den Code keine Rolle, welcher Typ gewählt wird. Beim Vergleich von Versionen wird unabhängig vom Typ ein einfacher numerischer Vergleich zwischen den aufeinanderfolgenden numerischen Komponenten durchgeführt. Es muss beachtet werden, dass dieses Feld nicht leer gelassen werden darf, sondern eine Versionsnummer zugewiesen werden muss. Wenn der Addon-Manager eine Erhöhung der Versionsnummer feststellt, wird den Benutzern die Information "Aktualisierung verfügbar" angezeigt.

<date>

ERFORDERLICH

Das Datum der aktuellen Version im Format JJJJ-MM-TT oder JJJJ.MM.TT.

<description>

ERFORDERLICH

Eine kurze (bis zu mehreren Sätzen) reine Textbeschreibung dieses Pakets. Es werden keine Markups unterstützt.

=== <maintainer>

MINDESTENS EINS ERFORDERLICH (mehrere zulässig)

Der Name der Person, die das Paket verwaltet. Alle Pakete benötigen einen Betreuer. Informationen zu verwaisten Paketen findet man weiter unten.

Attribute

Ein verwaistes Paket ist ein Paket ohne aktuellen Betreuer. Verwaiste Pakete sollten die folgenden Betreuerinformationen verwenden: 

<maintainer email="no-one@freecad.org">No current maintainer</maintainer>

<license>

MINDESTENS EINS ERFORDERLICH (mehrere zulässig)

SPDX-Kurzbezeichnung der Lizenz(en) für dieses Paket, z. B. BSD-2-Clause, GPL-3.0-or-later, LGPL-2.1-or-later. Um die Maschinenlesbarkeit zu verbessern, wird nur die SPDX-Kurzbezeichnung der Lizenz angegeben (siehe die SPDX-Webseite). Bei mehreren Lizenzen müssen mehrere separate Tags verwendet werden. Ein Paket hat mehrere Lizenzen, wenn verschiedene Quelldateien unterschiedliche Lizenzen haben. Jede in den Quelldateien vorkommende Lizenz sollte einen entsprechenden <license>-Tag haben. Für erläuternde Texte zu Lizenzhinweisen verwendet man den <description>-Tag. Um anzugeben, dass keine Lizenz gilt (z. B. "Alle Rechte vorbehalten."), wird dieser Wert auf "UNLICENSED" gesetzt. Um eine benutzerdefinierte Lizenz ohne SPDX-Kennung anzugeben, setzen man diesen Wert auf "SEE LICENSE IN <Dateiname>".

Häufig verwendete Lizenzzeichenfolgen:

Hinweis zur Abwärtskompatibilität: Der Addon-Manager versucht, Lizenzkennungen zu normalisieren, die nicht genau mit einer SPDX-Lizenzzeichenfolge übereinstimmen. Dies führt manchmal zu einer Lizenz-ID, die eine nicht von der FSF-Libre oder OSI genehmigte Lizenz ergibt: Beispielsweise wird "LGPL2" zu "LGPL-2.0" normalisiert, was eine nicht von der FSF-Libre genehmigte Lizenz ist: Vermutlich war "LGPL-2.1-oder-später" gemeint.

Attribute

<content>

ERFORDERLICH

Das <content>-Tag beschreibt den tatsächlichen Inhalt des Pakets. Es hat keine Attribute und enthält eine beliebige Anzahl von untergeordneten Elementen. Diese untergeordneten Elemente können beliebige Tag-Namen haben, von denen nur einige von FreeCAD erkannt werden. FreeCAD unterstützt derzeit die Elemente "workbench", "macro", "preferencepack", "bundle" (eingeführt in 1.1) und "other" (eingeführt in 1.1). Jedes untergeordnete Element wird dann rekursiv durch diesen Standard definiert und enthält einige oder alle Elemente, die für den Wurzelknoten <package> zulässig sind. Zum Beispiel: 

<content>
  <preferencepack>
    <name>Unicorn Sparkles Theme</name>
    <version>1.0.0</version>
    <url type="readme">https://github.com/chennes/FreeCAD-themes/blob/main/Unicorn%20Sparkles%20Theme/Readme.md</url>
    <icon>sparkles.svg</icon>
  </preferencepack>
</content>

Die Existenz der meisten <content>-Elemente impliziert eine Reihe von Unterordnern, einen für jedes Inhaltselement, die genau so benannt sind wie das jeweilige Element. Für das obige Beispiel sieht die Ordnerstruktur des Pakets also wie folgt aus: 

Package Directory/
  package.xml
  Unicorn Sparkles Theme/
    Unicorn Sparkles Theme.cfg
    sparkles.svg
    (the theme's other files)

Zusätzlich zu den anderen Elementen von <package> können Inhaltselemente optional Informationen in den Tags <icon>, <classname> und <file> bereitstellen (technisch gesehen können diese auch für das Wurzel-Tag <package> bereitgestellt werden, dort werden sie jedoch in der Regel nicht verwendet).

Hinweis zur Abwärtskompatibilität: Um eine Umstrukturierung von Paketen zu vermeiden, die vor diesem Metadatenstandard erstellt wurden, ist es zulässig, mit dem optionalen Tag <subdirectory> "./" als Unterverzeichnis für ein Inhaltselement anzugeben. In diesem Fall ist kein Unterverzeichnis erforderlich. Dies entspricht dem System vor Einführung des Standards, bei dem sich eine einzige Workbench an der Spitze der Verzeichnisstruktur befand.

<icon>

ERFORDERLICH für Arbeitsbereiche

Der Pfad zu einer Symboldatei. Handelt es sich um ein Symbol für das Paket der obersten Ebene, ist dieser Pfad relativ zur Datei package.xml selbst. Ist das Symbol ein Element eines <content>-Elements, ist der Pfad relativ zum Ordner des Inhalts. Der Addon-Manager zeigt das Symbol der obersten Ebene als Symbol für das gesamte Paket an. Ist kein Symbol der obersten Ebene vorhanden, wird das erste angegebene Workbench-Symbol als Paketsymbol verwendet.

<subdirectory>

Optional.

Normalerweise wird davon ausgegangen, dass sich ein Inhaltselement in einem Unterverzeichnis mit dem gleichen Namen wie das Element befindet. In einigen Fällen ist es jedoch sinnvoll, das Unterverzeichnis explizit anzugeben. Beispielsweise können sich viele Makros in einem einzigen Unterverzeichnis befinden, aber jedes hat seinen eigenen Eintrag in der Datei package.xml. Es bietet auch Abwärtskompatibilität für Pakete, die älter sind als die Spezifikation des Dateiformats package.xml und nicht der erwarteten Unterverzeichnisstruktur entsprechen. In diesen Fällen wird häufig "<subdirectory>./</subdirectory>" verwendet, um anzugeben, dass sich das Element überhaupt nicht in einem Unterverzeichnis befindet.

<classname>

ERFORDERLICH für Arbeitsbereiche

Für Arbeitsbereiche, der Name der Python-Hauptzugriffsklasse. Dies ist die Klasse, die FreeCAD beim Start zu laden versucht, um das Symbol des Arbeitsbereichs zu finden, das als Member-Variable der Klasse festgelegt werden sollte. Wenn der Arbeitsbereich beispielsweise die folgende Klasse definiert (normalerweise in InitGui.py): 

class MyNewWB:
    Icon = "resources/icon.svg"

dann erwartet die Datei package.xml: 

<classname>MyNewWB</classname>

<file>

Optional

Der Einfachheit halber können hier beliebig viele andere Dateien aufgelistet werden. Die Verwendung hängt von der Art des Inhalts ab. In einem Makro-Inhaltselement ist jeder Dateieintrag ein einzelnes Makro und wird durch den Addon-Manager verknüpft.

<url>

Mehrfach zulässig: "repository" ist erforderlich, und "readme"-Typ wird dringend empfohlen.

Ein Uniform Resource Locator für die Website des Pakets, den Bug-Tracker, das Quell-Repository, den ZIP-Download-Link, die Readme-Datei oder die Dokumentation (wie durch das Attribut "type" angegeben, siehe unten).

Bei der Angabe des Typs "readme" sollte ein direkter Link zu einer gerenderten Version der README-Datei angegeben werden. Auf GitHub ist dies beispielsweise ein Link vom Typ "blob" wie "https://github.com/FreeCAD/FreeCAD-addons/blob/master/README.md" oder auf einer GitLab-Instanz "https://gitlab.com/opensimproject/cfdof/-/blob/master/README.md" (das leicht unterschiedliche URL-Format zwischen den beiden ist zu beachten).

Es empfiehlt sich, <url>-Tags einzufügen, die Benutzer auf die Online-Ressourcen des Pakets verweisen. Die Website ist in der Regel eine Wiki-Seite auf wiki.freecad.org, auf der Benutzer beispielsweise Informationen zum Paket finden und aktualisieren können. Der Addon-Manager listet diese URLs auf und bietet in der Paketbeschreibung anklickbare Links zu ihnen.

Attribute

<author>

Mehrere zulässig

Der Name einer Person, die Autor des Pakets ist, als Anerkennung für ihre Arbeit und für Rückfragen.

Attribute

<depend>

Mehrere zulässig, mindestens eine erforderlich für Bündel (bundles).

Deklariert eine Abhängigkeit von einem anderen FreeCAD-Addon oder einem internen Arbeitsbereich oder einem Python-Paket. Die genannte Abhängigkeit wird zunächst anhand der Liste bekannter Addons überprüft (z. B. derjenigen, die entweder im offiziellen FreeCAD-Addons-Git-Repository oder in einem benutzerdefinierten Repository verfügbar sind). Die Überprüfung erfolgt anhand des kanonischen Namens des Addons. Wenn für dieses Addon eine package.xml-Datei vorhanden ist, ist der Name das <name>-Element dieses Pakets. Es muss eine exakte Übereinstimmung vorliegen. Wenn keine Übereinstimmung gefunden wird, wird die Liste der bekannten internen Workbenches (sowohl installierte als auch deinstallierte) überprüft. Wenn die genannte Abhängigkeit in den beiden vorherigen Schritten nicht gefunden wurde, wird schließlich davon ausgegangen, dass es sich um eine Python-Paketabhängigkeit handelt. Es ist zu beachten, dass noch nicht alle Funktionen im Zusammenhang mit Abhängigkeiten vollständig implementiert sind.

Ein "bundle"-Inhaltselement (eingeführt in 1.1) sollte mehrere "depends"-Zeilen enthalten, eine für jedes externe Add-on, das "gebündelt" wird. Es ist zu beachten, dass die Bündelung nicht wörtlich zu nehmen ist, da das Bündel (bundle) nicht tatsächlich den Quellcode der Abhängigkeit enthalten muss, sondern nur deklariert, dass es vom Add-on-Manager als Teil der Installation des Bündel installiert werden muss.

Attributes

Alle Abhängigkeiten und Beziehungen können ihre Anwendbarkeit auf bestimmte Versionen beschränken. Für jeden Vergleichsoperator kann ein Attribut verwendet werden. Zwei dieser Attribute können zusammen verwendet werden, um einen Versionsbereich zu beschreiben.

Typ: intern

Die folgenden internen Arbeitsbereichs-Typen sind verfügbar:

<conflict>

Mehrere zulässig

Deklariert einen Paketnamen, mit dem dieses Paket in Konflikt steht. Dieses Paket und das in Konflikt stehende Paket sollten nicht gleichzeitig installiert werden.

Attribute

Siehe <depend>.

<replace>

Mehrere zulässig

Deklariert einen Paketnamen, den dieses Paket ersetzen soll.

Attribute

Siehe <depend>.

<tag>

Ein einfacher Text-Tag, der zur Kategorisierung bei der Verwendung eines Paketmanagers verwendet wird. Es können mehrere <tag>-Elemente angegeben werden.

=== <freecadmin>

Die Mindestversion von FreeCAD, die zur Verwendung dieses Pakets/Elements erforderlich ist, als semantische Versionszeichenfolge 2.0 im Format MAJOR.MINOR.BUILD. Dieses Tag kann verwendet werden, um anzugeben, dass ein bestimmter Zweig dieses Add-ons nur Benutzern einer bestimmten FreeCAD-Version (oder höher) angezeigt werden soll. Es kann mit <freecadmax> kombiniert werden, um einen bestimmten gültigen Bereich festzulegen.

=== <freecadmax>

Die maximale Version von FreeCAD, die für die Verwendung des Pakets/Elements erforderlich ist, als semantische Versionszeichenfolge 2.0 im Format MAJOR.MINOR.BUILD. Dieses Tag kann verwendet werden, um anzugeben, dass ein bestimmter Zweig dieses Add-ons nur Benutzern einer bestimmten FreeCAD-Version (oder früher) angezeigt werden soll. Es kann mit <freecadmin> kombiniert werden, um einen bestimmten gültigen Bereich festzulegen. Beachte, dass es sich um eine exakte Versionszeichenfolge handelt. Um anzugeben, dass das Add-on eine gesamte Minor-Version unterstützt, sollte die „Patch”-Komponente als ausreichend große Zahl gewählt werden (z. B. „1.0.99” zur Unterstützung der gesamten 1.0.x-Versionsreihe).

=== <pythonmin>

(Neu in FreeCAD 0.21, in früheren Versionen ignoriert.) Die Mindestversion von Python, die für die Verwendung des Pakets/Elements erforderlich ist, als semantische Version 2.0-Zeichenkette im Format MAJOR.MINOR. Der Addon-Manager erlaubt keine Installation eines Addons auf einem System, auf dem eine ältere Version von Python läuft. Es werden nur Python 3.x-Versionen unterstützt. Obwohl eine dreiteilige Version angegeben werden kann, wird bei der Kompatibilitätsprüfung nur die Minor-Nummer berücksichtigt.

Validierung

Um die package.xml-Datei zu validieren, kann man den "Entwicklermodus" im Addon-Manager aktivieren: Eine boolesche Variable namens "developerMode" in der Parametergruppe "Addons" erstellen und sie auf True setzen: Werkzeuge → Parameter bearbeiten... → BaseApp → Einstellungen → Addons → Entwicklermodus. Nachdem der Addon-Manager die Addons-Datenbank gelesen hat, überprüft er alle verfügbaren package.xml-Dateien auf Fehler.

Kurzanleitung

Für eine Kurzanleitung wie man eine einfache package.xml-Datei erstellt und einen Arbeitsbereich zum Addon-Manager hinzufügt, siehe: Arbeitsbereich zum Addon-Manager hinzufügen.

Beispiele

Es muss beachtet werden, dass Kommentare (der Text zwischen <!-- und -->) vom XML-Parser ignoriert werden und kein erforderlicher Bestandteil des Dateiformats sind. Sie dienen hier nur zu Informationszwecken und können auf Wunsch aus der endgültigen package.xml-Datei weggelassen werden.

Ein einfaches Paket nur für den Arbeitsbereich (zum Beispiel, um eine Metadatendatei zu einem Paket hinzuzufügen, das älter ist als dieses Metadatenformat): 

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>Legacy Workbench</name> <!-- What the Addon Manager displays to users -->
  <description>Text that the Addon Manager shows for the Addon. Any length, but remember that Addon Manager's compact view only shows the first sentence or so.</description>
  <version>1.0.1</version> <!-- Semantic versioning (1.2.3-beta) or CalVer-based, (2022.01.07), don't omit or non-git installations won't see your updates -->
  <date>2022-01-07</date> <!-- Date of the last update to the version number -->
  <maintainer email="your_address@null.com">Your Name</maintainer>
  <license file="LICENSE">LGPL-2.1-or-later</license> <!-- Make sure you actually have this file in your Addon repo if the license requires it -->
  <url type="repository" branch="main">https://github.com/chennes/FreeCAD-Package</url> <!-- Don't forget to update the branch name here -->
  <url type="readme">https://github.com/chennes/FreeCAD-Package/blob/main/README.md</url> <!-- Link to the HTML-rendered README page -->
  <icon>Resources/icons/PackageIcon.svg</icon> <!-- If you include your icon here, you don't have to submit it to the main FreeCAD repo -->

  <content>
    <workbench>
      <classname>MyLegacyWorkbench</classname> <!-- Must match class name in InitGui.py -->
      <subdirectory>./</subdirectory>
    </workbench>
  </content>

</package>

Ein komplexes, aus mehreren Komponenten bestehendes Paket: 

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>Example Package Format</name>
  <description>An example of the package.xml file format</description>
  <version>2022.01</version>
  <date>2022-01-07</date>
  <maintainer email="no-one@freecad.org">No Maintainer</maintainer>
  <license file="LICENSE">GPL-3.0-or-later</license>
  <url type="repository" branch="main">https://github.com/chennes/FreeCAD-Package</url>
  <icon>PackageIcon.svg</icon>

  <content>
    <preferencepack>
      <name>FreeCAD Classic Colors</name>
      <description>FreeCAD default colors for core app and included Mods.</description>
      <version>1.0.0</version>
      <tag>color</tag>
      <tag>stylesheet</tag>
    </preferencepack>
    <workbench>
      <name>Metadata Creation Workbench</name>
      <description>A set of tools to assist in creation of package.xml metadata files</description>
      <classname>MetadataCreationWorkbench</classname>
      <subdirectory>MCW</subdirectory>
      <icon>Resources/mcw.svg</icon>
      <tag>developers</tag>
      <version>0.9.0-alpha</version>
    </workbench>
    <macro>
      <name>Problem Solver 9000</name>
      <description>Deletes all emails in your inbox</description>
      <subdirectory>./</subdirectory>
      <file>PS9000.FCMacro</file>
    </macro>
  </content>

</package>

Ein Paket mit Abhängigkeiten: 

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>Example with Dependencies</name>
  <description>An example of the package.xml file format</description>
  <version>1.0.1-beta3</version>
  <date>2022-01-07</date>
  <maintainer email="no-one@freecad.org">No Maintainer</maintainer>
  <license file="LICENSE">GPL-3.0-or-later</license>
  <url type="repository" branch="main">https://github.com/chennes/FreeCAD-Package</url>
  <icon>PackageIcon.svg</icon>

  <content>
    <workbench>
      <name>Metadata Creation Workbench</name>
      <description>A set of tools to assist in creation of package.xml metadata files</description>
      <classname>MetadataCreationWorkbench</classname>
      <subdirectory>MCW</subdirectory>
      <icon>Resources/mcw.svg</icon>
      <tag>developers</tag>

      <depend>FEM</depend>
      <depend version_gte="0.3.0">Curves workbench</depend>
      <depend version_gte="3.3" version_lt="4">Steel column</depend>

      <!-- As of FreeCAD 0.21, additional information may be provided about dependencies -->
      <depend optional="true" type="python">markdown</depend>
      <depend type="addon">TabBar</depend>

      <!-- If this package is installed, the Addon Manager may warn the user to remove it -->
      <replace>Metadata Creation Workbench Beta</replace>

      <!-- An unresolvable conflict to prevent installation on, e.g. a specific build -->
      <conflict condition="$BuildRevision==24267">Do not use with build 24267</conflict> 

      <!-- Python package dependencies (no support for version information) -->
      <depend>matplotlib</depend>
      <depend>some_other_package</depend> <!-- Assumed to be a Python dependency because it's unrecognized -->
    </workbench>
  </content>

</package>


Power user documentation