Manifest for Yocto building distro, temp name "kkd"

Goals

This repo is supposed to keep necessary items to build a distribution. Typically ARM, Armv8-A or later architectures (but not excluded to), hopefully someday RISCV too. Repository is intended to keep some scripts preparing the host machine to the build too. Eventually, sdcard-images, or files flashable by 3rd party tool like uuu should be buildable,

• for qemu running on developer's host, emulating aarch64 production/testing image
• for real HW target

Contents

This repository consists of:

.
├── default.xml                                 # main manifest
├── pinned.xml                                  # optional manifest (if exists, should contain repositories with frozen/fixed SHA-1's for reproducble builds)
├── docs                                        # intended to keep more detailed info than readme, when needed
├── layers
│   ├── conf                                    # TODO: temporary, switch to TEMPLATE_CONF
│   ├── meta-kkd-hw                             # layer keeping hardware specific configs, MACHINE definitions
│   ├── meta-kkd-os                             # layer keeping DISTRO and recipes for u-boot bootloader, and device-tree files
│   ├── meta-kkd-sw                             # layer with all software components developed privately, not necessary for OS to run
│   └── oe-init-build-env                       # populates build dir with conf dir
│
├── README.md                                   # this file
├── scripts
│   ├── setup_ec2.sh                            # default setup for ec2 provisioned machines, packages, locales ect
│   └── pin_versions.sh                         # shell script used to fix the repo manifest versions to particular SHA-1
├
├── upstream                                    # dir keeping layer collection with all software components downloaded from upstream sources
└── upstream-modifications                      # collection of patches/appends for upstream layers, which will be but haven't been yet upstreamed

As of now - no support for docker is provided.

Workflow idea

1. ensure google repo tool is installed: https://gerrit.googlesource.com/git-repo/ for example this way:

    # download the binary to `~/bin` directory, and give it permissions to be executed
    mkdir -p ~/bin && curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo && chmod +x ~/bin/repo
    # ensure dir is in path, or add (example for bash users) like this:
    echo 'export PATH=~/bin:$PATH' >> ~/.bashrc
   

2. clone manifest repo, using the tool:

    bash && repo init -u ssh://[email protected]/kkrolczyk/yocto-experiments -b main
   

   For reasons why repo tool is used, see <docs/why_repo.md>. For locally cloned repo use:

   repo init -u file:///path/to/your/local/manifest-repo -b main

   In case 'https' protocol instead of 'ssh' is required: use sed -i 's|ssh://git@|https://|g' default.xml

3. follow with repo sync

   optionally use -jX to parallelize/speed-up, where X is number of host cpu cores allocated to the build, newer repo scripts parallelize automatically, then one can use it to limit cores used.

4. make sure the dependencies for build host are met https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host (scripts dir contains setup_ec2.sh for typical debian setup)

5. source layers/oe-init-build-env <path/to/desired/build-dir>

6. run bitbake or

• adjust DISTRO in /conf/local.conf - to match either test or prod variant,

• adjust MACHINE in /conf/local.conf - select either qemu, or prod HW

• and build accordingly some by, for example:

10. bitbake kkd-image-prod or bitbake hello-world-rust or bitbake bootloader

Info

Layers pulled from upstream usually contain way more than needed, what prolongs the build. Initially, it's intended to keep them as they are, in upstream (just use what we need). Easier to update them this way. Alternatively, one could just copy needed recipes to kkd layers, and modify without the need for appends ect.

Rules

• Never modify stuff in upstream - all modifications either directly upstreamed, or kept in upstream-modifications

Notices

Yocto is sensitive to many params, including host's machine OS version, host gcc or other tools version, whether the disk is encrypted or not (path too long), which Yocto version is used (some build only on specific OS versions) ect.

• Yocto "scarthgap" was choosen, currently (2025-03) 5.0.x

• for Yocto's sscache, install also pip install websockets