Skip to content

adamws/hatch-kicad

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

44 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hatch-kicad

CI/CD CI - Main Coverage Status
Package PyPI - Version PyPI - Python Version
Meta Hatch project linting - Ruff code style - Black types - Mypy License - MIT

Hatch plugin to build KiCad addon packages.

Table of Contents

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

Builder

The builder plugin name is kicad-package.

Options

Specify package metadata and file selection in your pyproject.toml file. 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.

Option details

Option Type Default Description
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.

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.

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.