> ## Documentation Index
> Fetch the complete documentation index at: https://docs.t3gemstone.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Yocto

> Gemstone Development Kit

<Note>
  This section will cover the [meta-gemstone](https://github.com/t3gemstone/meta-gemstone) Yocto project, which is used
  to compile the Kernel, Bootloader, Firmware, BSP (Board Support Packages), and Initrd (Init Ramdisk) components for
  Gemstone development boards.
</Note>

<Tip>
  By the end of this section, you will have knowledge about the following topics:

  * The structure of Yocto projects for Gemstone
  * How Yocto compilation processes are performed
</Tip>

To perform a Yocto build, run the following commands in order: `devbox shell` --> `task box` --> `task yocto:build`.\
The Taskfile expects only the `MACHINE` variable from you for Yocto builds. If no assignment is made,
`intel-corei7-64` is selected by default.

```bash Example theme={"system"}
task yocto:build MACHINE=t3-gem-o1
```

When the above command is executed, Yocto will perform various download, compilation, and packaging operations
to generate the initrd image, kernel, bootloader, and firmware for the selected machine. If this is the first time
the process is initiated, it may take up to an hour, depending on your internet speed, CPU power, and RAM capacity.
Since Yocto caches intermediate processes on disk, subsequent builds will complete much faster.

### 1. meta-gemstone

All Yocto-specific developments for Gemstone are consolidated in the [meta-gemstone](https://github.com/t3gemstone/meta-gemstone) layer. To preserve Yocto's modular structure and enable quick adaptation to layer updates, no modifications should be made to <Tooltip tip="meta-ti, meta-oe, ...">other layers</Tooltip>. Instead, desired recipes should be customized in the meta-gemstone layer using Yocto's `.bbappend` files.

#### 1.1. Folder Structure

```bash theme={"system"}
meta-gemstone
|-- conf
|   |-- distro
|   |-- machine
|   |-- templates
|-- recipes-connectivity
|-- recipes-core
|   |-- images
|-- recipes-devtools
|-- recipes-graphics
|-- recipes-kernel
|-- ...
```

<ResponseField name="conf/">
  This folder contains distribution configurations, <Tooltip tip="T3-GEM-O1, T3-GEM-S1, ...">machine
  definitions</Tooltip>, and machine-specific configuration templates.
</ResponseField>

<ResponseField name="recipes-core/images/">
  Definitions for which packages initrd and other images will include, along with their requirements and
  features, are specified in `.bb` recipe files located in this folder.
</ResponseField>

<ResponseField name="recipes-*/">
  All other folders starting with `recipes-` are used to categorize recipes. `.bbappend` files, which allow
  customization of recipes written in other layers, are typically stored in these folders.
</ResponseField>

### 2. Yocto Outputs

During the build process, Yocto can package almost all projects in DEB, IPK, or RPM formats. Since Gemstone is
Debian-based, it has been deemed appropriate to package projects compiled for the Gemstone distribution in DEB format.

<Note>
  You can access the generated packages in the `<sdk-directory>/build/yocto/tmp-musl/deploy/deb/<machine-name>` folder.
</Note>

The DEB packages generated by Yocto are used in two areas of the Gemstone distribution:

<Columns cols={2}>
  <Card title="Debos">
    When creating the Gemstone image, Debos retrieves files such as the kernel, bootloader, firmware, device-tree,
    and initrd from the DEB packages generated by Yocto and places them in the /boot directory.
  </Card>

  <Card title="Gemstone APT Server">
    Machine-specific DEB packages, such as kernel modules, initrd, bootloader, and firmware, are produced by Yocto
    and uploaded to the **[Gemstone APT server](https://packages.t3gemstone.org/apt)**.
  </Card>
</Columns>