150 lines
7.5 KiB
Plaintext
150 lines
7.5 KiB
Plaintext
---
|
|
title: "Set up development environment"
|
|
---
|
|
|
|
```mdx-code-block
|
|
import {useState} from 'react';
|
|
|
|
export const RepositoryOpener = () => {
|
|
const [value, setValue] = useState("");
|
|
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. Copy your fork's URL 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 - SSH 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:
|
|
1. Open the Command Palette in Visual Studio Code:
|
|
* Mac: `Shift`+`Command`+`P`
|
|
* Windows/Linux: `Ctrl`+`Shift`+`P`
|
|
2. Select **Tasks: Run Task** -> **Run Home Assistant Core**
|
|
3. A terminal should open and begin outputting activity. Check for errors and wait for the output to stop/slow down.
|
|
4. 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 dev container comes with some useful tasks to help you with development. You can run these tasks by opening the Command Palette with `Shift`+`Command`+`P`(Mac) / `Ctrl`+`Shift`+`P` (Windows/Linux) and selecting **Tasks: Run Task**, then finally selecting 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 below 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/name_of_your_fork
|
|
cd name_of_your_fork
|
|
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 the 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 caused by the lack of Bluetooth permissions. 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 at the root of your repository.
|