summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/start.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/start.rst')
-rw-r--r--documentation/dev-manual/start.rst94
1 files changed, 47 insertions, 47 deletions
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index b02e961608..498734a04d 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -29,7 +29,7 @@ however, keep in mind, the procedure here is simply a starting point.
29You can build off these steps and customize the procedure to fit any 29You can build off these steps and customize the procedure to fit any
30particular working environment and set of practices. 30particular working environment and set of practices.
31 31
321. *Determine Who is Going to be Developing:* You first need to 32#. *Determine Who is Going to be Developing:* You first need to
33 understand who is going to be doing anything related to the Yocto 33 understand who is going to be doing anything related to the Yocto
34 Project and determine their roles. Making this determination is 34 Project and determine their roles. Making this determination is
35 essential to completing subsequent steps, which are to get your 35 essential to completing subsequent steps, which are to get your
@@ -52,7 +52,7 @@ particular working environment and set of practices.
52 automated tests that are used to ensure all application and core 52 automated tests that are used to ensure all application and core
53 system development meets desired quality standards. 53 system development meets desired quality standards.
54 54
552. *Gather the Hardware:* Based on the size and make-up of the team, 55#. *Gather the Hardware:* Based on the size and make-up of the team,
56 get the hardware together. Ideally, any development, build, or test 56 get the hardware together. Ideally, any development, build, or test
57 engineer uses a system that runs a supported Linux distribution. 57 engineer uses a system that runs a supported Linux distribution.
58 These systems, in general, should be high performance (e.g. dual, 58 These systems, in general, should be high performance (e.g. dual,
@@ -66,13 +66,13 @@ particular working environment and set of practices.
66 building Yocto Project development containers to be run under 66 building Yocto Project development containers to be run under
67 Docker, which is described later. 67 Docker, which is described later.
68 68
693. *Understand the Hardware Topology of the Environment:* Once you 69#. *Understand the Hardware Topology of the Environment:* Once you
70 understand the hardware involved and the make-up of the team, you 70 understand the hardware involved and the make-up of the team, you
71 can understand the hardware topology of the development environment. 71 can understand the hardware topology of the development environment.
72 You can get a visual idea of the machines and their roles across the 72 You can get a visual idea of the machines and their roles across the
73 development environment. 73 development environment.
74 74
754. *Use Git as Your Source Control Manager (SCM):* Keeping your 75#. *Use Git as Your Source Control Manager (SCM):* Keeping your
76 :term:`Metadata` (i.e. recipes, 76 :term:`Metadata` (i.e. recipes,
77 configuration files, classes, and so forth) and any software you are 77 configuration files, classes, and so forth) and any software you are
78 developing under the control of an SCM system that is compatible 78 developing under the control of an SCM system that is compatible
@@ -109,7 +109,7 @@ particular working environment and set of practices.
109 Documentation on how to create interfaces and frontends for 109 Documentation on how to create interfaces and frontends for
110 Git. 110 Git.
111 111
1125. *Set up the Application Development Machines:* As mentioned earlier, 112#. *Set up the Application Development Machines:* As mentioned earlier,
113 application developers are creating applications on top of existing 113 application developers are creating applications on top of existing
114 software stacks. Following are some best practices for setting up 114 software stacks. Following are some best practices for setting up
115 machines used for application development: 115 machines used for application development:
@@ -128,7 +128,7 @@ particular working environment and set of practices.
128 - Use multiple toolchains installed locally into different 128 - Use multiple toolchains installed locally into different
129 locations to allow development across versions. 129 locations to allow development across versions.
130 130
1316. *Set up the Core Development Machines:* As mentioned earlier, core 131#. *Set up the Core Development Machines:* As mentioned earlier, core
132 developers work on the contents of the operating system itself. 132 developers work on the contents of the operating system itself.
133 Following are some best practices for setting up machines used for 133 Following are some best practices for setting up machines used for
134 developing images: 134 developing images:
@@ -145,7 +145,7 @@ particular working environment and set of practices.
145 - Share layers amongst the developers of a particular project and 145 - Share layers amongst the developers of a particular project and
146 contain the policy configuration that defines the project. 146 contain the policy configuration that defines the project.
147 147
1487. *Set up an Autobuilder:* Autobuilders are often the core of the 148#. *Set up an Autobuilder:* Autobuilders are often the core of the
149 development environment. It is here that changes from individual 149 development environment. It is here that changes from individual
150 developers are brought together and centrally tested. Based on this 150 developers are brought together and centrally tested. Based on this
151 automated build and test environment, subsequent decisions about 151 automated build and test environment, subsequent decisions about
@@ -183,12 +183,12 @@ particular working environment and set of practices.
183 - Allows scheduling of builds so that resources can be used 183 - Allows scheduling of builds so that resources can be used
184 efficiently. 184 efficiently.
185 185
1868. *Set up Test Machines:* Use a small number of shared, high 186#. *Set up Test Machines:* Use a small number of shared, high
187 performance systems for testing purposes. Developers can use these 187 performance systems for testing purposes. Developers can use these
188 systems for wider, more extensive testing while they continue to 188 systems for wider, more extensive testing while they continue to
189 develop locally using their primary development system. 189 develop locally using their primary development system.
190 190
1919. *Document Policies and Change Flow:* The Yocto Project uses a 191#. *Document Policies and Change Flow:* The Yocto Project uses a
192 hierarchical structure and a pull model. There are scripts to create and 192 hierarchical structure and a pull model. There are scripts to create and
193 send pull requests (i.e. ``create-pull-request`` and 193 send pull requests (i.e. ``create-pull-request`` and
194 ``send-pull-request``). This model is in line with other open source 194 ``send-pull-request``). This model is in line with other open source
@@ -213,7 +213,7 @@ particular working environment and set of practices.
213 possible. Chances are if you have discovered the need for changes, 213 possible. Chances are if you have discovered the need for changes,
214 someone else in the community needs them also. 214 someone else in the community needs them also.
215 215
21610. *Development Environment Summary:* Aside from the previous steps, 216#. *Development Environment Summary:* Aside from the previous steps,
217 here are best practices within the Yocto Project development 217 here are best practices within the Yocto Project development
218 environment: 218 environment:
219 219
@@ -296,7 +296,7 @@ Setting Up a Native Linux Host
296Follow these steps to prepare a native Linux machine as your Yocto 296Follow these steps to prepare a native Linux machine as your Yocto
297Project Build Host: 297Project Build Host:
298 298
2991. *Use a Supported Linux Distribution:* You should have a reasonably 299#. *Use a Supported Linux Distribution:* You should have a reasonably
300 current Linux-based host system. You will have the best results with 300 current Linux-based host system. You will have the best results with
301 a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS 301 a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS
302 as these releases are frequently tested against the Yocto Project and 302 as these releases are frequently tested against the Yocto Project and
@@ -306,10 +306,10 @@ Project Build Host:
306 section in the Yocto Project Reference Manual and the wiki page at 306 section in the Yocto Project Reference Manual and the wiki page at
307 :yocto_wiki:`Distribution Support </Distribution_Support>`. 307 :yocto_wiki:`Distribution Support </Distribution_Support>`.
308 308
3092. *Have Enough Free Memory:* Your system should have at least 50 Gbytes 309#. *Have Enough Free Memory:* Your system should have at least 50 Gbytes
310 of free disk space for building images. 310 of free disk space for building images.
311 311
3123. *Meet Minimal Version Requirements:* The OpenEmbedded build system 312#. *Meet Minimal Version Requirements:* The OpenEmbedded build system
313 should be able to run on any modern distribution that has the 313 should be able to run on any modern distribution that has the
314 following versions for Git, tar, Python, gcc and make. 314 following versions for Git, tar, Python, gcc and make.
315 315
@@ -329,7 +329,7 @@ Project Build Host:
329 ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`" 329 ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`"
330 section in the Yocto Project Reference Manual for information. 330 section in the Yocto Project Reference Manual for information.
331 331
3324. *Install Development Host Packages:* Required development host 332#. *Install Development Host Packages:* Required development host
333 packages vary depending on your build host and what you want to do 333 packages vary depending on your build host and what you want to do
334 with the Yocto Project. Collectively, the number of required packages 334 with the Yocto Project. Collectively, the number of required packages
335 is large if you want to be able to cover all cases. 335 is large if you want to be able to cover all cases.
@@ -361,7 +361,7 @@ Yocto Project on a Windows, Mac, or Linux machine.
361Follow these general steps to prepare a Windows, Mac, or Linux machine 361Follow these general steps to prepare a Windows, Mac, or Linux machine
362as your Yocto Project build host: 362as your Yocto Project build host:
363 363
3641. *Determine What Your Build Host Needs:* 364#. *Determine What Your Build Host Needs:*
365 `Docker <https://www.docker.com/what-docker>`__ is a software 365 `Docker <https://www.docker.com/what-docker>`__ is a software
366 container platform that you need to install on the build host. 366 container platform that you need to install on the build host.
367 Depending on your build host, you might have to install different 367 Depending on your build host, you might have to install different
@@ -370,20 +370,20 @@ as your Yocto Project build host:
370 Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__" 370 Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__"
371 your build host needs to run containers. 371 your build host needs to run containers.
372 372
3732. *Choose What To Install:* Depending on whether or not your build host 373#. *Choose What To Install:* Depending on whether or not your build host
374 meets system requirements, you need to install "Docker CE Stable" or 374 meets system requirements, you need to install "Docker CE Stable" or
375 the "Docker Toolbox". Most situations call for Docker CE. However, if 375 the "Docker Toolbox". Most situations call for Docker CE. However, if
376 you have a build host that does not meet requirements (e.g. 376 you have a build host that does not meet requirements (e.g.
377 Pre-Windows 10 or Windows 10 "Home" version), you must install Docker 377 Pre-Windows 10 or Windows 10 "Home" version), you must install Docker
378 Toolbox instead. 378 Toolbox instead.
379 379
3803. *Go to the Install Site for Your Platform:* Click the link for the 380#. *Go to the Install Site for Your Platform:* Click the link for the
381 Docker edition associated with your build host's native software. For 381 Docker edition associated with your build host's native software. For
382 example, if your build host is running Microsoft Windows Version 10 382 example, if your build host is running Microsoft Windows Version 10
383 and you want the Docker CE Stable edition, click that link under 383 and you want the Docker CE Stable edition, click that link under
384 "Supported Platforms". 384 "Supported Platforms".
385 385
3864. *Install the Software:* Once you have understood all the 386#. *Install the Software:* Once you have understood all the
387 pre-requisites, you can download and install the appropriate 387 pre-requisites, you can download and install the appropriate
388 software. Follow the instructions for your specific machine and the 388 software. Follow the instructions for your specific machine and the
389 type of the software you need to install: 389 type of the software you need to install:
@@ -412,15 +412,15 @@ as your Yocto Project build host:
412 Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`__ 412 Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`__
413 for Linux build hosts running the Ubuntu distribution. 413 for Linux build hosts running the Ubuntu distribution.
414 414
4155. *Optionally Orient Yourself With Docker:* If you are unfamiliar with 415#. *Optionally Orient Yourself With Docker:* If you are unfamiliar with
416 Docker and the container concept, you can learn more here - 416 Docker and the container concept, you can learn more here -
417 https://docs.docker.com/get-started/. 417 https://docs.docker.com/get-started/.
418 418
4196. *Launch Docker or Docker Toolbox:* You should be able to launch 419#. *Launch Docker or Docker Toolbox:* You should be able to launch
420 Docker or the Docker Toolbox and have a terminal shell on your 420 Docker or the Docker Toolbox and have a terminal shell on your
421 development host. 421 development host.
422 422
4237. *Set Up the Containers to Use the Yocto Project:* Go to 423#. *Set Up the Containers to Use the Yocto Project:* Go to
424 https://github.com/crops/docker-win-mac-docs/wiki and follow 424 https://github.com/crops/docker-win-mac-docs/wiki and follow
425 the directions for your particular build host (i.e. Linux, Mac, or 425 the directions for your particular build host (i.e. Linux, Mac, or
426 Windows). 426 Windows).
@@ -453,7 +453,7 @@ in which you can develop using the Yocto Project.
453Follow these general steps to prepare a Windows machine using WSL 2 as 453Follow these general steps to prepare a Windows machine using WSL 2 as
454your Yocto Project build host: 454your Yocto Project build host:
455 455
4561. *Make sure your Windows machine is capable of running WSL 2:* 456#. *Make sure your Windows machine is capable of running WSL 2:*
457 457
458 While all Windows 11 and Windows Server 2022 builds support WSL 2, 458 While all Windows 11 and Windows Server 2022 builds support WSL 2,
459 the first versions of Windows 10 and Windows Server 2019 didn't. 459 the first versions of Windows 10 and Windows Server 2019 didn't.
@@ -469,7 +469,7 @@ your Yocto Project build host:
469 469
470 Microsoft Windows [Version 10.0.19041.153] 470 Microsoft Windows [Version 10.0.19041.153]
471 471
4722. *Install the Linux distribution of your choice inside WSL 2:* 472#. *Install the Linux distribution of your choice inside WSL 2:*
473 Once you know your version of Windows supports WSL 2, you can 473 Once you know your version of Windows supports WSL 2, you can
474 install the distribution of your choice from the Microsoft Store. 474 install the distribution of your choice from the Microsoft Store.
475 Open the Microsoft Store and search for Linux. While there are 475 Open the Microsoft Store and search for Linux. While there are
@@ -479,7 +479,7 @@ your Yocto Project build host:
479 making your selection, simply click "Get" to download and install the 479 making your selection, simply click "Get" to download and install the
480 distribution. 480 distribution.
481 481
4823. *Check which Linux distribution WSL 2 is using:* Open a Windows 482#. *Check which Linux distribution WSL 2 is using:* Open a Windows
483 PowerShell and run:: 483 PowerShell and run::
484 484
485 C:\WINDOWS\system32> wsl -l -v 485 C:\WINDOWS\system32> wsl -l -v
@@ -489,13 +489,13 @@ your Yocto Project build host:
489 Note that WSL 2 supports running as many different Linux distributions 489 Note that WSL 2 supports running as many different Linux distributions
490 as you want to install. 490 as you want to install.
491 491
4924. *Optionally Get Familiar with WSL:* You can learn more on 492#. *Optionally Get Familiar with WSL:* You can learn more on
493 https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. 493 https://docs.microsoft.com/en-us/windows/wsl/wsl2-about.
494 494
4955. *Launch your WSL Distibution:* From the Windows start menu simply 495#. *Launch your WSL Distibution:* From the Windows start menu simply
496 launch your WSL distribution just like any other application. 496 launch your WSL distribution just like any other application.
497 497
4986. *Optimize your WSL 2 storage often:* Due to the way storage is 498#. *Optimize your WSL 2 storage often:* Due to the way storage is
499 handled on WSL 2, the storage space used by the underlying Linux 499 handled on WSL 2, the storage space used by the underlying Linux
500 distribution is not reflected immediately, and since BitBake heavily 500 distribution is not reflected immediately, and since BitBake heavily
501 uses storage, after several builds, you may be unaware you are 501 uses storage, after several builds, you may be unaware you are
@@ -597,14 +597,14 @@ repository at :yocto_git:`/poky`.
597Use the following procedure to locate the latest upstream copy of the 597Use the following procedure to locate the latest upstream copy of the
598``poky`` Git repository: 598``poky`` Git repository:
599 599
6001. *Access Repositories:* Open a browser and go to 600#. *Access Repositories:* Open a browser and go to
601 :yocto_git:`/` to access the GUI-based interface into the 601 :yocto_git:`/` to access the GUI-based interface into the
602 Yocto Project source repositories. 602 Yocto Project source repositories.
603 603
6042. *Select the Repository:* Click on the repository in which you are 604#. *Select the Repository:* Click on the repository in which you are
605 interested (e.g. ``poky``). 605 interested (e.g. ``poky``).
606 606
6073. *Find the URL Used to Clone the Repository:* At the bottom of the 607#. *Find the URL Used to Clone the Repository:* At the bottom of the
608 page, note the URL used to clone that repository 608 page, note the URL used to clone that repository
609 (e.g. :yocto_git:`/poky`). 609 (e.g. :yocto_git:`/poky`).
610 610
@@ -630,7 +630,7 @@ of a given component.
630 630
631Follow these steps to locate and download a particular tarball: 631Follow these steps to locate and download a particular tarball:
632 632
6331. *Access the Index of Releases:* Open a browser and go to 633#. *Access the Index of Releases:* Open a browser and go to
634 :yocto_dl:`Index of Releases </releases>`. The 634 :yocto_dl:`Index of Releases </releases>`. The
635 list represents released components (e.g. ``bitbake``, ``sato``, and 635 list represents released components (e.g. ``bitbake``, ``sato``, and
636 so on). 636 so on).
@@ -642,14 +642,14 @@ Follow these steps to locate and download a particular tarball:
642 historically used for very early releases and exists now only for 642 historically used for very early releases and exists now only for
643 retroactive completeness. 643 retroactive completeness.
644 644
6452. *Select a Component:* Click on any released component in which you 645#. *Select a Component:* Click on any released component in which you
646 are interested (e.g. ``yocto``). 646 are interested (e.g. ``yocto``).
647 647
6483. *Find the Tarball:* Drill down to find the associated tarball. For 648#. *Find the Tarball:* Drill down to find the associated tarball. For
649 example, click on ``yocto-&DISTRO;`` to view files associated with the 649 example, click on ``yocto-&DISTRO;`` to view files associated with the
650 Yocto Project &DISTRO; release. 650 Yocto Project &DISTRO; release.
651 651
6524. *Download the Tarball:* Click the tarball to download and save a 652#. *Download the Tarball:* Click the tarball to download and save a
653 snapshot of the given component. 653 snapshot of the given component.
654 654
655Using the Downloads Page 655Using the Downloads Page
@@ -661,13 +661,13 @@ release. Rather than Git repositories, these files represent snapshot
661tarballs similar to the tarballs located in the Index of Releases 661tarballs similar to the tarballs located in the Index of Releases
662described in the ":ref:`dev-manual/start:accessing index of releases`" section. 662described in the ":ref:`dev-manual/start:accessing index of releases`" section.
663 663
6641. *Go to the Yocto Project Website:* Open The 664#. *Go to the Yocto Project Website:* Open The
665 :yocto_home:`Yocto Project Website <>` in your browser. 665 :yocto_home:`Yocto Project Website <>` in your browser.
666 666
6672. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the 667#. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the
668 pull-down "SOFTWARE" tab menu near the top of the page. 668 pull-down "SOFTWARE" tab menu near the top of the page.
669 669
6703. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to 670#. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to
671 display and choose a recent or past supported Yocto Project release 671 display and choose a recent or past supported Yocto Project release
672 (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). 672 (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
673 673
@@ -679,7 +679,7 @@ described in the ":ref:`dev-manual/start:accessing index of releases`" section.
679 You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto 679 You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto
680 Project releases. 680 Project releases.
681 681
6824. *Download Tools or Board Support Packages (BSPs):* From the 682#. *Download Tools or Board Support Packages (BSPs):* From the
683 "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll 683 "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll
684 down the page and look for what you need. 684 down the page and look for what you need.
685 685
@@ -707,10 +707,10 @@ Cloning the ``poky`` Repository
707Follow these steps to create a local version of the upstream 707Follow these steps to create a local version of the upstream
708:term:`Poky` Git repository. 708:term:`Poky` Git repository.
709 709
7101. *Set Your Directory:* Change your working directory to where you want 710#. *Set Your Directory:* Change your working directory to where you want
711 to create your local copy of ``poky``. 711 to create your local copy of ``poky``.
712 712
7132. *Clone the Repository:* The following example command clones the 713#. *Clone the Repository:* The following example command clones the
714 ``poky`` repository and uses the default name "poky" for your local 714 ``poky`` repository and uses the default name "poky" for your local
715 repository:: 715 repository::
716 716
@@ -766,13 +766,13 @@ and then specifically check out that development branch.
766 Further development on top of the branch that occurs after check it 766 Further development on top of the branch that occurs after check it
767 out can occur. 767 out can occur.
768 768
7691. *Switch to the Poky Directory:* If you have a local poky Git 769#. *Switch to the Poky Directory:* If you have a local poky Git
770 repository, switch to that directory. If you do not have the local 770 repository, switch to that directory. If you do not have the local
771 copy of poky, see the 771 copy of poky, see the
772 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 772 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`"
773 section. 773 section.
774 774
7752. *Determine Existing Branch Names:* 775#. *Determine Existing Branch Names:*
776 :: 776 ::
777 777
778 $ git branch -a 778 $ git branch -a
@@ -793,7 +793,7 @@ and then specifically check out that development branch.
793 remotes/origin/zeus-next 793 remotes/origin/zeus-next
794 ... and so on ... 794 ... and so on ...
795 795
7963. *Check out the Branch:* Check out the development branch in which you 796#. *Check out the Branch:* Check out the development branch in which you
797 want to work. For example, to access the files for the Yocto Project 797 want to work. For example, to access the files for the Yocto Project
798 &DISTRO; Release (&DISTRO_NAME;), use the following command:: 798 &DISTRO; Release (&DISTRO_NAME;), use the following command::
799 799
@@ -827,19 +827,19 @@ similar to checking out by branch name except you use tag names.
827 Checking out a branch based on a tag gives you a stable set of files 827 Checking out a branch based on a tag gives you a stable set of files
828 not affected by development on the branch above the tag. 828 not affected by development on the branch above the tag.
829 829
8301. *Switch to the Poky Directory:* If you have a local poky Git 830#. *Switch to the Poky Directory:* If you have a local poky Git
831 repository, switch to that directory. If you do not have the local 831 repository, switch to that directory. If you do not have the local
832 copy of poky, see the 832 copy of poky, see the
833 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" 833 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`"
834 section. 834 section.
835 835
8362. *Fetch the Tag Names:* To checkout the branch based on a tag name, 836#. *Fetch the Tag Names:* To checkout the branch based on a tag name,
837 you need to fetch the upstream tags into your local repository:: 837 you need to fetch the upstream tags into your local repository::
838 838
839 $ git fetch --tags 839 $ git fetch --tags
840 $ 840 $
841 841
8423. *List the Tag Names:* You can list the tag names now:: 842#. *List the Tag Names:* You can list the tag names now::
843 843
844 $ git tag 844 $ git tag
845 1.1_M1.final 845 1.1_M1.final
@@ -861,7 +861,7 @@ similar to checking out by branch name except you use tag names.
861 yocto_1.5_M5.rc8 861 yocto_1.5_M5.rc8
862 862
863 863
8644. *Check out the Branch:* 864#. *Check out the Branch:*
865 :: 865 ::
866 866
867 $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO; 867 $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO;