# How do I get started with Yocto Linux on Qemu?

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/yocto_qemu/)
- [How do I get started with Yocto Linux on Qemu?](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/yocto_qemu/yocto_build/)
- [Next Steps](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/yocto_qemu/_next-steps/)

## What is the Yocto Project?
The [Yocto Project](https://www.yoctoproject.org/) is an open-source project with a build system that allows software developers to create custom embedded Linux OS distributions regardless of the hardware architecture. Developers can configure their custom builds of Yocto using a set of recipes. In this Learning Path you will learn the steps to build a minimal Yocto Linux image for a 64-bit Arm target and run it on [QEMU](https://www.qemu.org/).

## How do I build a minimal Yocto Linux image for a 64-bit Arm target?
Poky is a reference distribution of the Yocto Project. It is a great starting point to build your own custom distribution as it contains both the build system and the the baseline functional distribution. Along with containing recipes for real target boards, it also contains the recipes for building the image, for example 64-bit Arm machines supported in QEMU. The example 64-bit machine emulated by QEMU does not emulate any particular board but is a great starting point to learn and try the basics of running this distribution.

The first step is to install the packages required to build and run Yocto.

For Ubuntu 22.04 and later:

```bash
sudo apt update
sudo apt-get install -y gawk wget git-core diffstat unzip texinfo build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libgl1 libglx-mesa0 libsdl1.2-dev pylint xterm python3-subunit mesa-common-dev lz4
```

Now download the Poky reference distribution and checkout the branch/tag you wish to build. You will build `yocto-5.0.10` in this example.

```bash
git clone [git://git.yoctoproject.org/poky](git://git.yoctoproject.org/poky)
cd poky
git checkout tags/yocto-5.0.10 -b yocto-5.0.10-local
```

Next source the script as shown below to initialize your build environment for your 64-bit Arm example machine QEMU target:

```bash
source oe-init-build-env build-qemu-arm64
```

The output is shown below:

```
__output__You had no conf/local.conf file. This configuration file has therefore been
__output__created for you with some default values. You may wish to edit it to, for
__output__example, select a different MACHINE (target hardware). See conf/local.conf
__output__for more information as common configuration options are commented.

__output__You had no conf/bblayers.conf file. This configuration file has therefore been
__output__created for you with some default values. To add additional metadata layers
__output__into your configuration please add entries to conf/bblayers.conf.

__output__The Yocto Project has extensive documentation about OE including a reference
__output__manual which can be found at:
    https://docs.yoctoproject.org

__output__For more information about OpenEmbedded see their website:
    https://www.openembedded.org/

### Shell environment set up for builds. ###

__output__You can now run 'bitbake <target>'

Common targets are:
    core-image-minimal
    core-image-full-cmdline
    core-image-sato
    core-image-weston
    meta-toolchain
    meta-ide-support

You can also run generated qemu images with a command like 'runqemu qemux86'

Other commonly useful commands are:
 - 'devtool' and 'recipetool' handle common recipe tasks
 - 'bitbake-layers' handles common layer tasks
 - 'oe-pkgdata-util' handles common target package tasks
```

You will now be in the `build-qemu-arm64` directory which is your build directory and where the images for your target are built. As the output from running the command above indicates, you will now need to select the target hardware MACHINE in the conf/local.conf file. To do this, run `sed` to uncomment `MACHINE ?= "qemuarm64"` in conf/local.conf file.

```bash
sed -i '/qemuarm64/s/^#//g' conf/local.conf
```

**Note:** On Ubuntu systems with apparmor you will need to allow unprivileged users to run bitbake.

```bash
echo 0 | sudo tee /proc/sys/kernel/apparmor_restrict_unprivileged_userns
```

With the right machine now selected, proceed to building the minimal core image for your target.

```bash
bitbake core-image-minimal
```

Depending on your machine, this build step can take an hour or more to complete.

After the build is complete, the images are in the `build-qemu-arm64/tmp/deploy/images/qemuarm64` directory.

## How do I run the image on the 64-bit Arm QEMU target?
QEMU is installed on your machine as part of cloning the Poky repository and sourcing the environment script.

You can now run the command below to launch run the image you built on the 64-bit Arm Qemu target:

```bash
runqemu qemuarm64 nographic
```

You will see Linux booting on your console.

Enter `root` when presented with the login prompt.

Run `uname` to check the Linux distribution and the target hardware architecture:

```bash
uname -a
```

You will see the output below:

```
__output__Linux qemuarm64 5.15.78-yocto-standard #1 SMP PREEMPT Wed Nov 16 14:17:41 UTC 2022 aarch64 GNU/Linux
```

To exit QEMU enter `Control-a` followed by `x` and you will return to the shell prompt.

Congratulations! You have successfully built and run a minimal Yocto Linux image on an example 64-bit Arm machine running in QEMU.