Package Metadata/pl

Wprowadzenie
Począwszy od wersji 0.20 programu FreeCAD, zewnętrzne dodatki (środowiska pracy, makra i pakiety preferencji) mogą być dystrybuowane z plikiem metadanych opisującym zawartość pakietu. Jeżeli plik "package.xml" jest obecny, jest on odczytywany przez FreeCAD i jego zawartość jest wykorzystywana w różnych częściach interfejsu użytkownika. Obecnie jest on opcjonalny dla środowisk pracy i makrodefinicji, a wymagany dla pakietów preferencji. Ta strona dokumentuje format tego pliku metadanych. Format (i zawartość tej strony Wiki) są oparte na REP 149.



Ogólny format pliku
Ten dokument opisuje obecnie format pliku w wersji 1.

Plik metadanych musi być prawidłowym, dobrze uformowanym dokumentem XML 1.0. Musi on nosić nazwę "package.xml" i musi istnieć w katalogu bazowym głównej gałęzi pakietu oprogramowania (jak określono w pliku FreeCAD-addons .gitmodules) w jego repozytorium git. Tylko plik package.xml z głównej gałęzi jest brany pod uwagę przez Menadżera dodatków. Wszystkie zrozumiałe znaczniki XML są pisane małymi literami, ale nierozpoznane znaczniki nie stanowią błędu. Większość znaczników jest opcjonalna, a niektóre mają zastosowanie tylko do niektórych typów zawartości pakietów (na przykład, tylko środowiska pracy zapewniają obecnie element "classname"). Niepotrzebne lub nierozpoznane elementy są ignorowane.

Każda ścieżka pliku określona w package.xml musi używać ukośnika ("/") jako separatora katalogu: w systemach, które oczekują innego separatora podczas wykonywania (np. Windows) FreeCAD automatycznie przekonwertuje go na prawidłowy separator.



Jedynym dozwolonym elementem najwyższego poziomu jest, a plik może zawierać tylko jeden element. Bezpośrednio pod nim znajduje się kilka wymaganych lub opcjonalnych elementów, zdefiniowanych tutaj. Żadne inne znaczniki nie są dozwolone bezpośrednio pod elementem.



Znacznik jest unikalnym znacznikiem najwyższego poziomu w pliku package.xml. Wszystkie inne znaczniki są zagnieżdżone pod nim.

Atrybuty

 * format="NUMBER": Określenie używanego formatu package.xml. Dla tego interfejsu należy określić format="1".
 * xmlns="NAMESPACE": Określa przestrzeń nazw XML dla tego pakietu i musi być dołączona dokładnie tak, jak pokazano powyżej, jako link do https://wiki.freecad.org/Package_Metadata.



Wymagane identyfikatory podrzędne
Element najwyższego poziomu musi zawierać co najmniej następujące znaczniki:


 * 
 * 
 * 
 * 
 * (wiele, ale co najmniej jeden)
 * (wiele, ale co najmniej jeden)
 * 
 * (element kontenera dla elementów zawartości pakietu)



Opcjonalne identyfikatory podrzędne

 * (wiele)
 * (wiele)
 * (wiele)
 * (wiele)
 * (wiele)
 * (wiele)
 * 
 * 
 * 

WYMAGANE

Nazwa tego pakietu. Musi zawierać tylko znaki, które są prawidłowe dla nazw plików (niedozwolone znaki to /\?%*:|"<> ).

WYMAGANE

Numer wersji zgodny ze standardem semantic versioning 2.0 (np. 1.0.2-beta) lub CalVer style (np. 2021.12.08). Należy pamiętać, że nie można dołączyć obu typów, a przełączanie między typami nie jest obsługiwane. Wewnętrznie kod nie ma pojęcia, który typ został wybrany, podczas porównywania wersji wykonuje proste porównanie numeryczne między każdym kolejnym składnikiem numerycznym, niezależnie od typu. Należy pamiętać, że nie można pozostawić tego pola pustego, należy przypisać jakiś numer wersji. Gdy Menedżer dodatków wykryje podwyższenie numeru wersji, wyświetli użytkownikom informację "dostępna aktualizacja".

WYMAGANE

Data bieżącej wersji, w formacie RRRR-MM-DD lub RRRR.MM.DD.

WYMAGANE

Zwięzły (do kilku zdań) tekstowy opis tego pakietu. Nie są obsługiwane żadne znaczniki.

CO NAJMNIEJ JEDEN WYMAGANY (dopuszczalna jest większa liczba)

Imię i nazwisko osoby opiekującej się pakietem. Wszystkie pakiety wymagają opiekuna. Dla osieroconych pakietów patrz uwagi poniżej.

Atrybuty

 * email="name@domain.tld" (wymagane): Adres e-mail opiekuna.

Osierocony pakiet to taki, który nie ma aktualnego opiekuna. Osierocone pakiety powinny używać następujących informacji o opiekunie:

No current maintainer

CO NAJMNIEJ JEDEN WYMAGANY (dopuszczalna jest większa liczba)

Skrócony identyfikator SPDX licencji dla tego pakietu, np. BSD-2-Clause, GPL-3, LGPL-2.1. W celu ułatwienia odczytu maszynowego, należy dołączyć tylko krótki identyfikator SPDX licencji (patrz strona SPDX). W przypadku wielu licencji należy użyć wielu oddzielnych znaczników. Pakiet będzie miał wiele licencji, jeśli różne pliki źródłowe mają różne licencje. Każda licencja występująca w plikach źródłowych powinna mieć odpowiedni znacznik. W przypadku tekstu objaśniającego zastrzeżenia licencyjne należy użyć znacznika.

Powszechnie używane ciągi nazw licencji:
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)
 * (Dedykacja domeny publicznej)

Atrybuty

 * (opcjonalnie): Ścieżka do pliku zawierającego pełny tekst licencji. Wiele licencji wymaga dołączenia tekstu licencji podczas redystrybucji oprogramowania. Np. Licencja Apache, wersja 2.0 stwierdza w paragrafie 4.1: "Musisz przekazać każdemu innemu odbiorcy Utworu lub Utworów Pochodnych kopię niniejszej Licencji".

WYMAGANE

Znacznik opisuje rzeczywistą zawartość pakietu. Nie posiada atrybutów i zawiera dowolną liczbę elementów podrzędnych. Te elementy podrzędne mogą mieć dowolne nazwy znaczników, z których tylko niektóre mogą być rozpoznawane przez FreeCAD. FreeCAD obsługuje obecnie elementy "workbench", "macro" i "preferencepack". Każdy element potomny jest następnie definiowany rekurencyjnie przez ten standard, zawierający dowolne lub wszystkie elementy dozwolone dla węzła głównego. Na przykład:

Unicorn Sparkles Theme 1.0.0    https://github.com/chennes/FreeCAD-themes/blob/main/Unicorn%20Sparkles%20Theme/Readme.md     sparkles.svg

Istnienie elementów implikuje zestaw podfolderów, po jednym dla każdego elementu zawartości, nazwanych dokładnie tak, jak dana nazwa elementu. Tak więc w powyższym przykładzie struktura folderów pakietu jest następująca:

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

Oprócz innych elementów, elementy zawartości mogą opcjonalnie dostarczać informacji w identyfikatorach , i (technicznie mogą one być również dostarczane do głównego identyfikatora , ale generalnie nie są tam używane).

Uwaga dotycząca kompatybilności wstecznej: aby uniknąć konieczności restrukturyzacji pakietów sprzed tego standardu metadanych, opcjonalny identyfikator  może określać "./" jako podkatalog dla elementu zawartości, w którym to przypadku nie jest wymagany żaden inny katalog podrzędny. Odpowiada to systemowi sprzed standardu, w którym pojedynczy obszar roboczy znajdował się na szczycie struktury katalogów.

WYMAGANE dla środowisk pracy

Ścieżka do pliku ikony. Jeśli jest to ikona dla pakietu najwyższego poziomu, ścieżka jest względna do samego pliku package.xml. Jeśli ikona jest elementem elementu, ścieżka jest względna do folderu zawartości. Menedżer dodatków wyświetli ikonę najwyższego poziomu jako ikonę całego pakietu. Jeśli nie ma ikony najwyższego poziomu, pierwsza określona ikona środowiska pracy zostanie użyta jako ikona pakietu.

Opcjonalnie.

Zwykle zakłada się, że element zawartości znajduje się w podkatalogu o tej samej nazwie co element. W niektórych przypadkach przydatne jest jednak wyraźne określenie podkatalogu. Na przykład, wiele makr może znajdować się w jednym podkatalogu, ale każde z nich ma swój własny wpis w pliku package.xml. Zapewnia również wsparcie kompatybilności wstecznej dla pakietów, które poprzedzają specyfikację formatu pliku package.xml i nie są zgodne z oczekiwaną strukturą podkatalogów. Często w takich przypadkach używa się zapisu " ./ ", aby wskazać, że element w ogóle nie znajduje się w katalogu podrzędnym.

WYMAGANE dla środowisk pracy

W przypadku środowisk pracy, nazwa głównej klasy wejściowej Python. Jest to klasa, którą FreeCAD będzie próbował załadować podczas uruchamiania, aby zlokalizować ikonę stołu warsztatowego, która powinna być ustawiona jako zmienna członkowska klasy. Na przykład, jeśli stół warsztatowy definiuje następującą klasę (zwykle w InitGui.py):

wtedy plik package.xml oczekuje:

MyNewWB

Opcjonalnie

Dla wygody innych narzędzi można tu wymienić dowolną liczbę innych plików. Ich użycie zależy od typu zawartości. W elemencie zawartości makra każdy wpis pliku jest pojedynczym makrem i zostanie połączony z katalogiem instalacyjnym makrodefinicji użytkownika przez Menedżera dodatków.

Dozwolonych jest wiele typów: "repozytorium" jest wymagane, a typ "readme" jest wysoce zalecany.

Ujednolicony lokalizator zasobów (Uniform Resource Locator) dla strony internetowej pakietu, narzędzia do śledzenia błędów, repozytorium źródłowego, linku do pobrania pliku zip, pliku readme lub dokumentacji (zgodnie z atrybutem "type", patrz poniżej).

When specifying the "readme" type, a direct link to a rendered version of the README should be provided. For example, on GitHub, this is a "blob"-type link such as "https://github.com/FreeCAD/FreeCAD-addons/blob/master/README.md", or on a GitLab instance, "https://gitlab.com/opensimproject/cfdof/-/blob/master/README.md" (note the slightly different URL format between the two).

It is a good idea to include tags pointing users to your package's online resources. The website is commonly a wiki page on wiki.freecad.org where users can find and update information about the package, for example. The Addon Manager lists these URLs and provides clickable links to them in the package description.

Atrybuty

 * type="TYPE" (required): The type should be one of the following identifiers: "website", "bugtracker", "repository", "readme", "documentation", or "discussion".
 * branch="BRANCH" (required for type="repository"): The name of the branch to check out to obtain this package. Typically the name of your main development branch. May also specify any other type of git reference, e.g. a tag or specific commit.

Multiple allowed

The name of a person who is an author of the package, as acknowledgement of their work and for questions.

Attributes

 * email="name@domain.tld" (optional): Email address of author.

Multiple allowed

Declares a dependency on another FreeCAD Addon or internal workbench, or Python package. The named dependency is first checked against the list of known Addons (e.g. those available either from the official FreeCAD Addons git repository, or those in a custom user-specified repository). The check is against the canonical name of the Addon. If a package.xml file is present for that Addon, the name is that package's element. An exact match is required. If no match is found it is checked against the list of known internal workbenches (both installed and uninstalled). Finally, if the named dependency has not been located in the previous two steps it is assumed to be a Python package dependency. Note that not all dependency-related features are fully implemented yet.

Atrybuty
All dependencies and relationships may restrict their applicability to particular versions. For each comparison operator an attribute can be used. Two of these attributes can be used together to describe a version range.


 * version_lt="VERSION" (optional): The dependency to the package is restricted to versions less than the stated version number.
 * version_lte="VERSION" (optional): The dependency to the package is restricted to versions less or equal than the stated version number.
 * version_eq="VERSION" (optional): The dependency to the package is restricted to a version equal than the stated version number.
 * version_gte="VERSION" (optional): The dependency to the package is restricted to versions greater or equal than the stated version number.
 * version_gt="VERSION" (optional): The dependency to the package is restricted to versions greater than the stated version number.
 * condition="CONDITION_EXPRESSION": Every dependency can be conditional on a condition expression. If the condition expression evaluates to "true" the dependency is used and considered as if it doesn't have a condition attribute. If the condition expression evaluates to "false" the dependency is ignored and considered as if it doesn't exist. The expression must be a valid FreeCAD Expression (i.e. Python syntax), and may refer to the variables "$BuildVersionMajor", "$BuildVersionMinor", and "$BuildRevision" representing the version of FreeCAD currently running.
 * optional="true|false": If "optional" is "true", then the dependency is treated as optional when the Addon is installed using the Addon Manager. In general this means that a failure to install the dependency does not prevent the Addon from installing, and the user may be prompted about whether they want to install it. Versions of FreeCAD prior to 0.21 do not recognize this attribute and will ignore it.
 * type="automatic|addon|internal|python": Optional, defaults to "automatic". Indicates what this dependency statement refers to. "addon" is for external addons, "internal" is for internal workbenches (e.g. "arch", "sketcher", etc.), and "python" indicates a Python package dependency. Versions of FreeCAD prior to 0.21 do not use this attribute, and "automatic" is always assumed.

Multiple allowed

Declares a package name with which this package conflicts. This package and the conflicting package should not be installed at the same time.

Atrybuty
See.

Multiple allowed

Declares a package name that this package is intended to replace.

Atrybuty
See.

A simple text tag used for categorization when using a package manager. Multiple elements may be specified.

The minimum version of FreeCAD required to use this package/element, as a semantic version 2.0 string in the format MAJOR.MINOR.BUILD

The maximum version of FreeCAD required to use package/element, as a semantic version 2.0 string in the format MAJOR.MINOR.BUILD

(New in FreeCAD 0.21, ignored by previous versions.) The minimum version of Python required to use package/element, as a semantic version 2.0 string in the format MAJOR.MINOR. The Addon Manager will not permit an Addon to be installed on a system running a version of Python before this one. Only Python 3.x versions are supported. Although you may specify a three-component version, only the minor number is considered during the compatibility check.

Sprawdzanie poprawności
To validate your package.xml file you can enable "developer mode" in the Addon Manager: create a boolean variable called "developerMode" in the "Addons" parameter group and set it to True:. When the Addon Manager has finished reading the Addons database it will examine all available package.xml files for errors.

Quick guide
For a quick guide on how to create a basic package.xml file and add a workbench to the Addon Manager see: Add Workbench to Addon Manager.

Examples
Note that comments (the text between and ) are ignored by the XML parser, and are not a required part of the file format. They are provided here for information purposes and may be omitted from the final package.xml if desired.

A simple workbench-only package (for example, to add a metadata file to a package that predates this metadata format):

  Legacy Workbench 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. 1.0.1  2022-01-07   Your Name LGPL-2.1-or-later https://github.com/chennes/FreeCAD-Package https://github.com/chennes/FreeCAD-Package/blob/main/README.md  Resources/icons/PackageIcon.svg

MyLegacyWorkbench ./

A complex, multi-component package:

  Example Package Format An example of the package.xml file format 2022.01  2022-01-07   No Maintainer GPL-3.0-or-later https://github.com/chennes/FreeCAD-Package PackageIcon.svg

FreeCAD Classic Colors FreeCAD default colors for core app and included Mods. 1.0.0      color stylesheet Metadata Creation Workbench A set of tools to assist in creation of package.xml metadata files MetadataCreationWorkbench MCW Resources/mcw.svg developers 0.9.0-alpha Problem Solver 9000 Deletes all emails in your inbox ./      PS9000.FCMacro

A package with dependencies:

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

Metadata Creation Workbench A set of tools to assist in creation of package.xml metadata files MetadataCreationWorkbench MCW Resources/mcw.svg developers

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

<depend optional="true" type="python">markdown TabBar

Metadata Creation Workbench Beta

<conflict condition="$BuildRevision==24267">Do not use with build 24267

matplotlib some_other_package