Package Metadata/fr

Introduction
A partir de la version 0.20 de FreeCAD, les add-ons externes (ateliers, macros, et kits de préférences) peuvent être distribués avec un fichier de métadonnées décrivant le contenu du package. Si le fichier "package.xml" est présent, il est lu par FreeCAD et son contenu est utilisé dans diverses parties de l'interface utilisateur. Il est actuellement facultatif pour les blocs de travail et les macros, et obligatoire pour les packs de préférences. Cette page documente le format de ce fichier de métadonnées. Le format (et le contenu de cette page Wiki) est basé sur REP 149.

Format général du fichier
Ce document décrit actuellement la version 1 du format de fichier.

Le fichier de métadonnées doit être un document XML 1.0 valide et bien formé. Il doit s'appeler "package.xml", et doit exister dans le répertoire de base du logiciel. Toutes les balises XML comprises sont en minuscules, mais les balises non reconnues ne constituent pas une erreur. La plupart des balises sont facultatives, et certaines ne s'appliquent qu'à certains types de contenu de paquetage (par exemple, seuls les ateliers fournissent actuellement un élément "classname"). Les éléments inutiles ou non reconnus sont ignorés.

Tout chemin de fichier spécifié dans package.xml doit utiliser la barre oblique ("/") comme séparateur de répertoire : sur les systèmes qui attendent un séparateur différent pendant l'exécution (par exemple Windows) FreeCAD convertira automatiquement vers le séparateur correct.

Le seul élément de haut niveau autorisé est, et le fichier ne peut contenir qu'un seul élément. Immédiatement subordonnés à celui-ci se trouvent plusieurs éléments obligatoires ou facultatifs, définis ici. Aucune autre balise n'est autorisée directement sous l'élément.



La balise est la balise unique de premier niveau dans un fichier package.xml. Toutes les autres balises sont imbriquées sous elle.

Attributs

 * format="NUMERO" : Spécifier le format package.xml utilisé. Pour cette interface, vous devez spécifier format="1".
 * xmlns="NAMESPACE" : Spécifie l'espace de noms XML pour ce paquet, et doit être inclus exactement comme indiqué ci-dessus, comme un lien vers https://wiki.freecad.org/Package_Metadata.

Balises enfant requises
L'élément de niveau supérieur doit contenir au moins les balises suivantes :


 * 
 * 
 * 
 * 
 * (plusieurs, mais au moins un)
 * (multiple, mais au moins un) (plusieurs, mais au moins un)
 * (multiple, mais au moins un)
 * (élément conteneur pour les éléments de contenu du paquet)

Balises enfant facultatives

 * (multiple)
 * (multiple)
 * (multiple)
 * (multiple)
 * (multiple)
 * (multiple)
 * 
 * 

OBLIGATOIRE

Le nom de ce paquet. Ne doit contenir que des caractères valides pour les noms de fichiers (les caractères non autorisés sont /\?%*:|"<> ).

OBLIGATOIRE

Un numéro de version qui suit soit la norme de versionnement sémantique 2.0 (par exemple 1.0.2-beta), soit le style CalVer (par exemple 2021.12.08). Notez que vous ne pouvez pas inclure les deux types, et que le passage d'un type à l'autre n'est pas pris en charge. En interne, le code n'a aucune notion du type choisi, lors de la comparaison des versions, il effectue une simple comparaison numérique entre chaque composant numérique successif, quel que soit le type.

OBLIGATOIRE

La date de la version en cours, au format AAAA-MM-JJ ou AAA.MM.JJ.

OBLIGATOIRE

Une description textuelle concise (plusieurs phrases maximum) de ce paquet. Aucun balisage n'est pris en charge.

AU MOINS UN OBLIGATOIRE (plusieurs autorisés)

Le nom de la personne qui maintient le paquet. Tous les paquets nécessitent un mainteneur. Pour les paquets orphelins, voir ci-dessous.

Attributs

 * email="name@domain.tld" (obligatoire) : Adresse électronique du responsable.

Un paquet orphelin est un paquet qui n'a pas de mainteneur attitré. Les paquets orphelins doivent utiliser les informations suivantes sur le mainteneur :

No current maintainer

AU MOINS UN OBLIGATOIRE (plusieurs autorisés)

Nom de la licence pour ce paquet, par exemple BSD, GPL, LGPL. Afin de faciliter la lecture par les machines, n'incluez que le nom de la licence dans cette balise. Pour les licences multiples, plusieurs balises distinctes doivent être utilisées. Un paquet aura plusieurs licences si les différents fichiers sources ont des licences différentes. Chaque licence apparaissant dans les fichiers sources doit avoir une balise correspondante. Pour tout texte explicatif sur les mises en garde relatives aux licences, veuillez utiliser la balise.

Les licences de logiciels libres les plus courantes sont décrites sur le site web de l'OSI.

Les licences les plus utilisées :
 * Apache-2.0
 * BSD
 * Boost Software License
 * GPLv2
 * GPLv3
 * LGPLv2.1
 * LGPLv3
 * MIT
 * Mozilla Public License Version 1.1

Attributs

 * file="FILE" (facultatif) : Un chemin relatif au fichier package.xml contenant le texte complet de la licence. De nombreuses licences exigent l'inclusion du texte de la licence lors de la redistribution du logiciel. Par exemple, la licence Apache, version 2.0, stipule au paragraphe 4.1 : "Vous devez remettre à tout autre destinataire de l'œuvre ou des œuvres dérivées une copie de la présente licence".

OBLIGATOIRE

La balise décrit le contenu réel du paquet. Elle n'a pas d'attributs, et contient un nombre quelconque d'enfants. Ces enfants peuvent avoir des noms de balises arbitraires, dont seuls certains peuvent être reconnus par FreeCAD. FreeCAD supporte actuellement les éléments "workbench", "macro", et "preferencepack". Chaque enfant est ensuite défini récursivement par cette norme, contenant n'importe quel ou tous les éléments autorisés pour le noeud racine. Par exemple :

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

L'existence d'éléments implique un ensemble de sous-dossiers, un pour chaque élément de contenu, nommé exactement comme le nom donné à l'élément. Ainsi, pour l'exemple ci-dessus, la structure des dossiers du paquet est la suivante :

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

Outre les autres éléments de, les éléments de contenu peuvent éventuellement fournir des informations dans les balises , , et (techniquement, celles-ci peuvent également être fournies à la balise racine , mais elles y sont généralement inutilisées).

Backwards-compatibility note: to avoid having to restructure packages that pre-date this metadata standard, the optional  tag is allowed to specify "./" as the subdirectory for a content item, in which case no subdirectory is required. This matches the pre-standard system where a single workbench was located at the top of the directory structure.

REQUIRED for Workbenches

The path to an icon file. If it is an icon for the top-level package this path is relative to the package.xml file itself. If the icon is an element of a item, then the path is relative to the content's folder. The Addon Manager will display the top-level icon as the icon for the overall package. If no top-level icon is present, the first specified workbench icon will be used as the package icon.

Optional.

Normally a content item is assumed to be located in a subdirectory with the same name as the item. In some cases, however, it is useful to explicitly specify the subdirectory. For example, many macros may be located within a single subdirectory, but each have their own entry in the package.xml file. It also provides backwards-compatibility support for packages that predate the package.xml file format specification, and do not follow the expected subdirectory structure. Often in these cases, a " ./ " is used to indicate that the item is not located in a subdirectory at all.

REQUIRED for Workbenches

For workbenches, the name of the Python main entry class.

Optional

Provided for convenience to other tools, any number of other files may be listed here. Their use depends on the type of content. In a macro content item, each file entry is a single macro, and will be linked into the user's Macros installation directory by the Addon Manager.

REQUIRED for Preference Packs, not supported for other content elements

Either "appearance", "behavior", or "combination" describing to end users what type of changes they can expect this preference pack to change.

Multiple allowed

A Uniform Resource Locator for the package's website, bug tracker, source repository, readme file, or documentation. For packages installed via git, the repository is required. Inclusion of the "readme" URL is highly recommended: if the readme is specified and is either a plain text, HTML, or Markdown document (as indicated by the extensions *.txt, *.html, and *.md, respectively), the Addon Manager will download, cache, and display this file and its associated image files.

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.

Attributes

 * type="TYPE" (required): The type should be one of the following identifiers -- "website", "bugtracker", "repository", "readme", or "documentation".
 * 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 another FreeCAD Addon or workbench. Note that not all dependency-related features are fully implemented yet. Does not support Python package dependencies, which should be specified using either a requirements.txt or metadata.txt file (see Workbench creation for details).

Attributes
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.

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.

Attributes
See.

Multiple allowed

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

Attributes
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

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

  Legacy Workbench A package.xml file to add to a workbench that predates the metadata standard. 1.0.1  2022-01-07   Your Name LGPLv2.1 https://github.com/chennes/FreeCAD-Package 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 GPLv3 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:

  Example with Dependencies An example of the package.xml file format 1.0.1-beta3 2022-01-07  No Maintainer GPLv3 <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

Metadata Creation Workbench Beta

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