148 lines
7.4 KiB
Plaintext
148 lines
7.4 KiB
Plaintext
---
|
|
title: "Set up development environment"
|
|
---
|
|
|
|
```mdx-code-block
|
|
import {useState} from 'react';
|
|
|
|
export const RepositoryOpener = () => {
|
|
const [value, setValue] = useState(0);
|
|
const repoUrl = `vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=${encodeURIComponent(value)}`;
|
|
return <div>
|
|
<input onInput={(ev) => setValue(ev.target.value)} style={{width: "80%", display: "inline-block", marginRight: 16}} />
|
|
<a href={repoUrl}><button style={{cursor: value == "" ? "default" : "pointer"}} disabled={value == ""}>Open</button></a>
|
|
</div>
|
|
}
|
|
```
|
|
|
|
You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up.
|
|
|
|
## Developing with Visual Studio Code + devcontainer
|
|
|
|
The easiest way to get started with development is to use Visual Studio Code with devcontainers. This approach will create a preconfigured development environment with all the tools you need. This approach is enabled for all Home Assistant repositories. [Learn more about devcontainers.](https://code.visualstudio.com/docs/devcontainers/containers)
|
|
|
|
:::note
|
|
As this approach uses containers, you may face challenges exposing hardware like USB devices & adapters (onboard Bluetooth, Zigbee, ...) into the container for testing. This is possible when developing on a Linux host; however, you cannot directly access such hardware if you are using a Windows or MacOS computer for development.
|
|
:::
|
|
|
|
**Prerequisites**
|
|
|
|
- [Docker](https://docs.docker.com/get-docker/)
|
|
- [Visual Studio code](https://code.visualstudio.com/)
|
|
- [Git](https://git-scm.com/)
|
|
|
|
**Getting started:**
|
|
|
|
1. Go to [Home Assistant core repository](https://github.com/home-assistant/core) and click "fork".
|
|
2. Once your fork is created, copy the URL of your fork and paste it below, then click "Open":
|
|
<RepositoryOpener />
|
|
3. Your browser will prompt you if you want to use Visual Studio Code to open the link, click "Open Link".
|
|
4. When Visual Studio Code asks if you want to install the Remote extension, click "Install".
|
|
5. The Dev Container image will then be built (this may take a few minutes), after this your development environment will be ready.
|
|
6. You can verify that your dev container is set up properly by the following:
|
|
* Open the command palette in Visual Studio Code - `Shift`+`Command`+`P`(Mac) / `Ctrl`+`Shift`+`P` (Windows/Linux).
|
|
* Select `Tasks: Run Task` -> `Run Home Assistant Core`
|
|
* A terminal should open and begin outputting activity. Check for errors and wait for the output to stop/slow down.
|
|
* Navigate a web browser to `http://localhost:8123`, and you should see the Home Assistant setup screen.
|
|
|
|
In the future, if you want to get back to your development environment: open Visual Studio Code, click on the "Remote Explorer" button in the sidebar, select "Containers" at the top of the sidebar.
|
|
|
|
### Tasks
|
|
|
|
The devcontainer comes with some useful tasks to help you with development, you can start these tasks by opening the command palette with `Shift`+`Command`+`P`(Mac) / `Ctrl`+`Shift`+`P` (Windows/Linux) and select `Tasks: Run Task` then select the task you want to run.
|
|
|
|
When a task is currently running (like `Preview` for the docs), it can be restarted by opening the command palette and selecting `Tasks: Restart Running Task`, then select the task you want to restart.
|
|
|
|
### Debugging with Visual Studio Code
|
|
|
|
If the Dev Container was set up correctly - it supports debugging by default, out-of-the-box. It provides the necessary debug configurations, so hitting F5 should launch Home Assistant. Any breakpoints put in the code should be triggered, and the debugger should stop.
|
|
|
|
It is also possible to debug a remote Home Assistance instance (e.g., production instance) by following the procedure described [here](https://www.home-assistant.io/integrations/debugpy/).
|
|
|
|
## Manual Environment
|
|
|
|
_You only need these instructions if you do not want to use devcontainers._
|
|
|
|
It is also possible to set up a more traditional development environment. See the section for your operating system. Make sure your Python version is 3.12.
|
|
|
|
### Developing on Ubuntu / Debian
|
|
|
|
Install the core dependencies.
|
|
|
|
```shell
|
|
sudo apt-get update
|
|
sudo apt-get install python3-pip python3-dev python3-venv autoconf libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev ffmpeg libgammu-dev
|
|
```
|
|
|
|
### Developing on Fedora
|
|
|
|
Install the core dependencies.
|
|
|
|
```shell
|
|
sudo dnf update
|
|
sudo dnf install python3-pip python3-devel python3-virtualenv autoconf openssl-devel libxml2-devel libxslt-devel libjpeg-turbo-devel libffi-devel systemd-devel zlib-devel pkgconf-pkg-config libavformat-free-devel libavcodec-free-devel libavdevice-free-devel libavutil-free-devel libswscale-free-devel ffmpeg-free-devel libavfilter-free-devel ffmpeg-free gcc gcc-c++ cmake
|
|
```
|
|
|
|
### Developing on Arch / Manjaro
|
|
|
|
Install the core dependencies.
|
|
|
|
```shell
|
|
sudo pacman -Sy base-devel python python-pip python-virtualenv autoconf libxml2 libxslt libjpeg-turbo libffi systemd zlib pkgconf ffmpeg gcc cmake
|
|
```
|
|
|
|
### Developing on Windows
|
|
|
|
To develop on Windows, you will need to use the Linux subsystem (WSL). Follow the [WSL installation instructions](https://learn.microsoft.com/windows/wsl/install) and install Ubuntu from the Windows Store. Once you're able to access Linux, follow the Linux instructions.
|
|
|
|
When working in WSL make sure to keep all code/repos in the WSL environment to avoid issues with file permissions.
|
|
|
|
:::tip
|
|
If you find that you cannot open the development instance via [http://localhost:8123](http://localhost:8123) when using WSL, instead, within a WSL terminal, find the `inet` address of the `eth0` adaptor by running `ip addr show eth0`. Then use this address, excluding the CIDR block, to access the development instance, i.e. if your `inet` is listed as `172.20.37.6/20`, use [http://172.20.37.6:8123](http://172.20.37.6:8123).
|
|
:::
|
|
|
|
### Developing on macOS
|
|
|
|
Install [Homebrew](https://brew.sh/), then use that to install the dependencies:
|
|
|
|
```shell
|
|
brew install python3 autoconf ffmpeg cmake make
|
|
```
|
|
|
|
If you encounter build issues with `cryptography` when running the `script/setup` script below, check the cryptography documentation for [installation instructions](https://cryptography.io/en/latest/installation/#building-cryptography-on-macos).
|
|
|
|
## Setup Local Repository
|
|
|
|
Visit the [Home Assistant Core repository](https://github.com/home-assistant/core) and click **Fork**.
|
|
Once forked, setup your local copy of the source using the commands:
|
|
|
|
```shell
|
|
git clone https://github.com/YOUR_GIT_USERNAME/short_name_of_your_fork
|
|
cd core
|
|
git remote add upstream https://github.com/home-assistant/core.git
|
|
```
|
|
|
|
Install the requirements with a provided script named `setup`.
|
|
|
|
```shell
|
|
script/setup
|
|
```
|
|
|
|
This will create a virtual environment and install all necessary requirements. You're now set!
|
|
|
|
Each time you start a new terminal session, you will need to activate your virtual environment:
|
|
|
|
```shell
|
|
source venv/bin/activate
|
|
```
|
|
|
|
After that you can run Home Assistant like this:
|
|
|
|
```shell
|
|
hass -c config
|
|
```
|
|
|
|
If you encounter a crash (`SIGKILL`) while running this command on *macOS*, it's probably about lack of Bluetooth permission. You can fix it by adding this permission for your Terminal app (System Preferences -> Security & Privacy -> Bluetooth).
|
|
|
|
The Home Assistant configuration is stored in the `config` directory in your repository.
|