hatch-kicad

CI/CD
Package
Meta

---

Hatch plugin to build KiCad addon packages.

Table of Contents

• Global dependency
• Showcases
• Builder
  • Options
    • IPC plugin Action type
    • Environment variables substitution
    • Context formatting
  • How to run
• Custom repository build hook
  • Options
    • Context formatting
• License

Global dependency

Add hatch-kicad within the build-system.requires field in your pyproject.toml file.

[build-system]
requires = ["hatchling", "hatch-kicad"]
build-backend = "hatchling.build"

Showcases

• kicad-plugin-template (pyproject.toml) Minimal example
• kicad-kbplacer (pyproject.toml) Advanced usage with extra build hooks and dynamic versioning

Builder

The builder plugin name is kicad-package.

[!WARNING] Since KiCad 9 there are two plugin mechanisms: IPC and Swig based (too learn more see this). The hatch-kicad by default packages plugins to old deprecated (Swig based) structure. This behaviour can be changed using compatibility option.

Options

Specify package metadata and file selection in your pyproject.toml file.

For legacy compatibility mode, depending on the project structure, it may be required to rewrite relative paths. In this example it is shown how to remove src/ path prefix:

[tool.hatch.build.kicad-package]
# rewrite paths using `source` option, src/a.py will become a.py
# which will be copied to `plugin` directory inside the zip package
sources = ["src"]
include = [
  "src/*.py",
  "src/version.txt",
  "src/icon.png",
]
# icon (regardless of the filename) will be copied to
# resources/icon.png inside the zip package
icon = "resources/icon.png"
name = "Plugin name"
# ...remaining required options

When in doubt check the plugin archive content, it must look like this:

Archive root
├── plugins
   ├── __init__.py
   ├── ...
├── resources
   ├── icon.png
├── metadata.json

[!IMPORTANT] metadata.json is created and packaged by plugin. Do not create it manually.

For ipc packages, the archive structure is more flexible and rewriting paths is not required. Just ensure that entrypoint and action icon values use correct paths. Because paths are not rewritten, they are the same at build time and inside the archive (both relative to the project root):

[tool.hatch.build.kicad-package]
compatibility = "ipc"
include = [
  "src/*.py",
  "src/icon.png",
]
# icon (regardless of the filename) will be copied to
# resources/icon.png inside the zip package
icon = "resources/icon.png"
name = "Plugin name"
actions = [
  { identifier = "run", name = "Run", description = "Run plugin",
    entrypoint = "src/main.py", icons_light = ["src/icon.png"] },
]
# ...remaining required options

The resulting ipc archive looks like this:

Archive root
├── plugins
│   ├── plugin.json
│   ├── src
│   │   ├── main.py
│   │   ├── icon.png
│   │   ├── ...
├── resources
│   ├── icon.png
├── metadata.json

[!IMPORTANT] plugin.json is generated from the actions option and packaged by plugin. Do not create it manually.

Option details

Option	Type	Default	Description
compatibility	str	legacy	The plugin packaging mode. Can be equal legacy or ipc.
name	str	required	The human-readable name of the package. May contain a maximum of 200 characters.
description	str	required	A short free-form description of the package that will be shown in the PCM alongside the package name. May contain a maximum of 500 characters.
description_full	str or list of str	required	A long free-form description of the package that will be shown in the PCM when the package is selected by the user. May include new lines. May contain a maximum of 5000 characters. If using list of strings, list will be joined to one string without adding any separators.
identifier	str	required	The unique identifier for the package. May contain only alphanumeric characters and the dash (-) symbol. Must be between 2 and 50 characters in length. Must start with a latin character and end with a latin character or a numeral.
author	dict with name property and optional contact properties	first author from project.authors (must contain name). This option is required so plugin will fail if default missing.	Object containing one mandatory field, name, containing the name of the package creator. An optional contact field may be present, for example: author={ name="Foo", "Website"="https://bar.com" } or author={ name="Foo", email="bar@com" }. Multiple contact fields are allowed.
maintainer	same as author	first maintainer from project.maintainers or None if does not contain name property	Same as author but not mandatory. If project.maintainers fallback fails (due to missing name for example), maintainer will be not included in final metadata.json
license	str	license from project metadata if it has text key (for example license = {text = "MIT"}). License with file key not supported. This option is required so plugin will fail if default missing.	A string containing the license under which the package is distributed. KiCad team requires opens-source license in order to be included in official KiCad's package repository. List of the supported licenses can be found here.
resources	dict	project.urls or {} if missing	Additional resource links for the package. Place your website, github, documentation and other links here.
status	str (supports environment variables substitution)	required	A string containing one of the following: stable - this package is stable for general use, testing - this package is in a testing phase, users should be cautious and report issues, development - this package is in a development phase and should not be expected to work fully, deprecated - this package is no longer maintained.
kicad_version	str	required	The minimum required KiCad version for this package.
kicad_version_max	str	""	The last KiCad version this package is compatible with.
tags	list of str	[]	The list of tags
icon	str	required	The path to the 64x64-pixel icon that will de displayed alongside the package in the KiCad's package dialog. Icon file must exist.
download_url	str (supports context formatting)	""	A string containing a direct download URL for the package archive.
actions	list of Action	required when in ipc compatibility mode	The list of plugin registered actions. For details refer to IPC plugin Action type chapter.

For more details see kicad documentation.

[!WARNING] Package version value is derived from required project.version field. KiCad version requirement is not compatible with PEP-0440 so some valid python values won't pass PCM validation check. In such cases kicad-package plugin uses only base version value.

IPC plugin Action type

This type is new addition which is required when using ipc compatibility mode. In ipc mode the hatch-kicad plugin creates PCM archive which includes plugin.json. The plugin.json must comply to KiCad's schema and is generated based on actions option which uses Action type as described below:

Option	Type	Default	Description
identifier	str	required	An identifier for the action, must be unique within a plugin.
name	str	required	A human-readable name for the action (normally a verb or verb phrase).
description	str	required	A human-readable description for the action.
show_button	bool	True	Whether or not to show the action in the toolbar. When enabled then icons-light list must have at least one icon defined.
entrypoint	str	required	The way KiCad should launch this action (for example, the name of a Python script)
icons_light	list of str	[], required when show_button enabled	A list of one or more paths to PNG files to be shown in light mode.
icons_dark	list of str	[]	A list of one or more paths to PNG files to be shown in dark mode.

[!NOTE] Action scopes are currently fixed to the PCB editor (pcb) and cannot be configured.

Environment variables substitution

Value of status option can be set with environment variables substitution using env field and its modifier, e.g. {env:ENV_NAME:DEFAULT}, for example:

[tool.hatch.build.kicad-package]
status = "{env:MY_PLUGIN_STATUS:development}"

[!IMPORTANT] Default value (used when environment variable not set) must be one of the following: stable, testing, development or deprecated

Context formatting

Value of download_url, similarly to status, can be set dynamically by environment variables substitution, but additionally supports three optional format fields.

Field	Description
status	The value of tool.hatch.build.kicad-package.status after substitution (if any)
version	The value of project.version, may be dynamic, for example using hatch-vcs
zip_name	The name of built zip artifact

For example:

[project]
name = "my-plugin"
version = "0.1.0"

[tool.hatch.build.kicad-package]
status = "{env:MY_PLUGIN_STATUS:development}"
download_url = "https://{env:MY_PLUGIN_URL:foo.bar}/{status}/{version}/{zip_name}"
# ...remaining required options

Value of download_url will depend on both MY_PLUGIN_STATUS and MY_PLUGIN_URL optional environment variables and will be expanded to following strings:

MY_PLUGIN_URL	MY_PLUGIN_STATUS	download_url after substitution
"baz.bar"	not set	"https://baz.bar/development/0.1.0/my_plugin-0.1.0.zip"
not set	"stable"	"https://foo.bar/stable/0.1.0/my_plugin-0.1.0.zip"

[!NOTE] Package download_url is optional and will be empty in metadata.json file if not configured. In such case, remember to manually update it before submitting plugin to KiCad's plugin repository.

[!WARNING] The file name of zip artifact is by default formatted in 'PEP 625 like' form of {name}-{version}.zip where {name} is normalised. This may lead to some unexpected results in download_url value. In the above example plugin-name has been normalised to plugin_name. If default behaviour is not desired, avoid usage of zip_name format field.

Environment variable and its default fallback value can include format fields:

[tool.hatch.build.kicad-package]
status = "stable"
# when MY_PLUGIN_URL="https://custom/{status}/plugin.zip" environment variable set,
# then download_url results in "https://custom/stable/plugin.zip"
download_url = "{env:MY_PLUGIN_URL:https://default/{zip_name}}"
# ...remaining required options

How to run

To start build process, run hatch build -t kicad-package. If build successful, calculated download_sha256, download_size and install_size fields should be printed:

$ hatch build --target kicad-package
[kicad-package]
Running custom, version: standard
package details:
{
  "download_sha256": "52cc67f37fcb272ac20ee5d8d50b214143e989c56a573bb49cc16a997d2dc701",
  "download_size": 33295,
  "install_size": 106682
}
dist/plugin-0.7.zip

By default, output artifacts are located at dist directory.
There should be two files: {name}-{version}.zip and metadata.json. For details how to use these files to submit package to KiCad addon repository see this guide.

Custom Repository Build Hook

The build hook name is kicad-repository. Enable it by adding hook to kicad-package target:

[tool.hatch.build.targets.kicad-package.hooks.kicad-repository]

When enabled, kicad-repository hook will create KiCad compatible custom repository which is ready for hosting. When hosted, it can be used by KiCad plugin manager instead of official repository.

This hook will generate dist/repository directory with following files:

File	Description
{name}-{version}.zip	Artifact generated by kicad-package builder.
packages.json	Metadata file with list of the packages, will contain single package.
repository.json	Repository metadata file. URL of this file needs to be set in KiCad's plugin manager to use this repository.
resources.zip	Archive with plugin icon which will be displayed by PCM. This is the same icon as defined by kicad-package.icon option.
index.html	Optional, configurable html page. Controlled by kicad-repository.html_data option.

[!NOTE] This feature is intended for automated deployments of development builds. It is recommended to publish releases to official KiCad plugin repository

Options

Option	Type	Default	Description
repository_url	str	parent path of kicad-package.download_url value. This option is required so hook will fail if default missing.	The URL address of the repository. Repository files must be hosted at this URL in order to be usable by KiCad's PCM.
html_data	str	default html template	Path to index.html template file. When missing, default will be used. In order to skip index.html generation define as empty string "".

Context formatting

Template text read from file specified by html_data option supports two optional format fields.

Field	Description
repository_url	The value of kicad-repository.repository_url option
metadata_str	Stringified representation of metadata.json file generated by kicad-builder

For example:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" href="data:," />
  </head>
  <body>
    <p>Add <mark>{repository_url}/repository.json</mark>
    to KiCad's repository list to use these packages:</p>
    <pre><code>{metadata_str}</code></pre>
  </body>
</html>

License

hatch-kicad is distributed under the terms of the MIT license.