Package: hatch-kicad
hatch-kicadCI/CDPackageMetaHatchplugin to buildKiCadaddon packages.Table of ContentsGlobal dependencyBuilderOptionsEnvironment variables substitutionContext formattingHow to runCustom repository build hookOptionsContext formattingShowcasesLicenseGlobal dependencyAddhatch-kicadwithin thebuild-system.requiresfield in yourpyproject.tomlfile.[build-system]requires=["hatchling","hatch-kicad"]build-backend="hatchling.build"BuilderThebuilder pluginname iskicad-package.OptionsSpecify package metadata andfile selectionin yourpyproject.tomlfile.
Depending on the project structure, it may be required torewrite relative paths.
In this example it is shown how to removesrc/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 packagesources=["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 packageicon="resources/icon.png"name="Plugin name"# ...remaining required optionsWhen in doubt check the plugin archive content, it must look like this:Archiveroot
├──plugins├──__init__.py├──...
├──resources├──icon.png
├──metadata.json[!IMPORTANT]metadata.jsonis created and packaged by plugin. Do not create it manually.Option detailsOptionTypeDefaultDescriptionnamestrrequiredThe human-readable name of the package. May contain a maximum of 200 characters.descriptionstrrequiredA 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_fullstrorlistofstrrequiredA 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 stringwithoutadding any separators.identifierstrrequiredThe 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.authordictwithnameproperty and optional contact propertiesfirstauthorfromproject.authors(mustcontainname).This option isrequiredso plugin will fail if default missing.Object containing one mandatory field,name, containing the name of the package creator. An optionalcontactfield may be present, for example:author={ name="Foo", "Website"="https://bar.com" }orauthor={ name="Foo", email="bar@com" }. Multiple contact fieldsareallowed.maintainersame asauthorfirstmaintainerfromproject.maintainersorNoneif does not containnamepropertySame asauthorbut not mandatory. Ifproject.maintainersfallback fails (due to missingnamefor example),maintainerwill be not included in finalmetadata.jsonlicensestrlicensefromprojectmetadata if it hastextkey (for examplelicense = {text = "MIT"}).License withfilekeynot supported.This option isrequiredso 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 foundhere.resourcesdictproject.urlsor{}if missingAdditional resource links for the package. Place your website, github, documentation and other links here.statusstr(supportsenvironment variables substitution)requiredA 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_versionstrrequiredThe minimum required KiCad version for this package.kicad_version_maxstr""The last KiCad version this package is compatible with.tagslistofstr[]The list of tagsiconstrrequiredThe path to the 64x64-pixel icon that will de displayed alongside the package in the KiCad's package dialog. Icon filemustexist.download_urlstr(supportscontext formatting)""A string containing a direct download URL for the package archive.For more details seekicad documentation.[!WARNING]
Packageversionvalue is derived fromrequiredproject.versionfield.
KiCad version requirement is not compatible withPEP-0440so some
valid python values won't pass PCM validation check. In such caseskicad-packageplugin uses onlybase versionvalue.Environment variables substitutionValue ofstatusoption can be set withenvironment variables substitutionusingenvfield 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)mustbe one of the following:stable,testing,developmentordeprecatedContext formattingValue ofdownload_url, similarly tostatus, can be set dynamically by environment variables substitution,
but additionally supports threeoptionalformat fields.FieldDescriptionstatusThe value oftool.hatch.build.kicad-package.statusafter substitution (if any)versionThe value ofproject.version, may be dynamic, for example usinghatch-vcszip_nameThe name of built zip artifactFor 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 optionsValue ofdownload_urlwill depend on bothMY_PLUGIN_STATUSandMY_PLUGIN_URLoptionalenvironment variables
and will be expanded to following strings:MY_PLUGIN_URLMY_PLUGIN_STATUSdownload_urlafter 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]
Packagedownload_urlis optional and will be empty inmetadata.jsonfile 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 625like' form of{name}-{version}.zipwhere{name}isnormalised.
This may lead to some unexpected results indownload_urlvalue. In the above exampleplugin-namehas been normalised toplugin_name.
If default behaviour is not desired, avoid usage ofzip_nameformat field.Environment variable and its default fallback valuecaninclude 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 optionsHow to runTo start build process, runhatch build -t kicad-package. If build successful, calculateddownload_sha256,download_sizeandinstall_sizefields should be printed:$hatchbuild--targetkicad-package[kicad-package]Runningcustom,version:standard
packagedetails:{"download_sha256":"52cc67f37fcb272ac20ee5d8d50b214143e989c56a573bb49cc16a997d2dc701","download_size":33295,"install_size":106682}dist/plugin-0.7.zipBy default, output artifacts are located atdistdirectory.There should be two files:{name}-{version}.zipandmetadata.json.
For details how to use these files to submit package to KiCad addon repository seethis guide.Custom Repository Build HookThebuild hookname iskicad-repository.
Enable it by adding hook tokicad-packagetarget:[tool.hatch.build.targets.kicad-package.hooks.kicad-repository]When enabled,kicad-repositoryhook 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 generatedist/repositorydirectory with following files:FileDescription{name}-{version}.zipArtifact generated bykicad-packagebuilder.packages.jsonMetadata file with list of the packages, will contain single package.repository.jsonRepository metadata file. URL of this file needs to be set in KiCad's plugin manager to use this repository.resources.zipArchive with plugin icon which will be displayed by PCM. This is the same icon as defined bykicad-package.iconoption.index.htmlOptional, configurable html page. Controlled bykicad-repository.html_dataoption.[!NOTE]
This feature is intended for automated deployments of development builds.
It is recommended to publish releases to official
KiCadplugin repositoryOptionsOptionTypeDefaultDescriptionrepository_urlstrparent path ofkicad-package.download_urlvalue. This option isrequiredso hook will fail if default missing.The URL address of the repository. Repository filesmustbe hosted at this URL in order to be usable by KiCad's PCM.html_datastrdefault html templatePath toindex.htmltemplate file. When missing, default will be used.In order to skipindex.htmlgeneration define as empty string"".Context formattingTemplate text read from file specified byhtml_dataoption supports twooptionalformat fields.FieldDescriptionrepository_urlThe value ofkicad-repository.repository_urloptionmetadata_strStringified representation ofmetadata.jsonfile generated bykicad-builderFor example:<!doctype html><htmllang="en"><head><metacharset="UTF-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0"/><linkrel="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>Showcaseskicad-plugin-template(pyproject.toml) Minimal examplekicad-kbplacer(pyproject.toml) Advanced usage with extra build hooks and dynamic versioningLicensehatch-kicadis distributed under the terms of theMITlicense.