jeans/operating-system
jeans/operating-system
1
0
Fork 0
mirror of https://github.com/home-assistant/operating-system.git synced 2025-07-24 13:36:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update spelling (#671)

Browse Source
This commit is contained in:
Fabian Affolter 2020-05-14 01:02:35 +02:00 committed by GitHub
parent a38bf6e75a
commit b0dbbf963c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Documentation/getting_started_development.md
View File

@ -1,11 +1,10 @@
Getting started with Hassos development using Docker on GNU/Linux
=================================================================
# Getting started with HassOS development using Docker on GNU/Linux
First, install **docker-ce** for your distribution - I'd advise to use your distro's provided packages, since that will make sure permissions et al. are sanely set up for what you are about to run. You're also expected to have your current user properly set up in in your sudoers policy, so that this account may elevate to root and execute arbitrary commands as UID 0 (this is required, since at some point during the build process, a new loopback device-backed filesystem image will be mounted inside a docker container - which requires a "privileged" container to run, which can only be done as root).
First, install `docker-ce` for your distribution. I'd advise to use your distro's provided packages, since that will make sure permissions et al. are sanely set up for what you are about to run. You're also expected to have your current user properly set up in in your sudoers policy, so that this account may elevate to root and execute arbitrary commands as UID 0 (this is required, since at some point during the build process, a new loopback device-backed filesystem image will be mounted inside a Docker container - which requires a "privileged" container to run, which can only be done as root).
Next, make sure the docker daemon is running:
Next, make sure the Docker daemon is running:
```
```bash
$ sudo systemctl status docker
● docker.service - Docker Application Container Engine
Loaded: loaded (/usr/lib/systemd/system/docker.service; disabled; vendor preset: disabled)
@ -15,7 +14,7 @@ $ sudo systemctl status docker
My desktop distro doesn't start newly installed services by default, which means I'll have to manually fire up the `docker` service:
```
```bash
$ sudo systemctl start docker
$ sudo systemctl --no-pager status docker -n0
● docker.service - Docker Application Container Engine
@ -30,9 +29,9 @@ $ sudo systemctl --no-pager status docker -n0
└─1539 docker-containerd --config /var/run/docker/containerd/containerd.toml
```
Now, change your working directory to your hassos repo checkout (please adapt pathnames as needed), make sure your intended changes to the source tree are applied (and committed, ideally :)), and execute the `enter.sh` helper script:
Now, change your working directory to your home-assistant/operating-system repository checkout (please adapt path names as needed), make sure your intended changes to the source tree are applied (and committed, ideally :)), and execute the `enter.sh` helper script:
```
```bash
$ cd ~/codebase/hassos/
$ sudo scripts/enter.sh
Sending build context to Docker daemon 30.48MB
@ -43,24 +42,24 @@ Successfully built 4dc25a21556b
Successfully tagged hassbuildroot:latest
```
Note that the current iteration of `enter.sh` will try to load the **overlayfs** kernel module, which is not strictly required for docker's operation, as far as I can tell. It's OK if loading that module fails; the shell script will continue executing. If everything works out, you will find yourself in an interactive login shell inside your docker container/build environment, where you can peek around:
Note that the current iteration of `enter.sh` will try to load the **overlayfs** kernel module, which is not strictly required for Docker's operation, as far as I can tell. It's OK if loading that module fails; the shell script will continue executing. If everything works out, you will find yourself in an interactive login shell inside your Docker container/build environment, where you can peek around:
```
```bash
root@somehashinhex:/build#
root@somehashinhex:/build# make help
[...]
```
The _hassos_ developers provide a Makefile that will build hassos images for a (rather long!) list of targets. For example run the command below to start building the _ova_ variant, and go make a cup of tea. Or fifteen.
The HassOS developers provide a `Makefile` that will build HassOS images for a list of targets. For example run the command below to start building the _ova_ variant, and go make a cup of tea. Or fifteen.
```
```bash
root@0db6f7079872:/build# make ova
[...]
```
That will result in a single VMDK image file at the very end of the build process. This image file is a compressed block device dump with a proper GPT partition table, prepared to ship into any OVA-compatible hypervisor's innards. For me, the end of the **ova** build steps looks like this:
```
```bash
[...]
2097152+0 records out
1073741824 bytes (1.1 GB, 1.0 GiB) copied, 12.2145 s, 87.9 MB/s
@ -74,15 +73,15 @@ make: Leaving directory '/build/buildroot'
The artifacts you just built are placed in the `target/` subdirectory:
```
```bash
root@fd292c061896:/build# ls -lh release/
total 141M
-rw-r--r-- 1 root root 141M Oct 10 20:22 hassos_ova-2.2.vmdk.gz
```
In order to be able to use this image file with the **qemu** hypervisor, you'll need to unpack it, and convert it to an image format that qemu can work with. Conveniently, the _hassos_ buildenv already provides all the tools we need for this conversion:
In order to be able to use this image file with the QEMU hypervisor, you'll need to unpack it, and convert it to an image format that QEMU can work with. Conveniently, the HassOS buildenv already provides all the tools we need for this conversion:
```
```bash
root@fd292c061896:/build# gunzip release/hassos_ova-2.2.qcow2.gz
root@fd292c061896:/build# ls -lh release/
total 673M
@ -91,14 +90,12 @@ total 673M
Now, exit the docker container's environment, and find the build artifacts in the `releases/` directory beneath your repository checkout dir. (The generated files will be owned by _root_; make sure to `chown` them to your user account, if needed.)
From there, qemu can try to boot it. Since the generated image assumes UEFI support in the host/hypervisor, this is slightly more tricky than with "classic"(/legacy) MBR-based images. On the *Debian* host I use to run my qemu virtual machine on, you'll need to install the **ovmf** package, which is described as providing "UEFI firmware for 64-bit x86 virtual machines". That package will install a _TianoCore_-derived qemu UEFI image build at `/usr/share/OVMF/OVMF_CODE.fd`, which we'll use with qemu to boot the generated qcow2 image. (Please adapt pathnames as necessary, for example if you have installed the ovmf firmware image at another location.)
From there, QEMU can try to boot it. Since the generated image assumes UEFI support in the host/hypervisor, this is slightly more tricky than with "classic"(/legacy) MBR-based images. On the *Debian* host I use to run my QEMU virtual machine on, you'll need to install the **ovmf** package which provides the "UEFI firmware for 64-bit x86 virtual machines". That package will install a **TianoCore**-derived QEMU UEFI image build at `/usr/share/OVMF/OVMF_CODE.fd`, which we'll use with QEMU to boot the generated qcow2 image. (Please adapt path names as necessary, for example if you have installed the ovmf firmware image at another location.)
```
```bash
$ /usr/bin/qemu-system-x86_64 -enable-kvm -name hassos_ova -smp 2 -m 1024 -drive file=release/hassos_ova-2.2.qcow2,index=0,media=disk,if=ide,cache=none,format=qcow2 -drive file=/usr/share/ovmf/x64/OVMF_CODE.fd,if=pflash,format=raw,readonly=on
```
This should pop up qemu's SDL frontend, displaying _hassos_' VT/CLI environment. Specifying addtional options and flags to qemu for network access, keyboard layout et al. are left as an exercise for the reader.
This should pop up QEMU's SDL frontend, displaying _hassos_' VT/CLI environment. Specifying additional options and flags to QEMU for network access, keyboard layout et al. are left as an exercise for the reader.
After the boot process has finished, you can log in to _hassos_ without a password, providing *root* as the username. From there, executing `login` on the *ha>* shell prompt will yield a root shell in the host OS.
Happy hacking! :)