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

Note de rétrocompatibilité : pour éviter de devoir restructurer les paquets antérieurs à cette norme de métadonnées, la balise facultative  est autorisée à spécifier "./" comme sous-répertoire pour un élément de contenu, auquel cas aucun sous-répertoire n'est nécessaire. Cela correspond au système pré-standard où un seul poste de travail était situé au sommet de la structure des répertoires.

OBLIGATOIRE pour les ateliers

Le chemin d'accès à un fichier d'icône. S'il s'agit d'une icône pour le paquet de premier niveau, ce chemin est relatif au fichier package.xml lui-même. Si l'icône est un élément d'un élément, le chemin est relatif au dossier du contenu. Le gestionnaire d'addons affichera l'icône de niveau supérieur comme l'icône du paquetage global. Si aucune icône de niveau supérieur n'est présente, la première icône de banc de travail spécifiée sera utilisée comme icône du paquet.

Optionnel.

Normalement, un élément de contenu est supposé se trouver dans un sous-répertoire portant le même nom que l'élément. Dans certains cas, cependant, il est utile de spécifier explicitement le sous-répertoire. Par exemple, de nombreuses macros peuvent se trouver dans un seul sous-répertoire, mais chacune a sa propre entrée dans le fichier package.xml. Cela fournit également un support de rétrocompatibilité pour les paquets antérieurs à la spécification du format de fichier package.xml, et qui ne suivent pas la structure de sous-répertoire attendue. Souvent, dans ces cas, un " ./ " est utilisé pour indiquer que l'élément n'est pas situé dans un sous-répertoire du tout.

OBLIGATOIRE pour les ateliers

Pour les ateliers, le nom de la classe d'entrée principale en Python.

Optionnel.

Fournis pour la convivialité d'autres outils, un certain nombre d'autres fichiers peuvent être répertoriés ici. Leur utilisation dépend du type de contenu. Dans un élément de contenu macro, chaque entrée de fichier est une macro unique et sera liée au répertoire d'installation Macros de l'utilisateur par le Gestionnaire d'Addon.

OBLIGATOIRE pour les kits de préférences, non pris en charge pour les autres éléments de contenu.

Soit "apparence", "comportement" ou "combinaison" décrivant aux utilisateurs le type de changements qu'ils peuvent attendre de ce kit de préférences.

Multiple autorisé

Un URL (Uniform Resource Locator) pour le site web du paquet, le gestionnaire de bogues, le dépôt de sources, le fichier readme ou la documentation. Pour les paquets installés via git, le dépôt est obligatoire. Il est fortement recommandé d'inclure l'URL "readme" : si le readme est spécifié et qu'il s'agit d'un document en texte brut, HTML ou Markdown (comme indiqué par les extensions *.txt, *.html et *.md, respectivement), le gestionnaire de modules complémentaires téléchargera, mettra en cache et affichera ce fichier et ses fichiers image associés.

C'est une bonne idée d'inclure des balises pointant les utilisateurs vers les ressources en ligne de votre paquet. Il s'agit généralement d'une page wiki de wiki.freecad.org où les utilisateurs peuvent trouver et mettre à jour des informations sur le paquet, par exemple. Le gestionnaire d'addons répertorie ces URL et fournit des liens cliquables vers celles-ci dans la description du paquet.

Attributs

 * type="TYPE" (obligatoire) : Le type doit être l'un des identifiants suivants : "website", "bugtracker", "repository", "readme" ou "documentation".
 * branch="BRANCH" (obligatoire pour type="repository") : Le nom de la branche à extraire pour obtenir ce paquet. Il s'agit généralement du nom de votre branche de développement principale. Peut également spécifier tout autre type de référence git, par exemple une balise ou un commit spécifique.

Multiple autorisé

Le nom d'une personne qui est un auteur du paquet, comme reconnaissance de son travail et pour les questions.

Attributs

 * email="name@domain.tld" (facultatif) : Adresse électronique de l'auteur.

Multiple autorisé

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