Package Metadata: Difference between revisions

From FreeCAD Documentation
(Extend dependency example)
(Tweak License inclusion information to clarify exactly what string we want)
Line 128: Line 128:


<!--T:38-->
<!--T:38-->
Name of license for this package, e.g. BSD, GPL, LGPL. In order to assist machine readability, only include the license name in this tag. For multiple licenses multiple separate tags must be used. A package will have multiple licenses if different source files have different licenses. Every license occurring in the source files should have a corresponding <license> tag. For any explanatory text about licensing caveats, please use the <description> tag.
Name of license for this package, e.g. BSD, GPL, LGPL. In order to assist machine readability, only include the license's SPDX short identifier (documented by OSI at [https://opensource.org/licenses/alphabetical their site] in this tag. For multiple licenses multiple separate tags must be used. A package will have multiple licenses if different source files have different licenses. Every license occurring in the source files should have a corresponding <license> tag. For any explanatory text about licensing caveats, please use the <description> tag.


<!--T:39-->
<!--T:39-->
Line 136: Line 136:
Commonly-used license strings:
Commonly-used license strings:
* {{incode|"Apache-2.0"}}
* {{incode|"Apache-2.0"}}
* {{incode|"BSD"}}
* {{incode|"BSD-2-Clause"}}
* {{incode|"Boost Software License"}}
* {{incode|"BSD-3-Clause"}}
* {{incode|"GPLv2"}}
* {{incode|"BSL-1.0"}}
* {{incode|"GPLv3"}}
* {{incode|"GPL-2"}}
* {{incode|"LGPLv2.1"}}
* {{incode|"GPL-3"}}
* {{incode|"LGPLv3"}}
* {{incode|"LGPL-2.1"}}
* {{incode|"LGPL-3"}}
* {{incode|"MIT"}}
* {{incode|"MIT"}}
* {{incode|"Mozilla Public License Version 1.1"}}
* {{incode|"MPL-1.1"}}
* {{incode|"CC0v1"}} (Public Domain dedication)
* {{incode|"CC0v1"}} (Public Domain dedication)



Revision as of 02:45, 10 September 2022

Other languages:

Introduction

Beginning in FreeCAD version 0.20, external add-ons (workbenches, macros, and preference packs) may be distributed with a metadata file describing the contents of the package. If the file "package.xml" is present it is read by FreeCAD and its contents used in various parts of the user interface. It is currently optional for workbenches and macros, and required for preference packs. This page documents the format of that metadata file. The format (and the contents of this Wiki page) are based on REP 149.

Overall file format

This document currently describes file format version 1.

The metadata file must be a valid, well-formed XML 1.0 document. It must be called "package.xml", and must exist in the base directory of the software package's primary branch (as specified by the FreeCAD-addons .gitmodules file) in its git repository. Only the package.xml file from the primary branch is considered by the Addon Manager. All understood XML tags are in lowercase, but unrecognized tags are not an error. Most tags are optional, and some only apply to certain types of package contents (for example, only Workbenches currently provide a "classname" element). Unneeded or unrecognized elements are ignored.

Any file path specified in package.xml must use the slash ("/") as the directory separator: on systems that expect a different separator during execution (e.g. Windows) FreeCAD will automatically convert to the correct separator.

Content elements

<package>

The only top-level element allowed is <package>, and the file may only contain one <package> element. Immediately subordinate to that are several required or optional elements, defined here. No other tags are permitted directly under the <package> element.

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

The <package> tag is the unique top-level tag in a package.xml file. All other tags are nested under it.

Attributes

  • format="NUMBER": Specifying the package.xml format being used. For this interface, you must specify format="1".
  • xmlns="NAMESPACE": Specifies the XML namespace for this package, and must be included exactly as shown above, as a link to https://wiki.freecad.org/Package_Metadata.

Required child tags

The top-level <package> element must contain at least the following tags:

Optional child tags

<name>

REQUIRED

The name of this package. Must only contain characters that are valid for filenames (disallowed characters are /\?%*:|"<> ).

<version>

REQUIRED

A version number that follows either the semantic versioning 2.0 standard (e.g. 1.0.2-beta) or the CalVer style (e.g. 2021.12.08). Note that you cannot include both types, and switching between types is not supported. Internally the code has no concept of which type is chosen, when comparing versions it performs a simple numerical comparison between each successive numeric component regardless of type. Note that this cannot be left blank, some kind of version number must be assigned. When the Addon Manager detects an increase in version number it will display the "update available" information to users.

<date>

REQUIRED

The date of the current version, in the format YYYY-MM-DD or YYYY.MM.DD.

<description>

REQUIRED

A concise (up to several sentences) text-only description of this package. No markup is supported.

<maintainer>

AT LEAST ONE REQUIRED (multiple allowed)

The name of the person maintaining the package. All packages require a maintainer. For orphaned packages see below.

Attributes

  • email="name@domain.tld" (required): Email address of the maintainer.

An orphaned package is one with no current maintainer. Orphaned packages should use the following maintainer information:

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

<license>

AT LEAST ONE REQUIRED (multiple allowed)

Name of license for this package, e.g. BSD, GPL, LGPL. In order to assist machine readability, only include the license's SPDX short identifier (documented by OSI at their site in this tag. For multiple licenses multiple separate tags must be used. A package will have multiple licenses if different source files have different licenses. Every license occurring in the source files should have a corresponding <license> tag. For any explanatory text about licensing caveats, please use the <description> tag.

Most common open-source licenses are described on the OSI website.

Commonly-used license strings:

  • "Apache-2.0"
  • "BSD-2-Clause"
  • "BSD-3-Clause"
  • "BSL-1.0"
  • "GPL-2"
  • "GPL-3"
  • "LGPL-2.1"
  • "LGPL-3"
  • "MIT"
  • "MPL-1.1"
  • "CC0v1" (Public Domain dedication)

Attributes

  • file="FILE" (optional): A path relative to the package.xml file containing the full license text. Many licenses require including the license text when redistributing the software. E.g. the Apache License, Version 2.0 states in paragraph 4.1: "You must give any other recipients of the Work or Derivative Works a copy of this License"

<content>

REQUIRED

The <content> tag describes the actual contents of the package. It has no attributes, and contains any number of children. Those children can have arbitrary tag names, only some of which may be recognized by FreeCAD. FreeCAD currently supports "workbench", "macro", and "preferencepack" elements. Each child is then defined recursively by this standard, containing any or all of the elements allowed for the root <package> node. For example:

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

The existence of <content> items implies a set of subfolders, one for each content item, named exactly as the given name of the item. So for the example above, the package's folder structure is:

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

In addition to the other elements of <package>, content items can optionally provide information in <icon>, <classname>, and <file> tags (technically these can be provided to the root <package> tag as well, but they are generally unused there).

Backwards-compatibility note: to avoid having to restructure packages that pre-date this metadata standard, the optional <subdirectory> 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.

<icon>

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

<subdirectory>

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 "<subdirectory>./</subdirectory>" is used to indicate that the item is not located in a subdirectory at all.

<classname>

REQUIRED for Workbenches

For workbenches, the name of the Python main entry class. This is the class that FreeCAD will try to load on startup to locate the workbench's icon, which should be set as a member variable of the class. For example, if your workbench defines the following class (usually in InitGui.py):

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

then the package.xml file expects:

<classname>MyNewWB</classname>

<file>

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.

<url>

Multiple allowed: "repository" is required, and "readme"-type is highly recommended.

A Uniform Resource Locator for the package's website, bug tracker, source repository, zip download link, readme file, or documentation (as specified by the "type" attribute, see below).

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

<author>

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.

<depend>

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

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

<conflict>

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

<replace>

Multiple allowed

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

Attributes

See <depend>.

<tag>

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

<freecadmin>

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

<freecadmax>

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

Validation

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: Tools → Edit parameters... → BaseApp → Preferences → Addons → developerMode. When the Addon Manager has finished reading the Addons database it will examine all available package.xml files for errors.

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

<?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">LGPLv2.1</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>

A complex, multi-component package:

<?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">GPLv3</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>

A package with dependencies:

<?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">GPLv3</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>