Hello everyone, We are currently working on the fourth edition of our Yocto Project book and have been updating the content from Yocto Project 4.0 to the upcoming 6.0 release. As part of this effort, we have been working extensively with the new bitbake-setup tool and its documentation.
First, we would like to say that bitbake-setup is a welcome addition to the ecosystem. The move from the monolithic Poky repository approach to a more modular, template-based setup is a significant improvement for flexibility and reproducibility. During our work, we identified some areas where we believe the documentation and tooling could be improved to make the experience smoother for newcomers. We are sharing these observations in the hope of starting a constructive conversation. Terminology Suggestions The current documentation introduces several new terms that we found challenging to communicate clearly to readers. We would like to propose some alternative naming that we believe would be more intuitive. 1. Generic Configuration → BitBake Setup Template The term "Generic Configuration" does not immediately convey that this is a reusable template file used as input to create a build environment. The word "generic" can be interpreted as "basic" or "non-specialized" rather than "reusable template." We suggest *BitBake Setup Template* as an alternative. This clearly communicates that the .conf.json file serves as a template for creating setups. 2. Specific Configuration → BitBake Setup Instance Similarly, "Specific Configuration" does not clearly indicate that this is the *result* of applying a template with user choices. The relationship between "Generic" and "Specific" is not immediately obvious. We suggest *BitBake Setup Instance* as an alternative. The "Template → Instance" pattern is widely understood by developers and immediately conveys the relationship: a template is used to create an instance. 3. Nested "configurations" → Variant Within a BitBake Setup Template, there are nested "configurations" (e.g., poky, poky-with-sstate) that represent predefined bundles of fragments and settings. Using "configuration" here creates confusion since the term is already heavily overloaded in the Yocto ecosystem. We suggest *Variant* as an alternative. This conveys that these are different flavors or variations of the same base template, similar to how distributions have variants or flavors. Summary Table Current Term Proposed Term Generic Configuration BitBake Setup Template Specific Configuration BitBake Setup Instance (nested) configurations Variant Tooling and Usability Feedback 1. pip-installed bitbake-setup Cannot Access Default Registries When installing bitbake-setup via pip and running bitbake-setup init, the command fails because it cannot locate the default registry files that would normally be at ./bitbake/default-registry/. This creates a confusing first experience for users who expect a pip-installed tool to work out of the box. Having to clone the full BitBake repository defeats the convenience of pip installation. 2. Allow Empty Variants in Templates Currently, bitbake-setup init requires the user to select a variant when one is defined in the template. There is no option to skip this selection. Allowing templates without variants (or making variant selection optional) would reduce the number of questions during setup, making the process faster and more approachable for newcomers. 3. Unclear Error When Using Non-Raw URLs When running bitbake-setup init with a URL to a .conf.json file hosted on platforms like GitHub or GitLab, users naturally copy the URL from their browser. This URL points to an HTML page rather than the raw JSON content, causing the command to fail. The error message does not clearly indicate that a raw/plain URL is required. A clearer error message or guidance would help users understand the issue more quickly. 4. Tool to Generate Templates from Existing Environments Currently, there is no way to generate a BitBake Setup Template from: - An existing BitBake Setup Instance - A traditional workspace set up manually with oe-init-build-env - Any working Yocto/OpenEmbedded build environment A tool to export a working environment as a template would: - Help users migrate existing projects to the new bitbake-setup workflow - Make it easier to share working configurations with colleagues or the community - Reduce the barrier to adoption for users with established projects 5. Fragment Discovery on OpenEmbedded Layer Index The OpenEmbedded Layer Index (https://layers.openembedded.org) is an excellent resource for discovering layers. However, there is no equivalent discovery mechanism for configuration fragments. Adding a tab or section for fragments would help users discover available fragments and understand what problems they solve. ------------------------------ We hope this feedback is helpful. We are happy to discuss any of these points further or assist with documentation improvements. Best regards, Otávio Salvador Daiane Angolini -- Otavio Salvador O.S. Systems http://www.ossystems.com.br http://code.ossystems.com.br Mobile: +55 (53) 9 9981-7854
-=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#229297): https://lists.openembedded.org/g/openembedded-core/message/229297 Mute This Topic: https://lists.openembedded.org/mt/117253652/21656 Group Owner: [email protected] Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
