Clarifying Yocto Layer Structure: Best Practice vs. Common Misconceptions

The Official Best Practice: Layers Inside the `poky` Directory

The Yocto Project Best Known Methods (BKM) and official documentation are clear:
All meta-layers — whether BSP, distro, software, or third-party—should reside directly inside the `poky` directory.
This is not just a convention but a practical requirement for many Yocto tools and scripts, including `bitbake-layers` and the `yocto-check-layer` compatibility script (which, until recently, required this structure to function properly).

Example structure:

poky/
├── meta-my-bsp/
├── meta-my-distro/
├── meta-my-software/
├── meta-openembedded/
└── meta-other-third-party/

• Layer creation:
  The recommended way to create layers is with the `bitbake-layers create-layer` command, run from inside `poky/`. This ensures the layer lands in the correct location and is properly initialized.
• Layer management:
  Use `bitbake-layers add-layer` and related commands to manage which layers are active in your build.

Common Misconceptions: Alternative (and Faulty) Structure

A widespread mistake—especially in larger or long-running projects—is to invent alternative directory layouts, such as grouping layers under `layers/project/` or `layers/third-party/`, or placing them outside the `poky` directory entirely.
This is not recommended by Yocto documentation BKM.

Why did this happen? Probably a combination of not reading the official Yocto Documentation, and that these BKM’s have evolved over time and therefore a number of improvised own structures appeared. Over time, these alternatives spread, leading to confusion and compatibility problems.

•  Many Yocto tools and scripts assume layers are in `poky/` and may not work correctly otherwise.
•  The `poky/.gitignore` is set up to ignore `meta-*` directories in `poky/`, not elsewhere.
•  The official documentation and community support expect the standard layout, making troubleshooting harder for non-standard setups.

Managing Multiple Projects and Builds: Build Directories

The ”correct”” way to handle multiple projects or products is not to scatter layers, but to use separate build directories.

• Each project or product gets its own build directory e.g:
  `build-project_one/`
  `build-project_two/`),
  each with its own `conf/local.conf` and `conf/bblayers.conf`.
• All builds share the same set of layers in:
  `poky/`**, but each build directory can enable or disable layers as needed by editing its own `bblayers.conf`.

Example:

poky/
├── meta-my-bsp/
├── meta-my-distro/
├── meta-my-software/
├── meta-openembedded/
build-project_one/
└── conf/
├── local.conf
└── bblayers.conf
build-project_two/
└── conf/
├── local.conf
└── bblayers.conf

This allows for clean separation of build configurations without duplicating or scattering layers.

Layer Management with BitBake and Bootstrap Layers

bitbake-layers utility:
– Use for creating (`create-layer`), adding (`add-layer`), and managing layers[1][2][4].
– Also supports advanced commands like `layerindex-fetch` for pulling layers from the OpenEmbedded Layer Index.

• Bootstrap layers:
  A **bootstrap layer** is a minimal layer that helps manage project/product/release configurations, often containing only the essential settings and dependencies to “bootstrap” a build.
• Use `bitbake-layers create-layer meta-bootstrap` to set up such a layer in `poky/`.
• Enable the bootstrap layer first in your `bblayers.conf` so it can set up the environment for other layers.
• This is especially useful when managing multiple products or releases, as it allows you to encapsulate project-specific logic cleanly and portable.
• Use bitbake–alyers save-build-conf, to create local.conf.template & bblayers.conf.template files in your bootstrap layer, to be used with TEMPLATECONF
  when sourcing the environment
  TEMPLATECONF=path/to/bootstrap-layer source oe-init-build-env

In summary

For maintainable, compatible Yocto projects, always place your layers directly inside `poky/`, use separate build directories for each project/product, and leverage bootstrap layers for scalable configuration management. Avoid inventing alternative layer layouts—these are a main source of confusion and break tool compatibility.

[1] https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html
[2] https://kickstartembedded.com/2022/01/19/yocto-part-5-creating-adding-a-new-layer-to-your-image/
[3] https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/57836605/Creating+a+Custom+Yocto+Layer
[4] https://github.com/maxpeng/openstlinux_add_new_recipe/blob/master/add_the_layer_by_bitbake-layers.md
[5] https://docs.yoctoproject.org/dev-manual/layers.html
[6] https://docs.yoctoproject.org/2.1/ref-manual/ref-manual.html
[7] https://docs.yoctoproject.org/1.5/dev-manual/dev-manual.html
[8] https://www.reddit.com/r/embedded/comments/1dprl19/those_who_work_with_yocto_how_do_yall_manage_it/
[9] https://community.nxp.com/t5/i-MX-Processors-Knowledge-Base/How-to-add-a-new-layer-and-a-new-recipe-in-Yocto/ta-p/1102230
[10] https://www.embeddedrelated.com/showarticle/1693.php
[11] https://docs.yoctoproject.org/4.0.4/dev-manual/common-tasks.html
[12] https://bootlin.com/~mike/yocto/doc/overview-manual/yp-intro.html
[13] https://www.yoctoproject.org/development/technical-overview/
[14] https://github.com/jynik/ready-set-yocto
[15] https://yannik520.github.io/create_a_new_yocto_layer.html
[16] https://stackoverflow.com/questions/78808744/how-to-use-dynamic-layers-in-yocto
[17] https://www.youtube.com/watch?v=yuE7my3KOpo
[18] https://docs.yoctoproject.org/overview-manual/concepts.html
[19] https://community.nxp.com/pwmxy87654/attachments/pwmxy87654/connects/289/1/AMF-AUT-T2310.pdf