diff options
Diffstat (limited to 'documentation/overview-manual/yp-intro.rst')
| -rw-r--r-- | documentation/overview-manual/yp-intro.rst | 126 |
1 files changed, 54 insertions, 72 deletions
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst index a8ca9e9440..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). @@ -151,7 +151,7 @@ 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. @@ -217,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 @@ -269,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 @@ -340,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 ---------------- @@ -351,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 @@ -361,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 @@ -387,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. @@ -550,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>`. @@ -617,20 +596,15 @@ Build Host runs, you have several choices. ":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 @@ -643,6 +617,14 @@ Build Host runs, you have several choices. 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) ====================================== @@ -671,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. @@ -721,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 @@ -742,7 +724,7 @@ 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 @@ -753,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 @@ -814,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 @@ -875,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 |