KiCad Plugin Template

CI/CD
Meta

---

Project template for KiCad action plugins.

Table of Contents

• Key Features
• How to use
  • First build
  • Hatch project manager
  • Testing
  • Github Actions
• License

Key Features

• KiCad compatible plugin packaging with minimal configuration
• Custom repository deployments for development builds
• Test setup example
• Lint tools configuration with sane defaults
• Hatch based for extra extensibility

How to use

This is template repository. You can create your own repository from that template using this guide. Alternatively, clone/download this repository and use it as a starting point for your plugin.

First build

After your plugin directory is ready, run:

hatch build --target kicad-package

After a while you should get output similar to this:

[kicad-package]
package details:
{
  "download_sha256": "6d9aa77cea16b5edee478e4eb36c4e2c2a1c012201240767329363f116563312",
  "download_size": 7961,
  "install_size": 9259
}
dist/kicad_plugin_template-0.1.0.zip

Build result is located in dist/ directory. You can install it with KiCad's Plugin and Content Manager using Install From File... option:

To check if it is working, open PCB Editor. Plugin icon should be on the toolbar. If everything is ok, clicking it will result in following window:

And that's it! You built working KiCad plugin. Now it's time to start modifying template.

Hatch project manager

This template is using hatch with hatch-kicad plugin. Thanks to this build system it is possible to create KiCad compatible package file with single command. All settings used in this process are located in pyproject.toml file.

At this stage you should start customizing project defaults. Open pyproject.toml and modify kicad-package section:

[tool.hatch.build.targets.kicad-package]
name = "Template"
# ...remaining options

These options controls plugin content and metadata. Metadata values will become important when publishing to KiCad's plugin repository. To learn more about kicad-package builder see this.

Hatch is also used for running various actions in isolated environments. There are two environments defined:

[tool.hatch.envs.default]
# ...
[tool.hatch.envs.lint]
# ...

Project environment can be used with hatch run or hatch shell command. For example, to get linting results using ruff, black and mypy, run:

hatch run lint:all

Testing

Tests are run in default environment. This environment uses system-packages = true option because it requires pcbnew package which is installed and managed by KiCad.

To execute tests run hath run test command.

Warning

This approach wasn't tested on Windows

Github Actions

This template project uses GitHub Actions for CI/CD. For the details see main workflow file.

This workflow performs tests and publishes plugin package. When built on master branch, plugin is published to custom KiCad plugin repository which is build by hatch-kicad kicad-repository hook and then is pushed to gh-pages branch. This makes it accessible via following URL: https://adamws.github.io/kicad-plugin-template/.

For tags, plugin zip archive is published as GitHub release.

License

This project is distributed under the terms of the MIT license.