depot/pkgs/servers/home-assistant/custom-components/README.md
Luke Granger-Brown 57725ef3ec Squashed 'third_party/nixpkgs/' content from commit 76612b17c0ce
git-subtree-dir: third_party/nixpkgs
git-subtree-split: 76612b17c0ce71689921ca12d9ffdc9c23ce40b2
2024-11-10 23:59:47 +00:00

74 lines
2.1 KiB
Markdown

# Packaging guidelines
## buildHomeAssistantComponent
Custom components should be packaged using the
`buildHomeAssistantComponent` function, that is provided at top-level.
It builds upon `buildPythonPackage` but uses a custom install and check
phase.
Python runtime dependencies can be directly consumed as unqualified
function arguments. Pass them into `propagatedBuildInputs`, for them to
be available to Home Assistant.
Out-of-tree components need to use Python packages from
`home-assistant.python.pkgs` as to not introduce conflicting package
versions into the Python environment.
**Example Boilerplate:**
```nix
{ lib
, buildHomeAssistantComponent
, fetchFromGitHub
}:
buildHomeAssistantComponent {
# owner, domain, version
src = fetchFromGithub {
# owner, repo, rev, hash
};
propagatedBuildInputs = [
# python requirements, as specified in manifest.json
];
meta = with lib; {
# changelog, description, homepage, license, maintainers
};
}
```
## Package attribute
The attribute name must reflect the domain as seen in the
`manifest.json`, which in turn will match the python module name below
in the `custom_components/` directory.
**Example:**
The project [mweinelt/ha-prometheus-sensor](https://github.com/mweinelt/ha-prometheus-sensor/blob/1.0.0/custom_components/prometheus_sensor/manifest.json#L2)
would receive the attribute name `"prometheus_sensor"`, because both
domain in the `manifest.json` as well as the module name are
`prometheus_sensor`.
## Package name
The `pname` attribute is a composition of both `owner` and `domain`.
Don't set `pname`, set `owner` and `domain` instead.
Exposing the `domain` attribute separately allows checking for
conflicting components at eval time.
## Manifest check
The `buildHomeAssistantComponent` builder uses a hook to check whether
the dependencies specified in the `manifest.json` are present and
inside the specified version range. It also makes sure derivation
and manifest agree about the domain name.
There shouldn't be a need to disable this hook, but you can set
`dontCheckManifest` to `true` in the derivation to achieve that.