diff options
Diffstat (limited to 'documentation/overview-manual/yp-intro.rst')
| -rw-r--r-- | documentation/overview-manual/yp-intro.rst | 147 |
1 files changed, 63 insertions, 84 deletions
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst index 7a01828c5f..4a27e12e01 100644 --- a/documentation/overview-manual/yp-intro.rst +++ b/documentation/overview-manual/yp-intro.rst @@ -24,7 +24,7 @@ software customizations and build interchange for multiple hardware platforms as well as software stacks that can be maintained and scaled. .. image:: figures/key-dev-elements.png - :align: center + :width: 100% For further introductory information on the Yocto Project, you might be interested in this @@ -129,7 +129,7 @@ Here are features and advantages of the Yocto Project: arbitrarily include packages. - *License Manifest:* The Yocto Project provides a :ref:`license - manifest <dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle>` + manifest <dev-manual/licenses:maintaining open source license compliance during your product's lifecycle>` for review by people who need to track the use of open source licenses (e.g. legal teams). @@ -140,8 +140,7 @@ Here are challenges you might encounter when developing using the Yocto Project: - *Steep Learning Curve:* The Yocto Project has a steep learning curve and has many different ways to accomplish similar tasks. It can be - difficult to choose how to proceed when varying methods exist by - which to accomplish a given task. + difficult to choose between such ways. - *Understanding What Changes You Need to Make For Your Design Requires Some Research:* Beyond the simple tutorial stage, understanding what @@ -152,11 +151,11 @@ Here are challenges you might encounter when developing using the Yocto Project: ":ref:`transitioning-to-a-custom-environment:transitioning to a custom environment for systems development`" documents on the Yocto Project website. -- *Project Workflow Could Be Confusing:* The `Yocto Project +- *Project Workflow Could Be Confusing:* The :ref:`Yocto Project workflow <overview-manual/development-environment:the yocto project development environment>` could be confusing if you are used to traditional desktop and server software development. - In a desktop development environment, mechanisms exist to easily pull + In a desktop development environment, there are mechanisms to easily pull and install new packages, which are typically pre-compiled binaries from servers accessible over the Internet. Using the Yocto Project, you must modify your configuration and rebuild to add additional @@ -218,15 +217,15 @@ your Metadata, the easier it is to cope with future changes. - Use Board Support Package (BSP) layers from silicon vendors when possible. - - Familiarize yourself with the `Yocto Project curated layer - index <https://www.yoctoproject.org/software-overview/layers/>`__ - or the :oe_layerindex:`OpenEmbedded layer index <>`. + - Familiarize yourself with the + :yocto_home:`Yocto Project Compatible Layers </software-overview/layers/>` + or the :oe_layerindex:`OpenEmbedded Layer Index <>`. The latter contains more layers but they are less universally validated. - Layers support the inclusion of technologies, hardware components, and software components. The :ref:`Yocto Project - Compatible <dev-manual/common-tasks:making sure your layer is compatible with yocto project>` + Compatible <dev-manual/layers:making sure your layer is compatible with yocto project>` designation provides a minimum level of standardization that contributes to a strong ecosystem. "YP Compatible" is applied to appropriate products and software components such as BSPs, other @@ -249,8 +248,7 @@ accomplish this through a recipe that is a BitBake append .. note:: For general information on BSP layer structure, see the - :doc:`/bsp-guide/index` - . + :doc:`/bsp-guide/index`. The :term:`Source Directory` contains both general layers and BSP layers right out of the box. You @@ -271,7 +269,7 @@ of the ``poky`` repository, you will see several layers: ``meta``, layer. For procedures on how to create layers, see the -":ref:`dev-manual/common-tasks:understanding and creating layers`" +":ref:`dev-manual/layers:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. Components and Tools @@ -342,6 +340,18 @@ the Yocto Project: view information about builds. For information on Toaster, see the :doc:`/toaster-manual/index`. +- *VSCode IDE Extension:* The `Yocto Project BitBake + <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ + extension for Visual Studio Code provides a rich set of features for working + with BitBake recipes. The extension provides syntax highlighting, + hover tips, and completion for BitBake files as well as embedded Python and + Bash languages. Additional views and commands allow you to efficiently + browse, build and edit recipes. It also provides SDK integration for + cross-compiling and debugging through ``devtool``. + + Learn more about the VSCode Extension on the `extension's frontpage + <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__. + Production Tools ---------------- @@ -353,7 +363,7 @@ Yocto Project: (BitBake and OE-Core) automatically generates upgrades for recipes that are based on new versions of the recipes published upstream. See - :ref:`dev-manual/common-tasks:using the auto upgrade helper (auh)` + :ref:`dev-manual/upgrading-recipes:using the auto upgrade helper (auh)` for how to set it up. - *Recipe Reporting System:* The Recipe Reporting System tracks recipe @@ -363,7 +373,7 @@ Yocto Project: of the :oe_layerindex:`OpenEmbedded Layer Index <>`, which is a website that indexes OpenEmbedded-Core layers. -- *Patchwork:* `Patchwork <http://jk.ozlabs.org/projects/patchwork/>`__ +- *Patchwork:* `Patchwork <https://patchwork.yoctoproject.org/>`__ is a fork of a project originally started by `OzLabs <https://ozlabs.org/>`__. The project is a web-based tracking system designed to streamline the process of bringing contributions @@ -373,7 +383,7 @@ Yocto Project: - *AutoBuilder:* AutoBuilder is a project that automates build tests and quality assurance (QA). By using the public AutoBuilder, anyone - can determine the status of the current "master" branch of Poky. + can determine the status of the current development branch of Poky. .. note:: @@ -389,39 +399,6 @@ Yocto Project: You can learn more about the AutoBuilder used by the Yocto Project Autobuilder :doc:`here </test-manual/understand-autobuilder>`. -- *Cross-Prelink:* Prelinking is the process of pre-computing the load - addresses and link tables generated by the dynamic linker as compared - to doing this at runtime. Doing this ahead of time results in - performance improvements when the application is launched and reduced - memory usage for libraries shared by many applications. - - Historically, cross-prelink is a variant of prelink, which was - conceived by `Jakub - Jelínek <https://people.redhat.com/jakub/prelink.pdf>`__ a number of - years ago. Both prelink and cross-prelink are maintained in the same - repository albeit on separate branches. By providing an emulated - runtime dynamic linker (i.e. ``glibc``-derived ``ld.so`` emulation), - the cross-prelink project extends the prelink software's ability to - prelink a sysroot environment. Additionally, the cross-prelink - software enables the ability to work in sysroot style environments. - - The dynamic linker determines standard load address calculations - based on a variety of factors such as mapping addresses, library - usage, and library function conflicts. The prelink tool uses this - information, from the dynamic linker, to determine unique load - addresses for executable and linkable format (ELF) binaries that are - shared libraries and dynamically linked. The prelink tool modifies - these ELF binaries with the pre-computed information. The result is - faster loading and often lower memory consumption because more of the - library code can be re-used from shared Copy-On-Write (COW) pages. - - The original upstream prelink project only supports running prelink - on the end target device due to the reliance on the target device's - dynamic linker. This restriction causes issues when developing a - cross-compiled system. The cross-prelink adds a synthesized dynamic - loader that runs on the host, thus permitting cross-prelinking - without ever having to run on a read-write target filesystem. - - *Pseudo:* Pseudo is the Yocto Project implementation of `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run commands in an environment that seemingly has root privileges. @@ -430,8 +407,8 @@ Yocto Project: require system administrator privileges. For example, file ownership or permissions might need to be defined. Pseudo is a tool that you can either use directly or through the environment variable - ``LD_PRELOAD``. Either method allows these operations to succeed as - if system administrator privileges exist even when they do not. + ``LD_PRELOAD``. Either method allows these operations to succeed + even without system administrator privileges. Thanks to Pseudo, the Yocto Project never needs root privileges to build images for your target system. @@ -552,18 +529,18 @@ Historically, the Build Appliance was the second of three methods by which you could use the Yocto Project on a system that was not native to Linux. -1. *Hob:* Hob, which is now deprecated and is no longer available since +#. *Hob:* Hob, which is now deprecated and is no longer available since the 2.1 release of the Yocto Project provided a rudimentary, GUI-based interface to the Yocto Project. Toaster has fully replaced Hob. -2. *Build Appliance:* Post Hob, the Build Appliance became available. It +#. *Build Appliance:* Post Hob, the Build Appliance became available. It was never recommended that you use the Build Appliance as a day-to-day production development environment with the Yocto Project. Build Appliance was useful as a way to try out development in the Yocto Project environment. -3. *CROPS:* The final and best solution available now for developing +#. *CROPS:* The final and best solution available now for developing using the Yocto Project on a system not native to Linux is with :ref:`CROPS <overview-manual/yp-intro:development tools>`. @@ -579,8 +556,7 @@ software. This section provides an introduction to the choices or development methods you have when setting up your Build Host. Depending on your particular workflow preference and the type of operating system your -Build Host runs, several choices exist that allow you to use the Yocto -Project. +Build Host runs, you have several choices. .. note:: @@ -620,20 +596,15 @@ Project. ":ref:`dev-manual/start:setting up to use cross platforms (crops)`" section in the Yocto Project Development Tasks Manual. -- *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem - For Linux v2 to set up a Build Host using Windows 10. - - .. note:: - - The Yocto Project is not compatible with WSLv1, it is compatible - but not officially supported nor validated with WSLv2, if you - still decide to use WSL please upgrade to WSLv2. +- *Windows Subsystem For Linux (WSL 2):* You may use Windows Subsystem + For Linux version 2 to set up a Build Host using Windows 10 or later, + or Windows Server 2019 or later. - The Windows Subsystem For Linux allows Windows 10 to run a real Linux + The Windows Subsystem For Linux allows Windows to run a real Linux kernel inside of a lightweight virtual machine (VM). - For information on how to set up a Build Host with WSLv2, see the - ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wslv2)`" + For information on how to set up a Build Host with WSL 2, see the + ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wsl 2)`" section in the Yocto Project Development Tasks Manual. - *Toaster:* Regardless of what your Build Host is running, you can use @@ -646,6 +617,14 @@ Project. For information about and how to use Toaster, see the :doc:`/toaster-manual/index`. +- *Using the VSCode Extension:* You can use the `Yocto Project BitBake + <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ + extension for Visual Studio Code to start your BitBake builds through a + graphical user interface. + + Learn more about the VSCode Extension on the `extension's marketplace page + <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ + Reference Embedded Distribution (Poky) ====================================== @@ -674,7 +653,7 @@ these items that make up the Poky repository in the The following figure illustrates what generally comprises Poky: .. image:: figures/poky-reference-distribution.png - :align: center + :width: 100% - BitBake is a task executor and scheduler that is the heart of the OpenEmbedded build system. @@ -724,8 +703,8 @@ Sato. One of the most powerful properties of Poky is that every aspect of a build is controlled by the metadata. You can use metadata to augment -these base image types by adding metadata -`layers <overview-manual/yp-intro:the yocto project layer model>` that extend +these base image types by adding metadata :ref:`layers +<overview-manual/yp-intro:the yocto project layer model>` that extend functionality. These layers can provide, for example, an additional software stack for an image type, add a board support package (BSP) for additional @@ -741,11 +720,11 @@ other build process, in which case the basic functionality can be defined by the classes it inherits from the OE-Core layer's class definitions in ``./meta/classes``. Within a recipe you can also define additional tasks as well as task prerequisites. Recipe syntax through -BitBake also supports both ``_prepend`` and ``_append`` operators as a +BitBake also supports both ``:prepend`` and ``:append`` operators as a method of extending task functionality. These operators inject code into the beginning or end of a task. For information on these BitBake operators, see the -":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)`" +":ref:`bitbake-user-manual/bitbake-user-manual-metadata:appending and prepending (override style syntax)`" section in the BitBake User's Manual. The OpenEmbedded Build System Workflow @@ -756,31 +735,31 @@ accomplish image and SDK generation. The following figure overviews that workflow: .. image:: figures/YP-flow-diagram.png - :align: center + :width: 100% -Following is a brief summary of the "workflow": +Here is a brief summary of the "workflow": -1. Developers specify architecture, policies, patches and configuration +#. Developers specify architecture, policies, patches and configuration details. -2. The build system fetches and downloads the source code from the +#. The build system fetches and downloads the source code from the specified location. The build system supports standard methods such as tarballs or source code repositories systems such as Git. -3. Once source code is downloaded, the build system extracts the sources +#. Once source code is downloaded, the build system extracts the sources into a local work area where patches are applied and common steps for configuring and compiling the software are run. -4. The build system then installs the software into a temporary staging +#. The build system then installs the software into a temporary staging area where the binary package format you select (DEB, RPM, or IPK) is used to roll up the software. -5. Different QA and sanity checks run throughout entire build process. +#. Different QA and sanity checks run throughout entire build process. -6. After the binaries are created, the build system generates a binary +#. After the binaries are created, the build system generates a binary package feed that is used to create the final root file image. -7. The build system generates the file system image and a customized +#. The build system generates the file system image and a customized Extensible SDK (eSDK) for application development in parallel. For a very detailed look at this workflow, see the @@ -790,7 +769,7 @@ Some Basic Terms ================ It helps to understand some basic fundamental terms when learning the -Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project +Yocto Project. Although there is a list of terms in the ":doc:`Yocto Project Terms </ref-manual/terms>`" section of the Yocto Project Reference Manual, this section provides the definitions of some terms helpful for getting started: @@ -817,7 +796,7 @@ helpful for getting started: Yocto Project. For more detailed information on layers, see the - ":ref:`dev-manual/common-tasks:understanding and creating layers`" + ":ref:`dev-manual/layers:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. For a discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto @@ -878,7 +857,7 @@ helpful for getting started: distribution. Another point worth noting is that historically within the Yocto - Project, recipes were referred to as packages - thus, the existence + Project, recipes were referred to as packages --- thus, the existence of several BitBake variables that are seemingly mis-named, (e.g. :term:`PR`, :term:`PV`, and |