diff options
Diffstat (limited to 'documentation/dev-manual')
| -rw-r--r-- | documentation/dev-manual/bmaptool.rst | 6 | ||||
| -rw-r--r-- | documentation/dev-manual/building.rst | 46 | ||||
| -rw-r--r-- | documentation/dev-manual/changes.rst | 48 | ||||
| -rw-r--r-- | documentation/dev-manual/debugging.rst | 22 | ||||
| -rw-r--r-- | documentation/dev-manual/gobject-introspection.rst | 18 | ||||
| -rw-r--r-- | documentation/dev-manual/layers.rst | 18 | ||||
| -rw-r--r-- | documentation/dev-manual/packages.rst | 4 | ||||
| -rw-r--r-- | documentation/dev-manual/qemu.rst | 12 | ||||
| -rw-r--r-- | documentation/dev-manual/quilt.rst | 16 | ||||
| -rw-r--r-- | documentation/dev-manual/runtime-testing.rst | 28 | ||||
| -rw-r--r-- | documentation/dev-manual/start.rst | 94 | ||||
| -rw-r--r-- | documentation/dev-manual/upgrading-recipes.rst | 28 | ||||
| -rw-r--r-- | documentation/dev-manual/wayland.rst | 4 | ||||
| -rw-r--r-- | documentation/dev-manual/wic.rst | 8 |
14 files changed, 176 insertions, 176 deletions
diff --git a/documentation/dev-manual/bmaptool.rst b/documentation/dev-manual/bmaptool.rst index 4ee6f5e48b..9add72cf3b 100644 --- a/documentation/dev-manual/bmaptool.rst +++ b/documentation/dev-manual/bmaptool.rst | |||
| @@ -28,18 +28,18 @@ Following, is an example that shows how to flash a Wic image. Realize | |||
| 28 | that while this example uses a Wic image, you can use Bmaptool to flash | 28 | that while this example uses a Wic image, you can use Bmaptool to flash |
| 29 | any type of image. Use these steps to flash an image using Bmaptool: | 29 | any type of image. Use these steps to flash an image using Bmaptool: |
| 30 | 30 | ||
| 31 | 1. *Update your local.conf File:* You need to have the following set | 31 | #. *Update your local.conf File:* You need to have the following set |
| 32 | in your ``local.conf`` file before building your image:: | 32 | in your ``local.conf`` file before building your image:: |
| 33 | 33 | ||
| 34 | IMAGE_FSTYPES += "wic wic.bmap" | 34 | IMAGE_FSTYPES += "wic wic.bmap" |
| 35 | 35 | ||
| 36 | 2. *Get Your Image:* Either have your image ready (pre-built with the | 36 | #. *Get Your Image:* Either have your image ready (pre-built with the |
| 37 | :term:`IMAGE_FSTYPES` | 37 | :term:`IMAGE_FSTYPES` |
| 38 | setting previously mentioned) or take the step to build the image:: | 38 | setting previously mentioned) or take the step to build the image:: |
| 39 | 39 | ||
| 40 | $ bitbake image | 40 | $ bitbake image |
| 41 | 41 | ||
| 42 | 3. *Flash the Device:* Flash the device with the image by using Bmaptool | 42 | #. *Flash the Device:* Flash the device with the image by using Bmaptool |
| 43 | depending on your particular setup. The following commands assume the | 43 | depending on your particular setup. The following commands assume the |
| 44 | image resides in the :term:`Build Directory`'s ``deploy/images/`` area: | 44 | image resides in the :term:`Build Directory`'s ``deploy/images/`` area: |
| 45 | 45 | ||
diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index 2798dd3e98..3064974cc5 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst | |||
| @@ -43,11 +43,11 @@ The following figure and list overviews the build process: | |||
| 43 | .. image:: figures/bitbake-build-flow.png | 43 | .. image:: figures/bitbake-build-flow.png |
| 44 | :width: 100% | 44 | :width: 100% |
| 45 | 45 | ||
| 46 | 1. *Set up Your Host Development System to Support Development Using the | 46 | #. *Set up Your Host Development System to Support Development Using the |
| 47 | Yocto Project*: See the ":doc:`start`" section for options on how to get a | 47 | Yocto Project*: See the ":doc:`start`" section for options on how to get a |
| 48 | build host ready to use the Yocto Project. | 48 | build host ready to use the Yocto Project. |
| 49 | 49 | ||
| 50 | 2. *Initialize the Build Environment:* Initialize the build environment | 50 | #. *Initialize the Build Environment:* Initialize the build environment |
| 51 | by sourcing the build environment script (i.e. | 51 | by sourcing the build environment script (i.e. |
| 52 | :ref:`structure-core-script`):: | 52 | :ref:`structure-core-script`):: |
| 53 | 53 | ||
| @@ -66,7 +66,7 @@ The following figure and list overviews the build process: | |||
| 66 | event, it's typically cleaner to locate the :term:`Build Directory` | 66 | event, it's typically cleaner to locate the :term:`Build Directory` |
| 67 | somewhere outside of your source directory. | 67 | somewhere outside of your source directory. |
| 68 | 68 | ||
| 69 | 3. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the | 69 | #. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the |
| 70 | ``conf/local.conf`` configuration file, which is found in the | 70 | ``conf/local.conf`` configuration file, which is found in the |
| 71 | :term:`Build Directory`, is set up how you want it. This file defines many | 71 | :term:`Build Directory`, is set up how you want it. This file defines many |
| 72 | aspects of the build environment including the target machine architecture | 72 | aspects of the build environment including the target machine architecture |
| @@ -74,7 +74,7 @@ The following figure and list overviews the build process: | |||
| 74 | the build (:term:`PACKAGE_CLASSES`), and a centralized tarball download | 74 | the build (:term:`PACKAGE_CLASSES`), and a centralized tarball download |
| 75 | directory through the :term:`DL_DIR` variable. | 75 | directory through the :term:`DL_DIR` variable. |
| 76 | 76 | ||
| 77 | 4. *Build the Image:* Build the image using the ``bitbake`` command:: | 77 | #. *Build the Image:* Build the image using the ``bitbake`` command:: |
| 78 | 78 | ||
| 79 | $ bitbake target | 79 | $ bitbake target |
| 80 | 80 | ||
| @@ -273,12 +273,12 @@ loading modules needed to locate and mount the final root filesystem. | |||
| 273 | 273 | ||
| 274 | Follow these steps to create an :term:`Initramfs` image: | 274 | Follow these steps to create an :term:`Initramfs` image: |
| 275 | 275 | ||
| 276 | 1. *Create the :term:`Initramfs` Image Recipe:* You can reference the | 276 | #. *Create the :term:`Initramfs` Image Recipe:* You can reference the |
| 277 | ``core-image-minimal-initramfs.bb`` recipe found in the | 277 | ``core-image-minimal-initramfs.bb`` recipe found in the |
| 278 | ``meta/recipes-core`` directory of the :term:`Source Directory` | 278 | ``meta/recipes-core`` directory of the :term:`Source Directory` |
| 279 | as an example from which to work. | 279 | as an example from which to work. |
| 280 | 280 | ||
| 281 | 2. *Decide if You Need to Bundle the :term:`Initramfs` Image Into the Kernel | 281 | #. *Decide if You Need to Bundle the :term:`Initramfs` Image Into the Kernel |
| 282 | Image:* If you want the :term:`Initramfs` image that is built to be bundled | 282 | Image:* If you want the :term:`Initramfs` image that is built to be bundled |
| 283 | in with the kernel image, set the :term:`INITRAMFS_IMAGE_BUNDLE` | 283 | in with the kernel image, set the :term:`INITRAMFS_IMAGE_BUNDLE` |
| 284 | variable to ``"1"`` in your ``local.conf`` configuration file and set the | 284 | variable to ``"1"`` in your ``local.conf`` configuration file and set the |
| @@ -290,7 +290,7 @@ Follow these steps to create an :term:`Initramfs` image: | |||
| 290 | :term:`CONFIG_INITRAMFS_SOURCE` variable, allowing the :term:`Initramfs` | 290 | :term:`CONFIG_INITRAMFS_SOURCE` variable, allowing the :term:`Initramfs` |
| 291 | image to be built into the kernel normally. | 291 | image to be built into the kernel normally. |
| 292 | 292 | ||
| 293 | 3. *Optionally Add Items to the Initramfs Image Through the Initramfs | 293 | #. *Optionally Add Items to the Initramfs Image Through the Initramfs |
| 294 | Image Recipe:* If you add items to the :term:`Initramfs` image by way of its | 294 | Image Recipe:* If you add items to the :term:`Initramfs` image by way of its |
| 295 | recipe, you should use :term:`PACKAGE_INSTALL` rather than | 295 | recipe, you should use :term:`PACKAGE_INSTALL` rather than |
| 296 | :term:`IMAGE_INSTALL`. :term:`PACKAGE_INSTALL` gives more direct control of | 296 | :term:`IMAGE_INSTALL`. :term:`PACKAGE_INSTALL` gives more direct control of |
| @@ -298,7 +298,7 @@ Follow these steps to create an :term:`Initramfs` image: | |||
| 298 | necessarily want that are set by the :ref:`image <ref-classes-image>` | 298 | necessarily want that are set by the :ref:`image <ref-classes-image>` |
| 299 | or :ref:`core-image <ref-classes-core-image>` classes. | 299 | or :ref:`core-image <ref-classes-core-image>` classes. |
| 300 | 300 | ||
| 301 | 4. *Build the Kernel Image and the Initramfs Image:* Build your kernel | 301 | #. *Build the Kernel Image and the Initramfs Image:* Build your kernel |
| 302 | image using BitBake. Because the :term:`Initramfs` image recipe is a | 302 | image using BitBake. Because the :term:`Initramfs` image recipe is a |
| 303 | dependency of the kernel image, the :term:`Initramfs` image is built as well | 303 | dependency of the kernel image, the :term:`Initramfs` image is built as well |
| 304 | and bundled with the kernel image if you used the | 304 | and bundled with the kernel image if you used the |
| @@ -316,7 +316,7 @@ to override it. | |||
| 316 | 316 | ||
| 317 | To achieve this, you need to perform some additional steps: | 317 | To achieve this, you need to perform some additional steps: |
| 318 | 318 | ||
| 319 | 1. *Create a multiconfig for your Initramfs image:* You can perform the steps | 319 | #. *Create a multiconfig for your Initramfs image:* You can perform the steps |
| 320 | on ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" to create a separate multiconfig. | 320 | on ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" to create a separate multiconfig. |
| 321 | For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and | 321 | For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and |
| 322 | contains the variables:: | 322 | contains the variables:: |
| @@ -324,7 +324,7 @@ To achieve this, you need to perform some additional steps: | |||
| 324 | TMPDIR="${TOPDIR}/tmp-initramfscfg" | 324 | TMPDIR="${TOPDIR}/tmp-initramfscfg" |
| 325 | TCLIBC="musl" | 325 | TCLIBC="musl" |
| 326 | 326 | ||
| 327 | 2. *Set additional Initramfs variables on your main configuration:* | 327 | #. *Set additional Initramfs variables on your main configuration:* |
| 328 | Additionally, on your main configuration (``local.conf``) you need to set the | 328 | Additionally, on your main configuration (``local.conf``) you need to set the |
| 329 | variables:: | 329 | variables:: |
| 330 | 330 | ||
| @@ -599,13 +599,13 @@ are a couple of areas to experiment with: | |||
| 599 | 599 | ||
| 600 | - ``glibc``: In general, follow this process: | 600 | - ``glibc``: In general, follow this process: |
| 601 | 601 | ||
| 602 | 1. Remove ``glibc`` features from | 602 | #. Remove ``glibc`` features from |
| 603 | :term:`DISTRO_FEATURES` | 603 | :term:`DISTRO_FEATURES` |
| 604 | that you think you do not need. | 604 | that you think you do not need. |
| 605 | 605 | ||
| 606 | 2. Build your distribution. | 606 | #. Build your distribution. |
| 607 | 607 | ||
| 608 | 3. If the build fails due to missing symbols in a package, determine | 608 | #. If the build fails due to missing symbols in a package, determine |
| 609 | if you can reconfigure the package to not need those features. For | 609 | if you can reconfigure the package to not need those features. For |
| 610 | example, change the configuration to not support wide character | 610 | example, change the configuration to not support wide character |
| 611 | support as is done for ``ncurses``. Or, if support for those | 611 | support as is done for ``ncurses``. Or, if support for those |
| @@ -837,13 +837,13 @@ build. | |||
| 837 | 837 | ||
| 838 | Follow these steps to populate your Downloads directory: | 838 | Follow these steps to populate your Downloads directory: |
| 839 | 839 | ||
| 840 | 1. *Create a Clean Downloads Directory:* Start with an empty downloads | 840 | #. *Create a Clean Downloads Directory:* Start with an empty downloads |
| 841 | directory (:term:`DL_DIR`). You | 841 | directory (:term:`DL_DIR`). You |
| 842 | start with an empty downloads directory by either removing the files | 842 | start with an empty downloads directory by either removing the files |
| 843 | in the existing directory or by setting :term:`DL_DIR` to point to either | 843 | in the existing directory or by setting :term:`DL_DIR` to point to either |
| 844 | an empty location or one that does not yet exist. | 844 | an empty location or one that does not yet exist. |
| 845 | 845 | ||
| 846 | 2. *Generate Tarballs of the Source Git Repositories:* Edit your | 846 | #. *Generate Tarballs of the Source Git Repositories:* Edit your |
| 847 | ``local.conf`` configuration file as follows:: | 847 | ``local.conf`` configuration file as follows:: |
| 848 | 848 | ||
| 849 | DL_DIR = "/home/your-download-dir/" | 849 | DL_DIR = "/home/your-download-dir/" |
| @@ -856,7 +856,7 @@ Follow these steps to populate your Downloads directory: | |||
| 856 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 856 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
| 857 | variable for more information. | 857 | variable for more information. |
| 858 | 858 | ||
| 859 | 3. *Populate Your Downloads Directory Without Building:* Use BitBake to | 859 | #. *Populate Your Downloads Directory Without Building:* Use BitBake to |
| 860 | fetch your sources but inhibit the build:: | 860 | fetch your sources but inhibit the build:: |
| 861 | 861 | ||
| 862 | $ bitbake target --runonly=fetch | 862 | $ bitbake target --runonly=fetch |
| @@ -865,7 +865,7 @@ Follow these steps to populate your Downloads directory: | |||
| 865 | a "snapshot" of the source files in the form of tarballs, which can | 865 | a "snapshot" of the source files in the form of tarballs, which can |
| 866 | be used for the build. | 866 | be used for the build. |
| 867 | 867 | ||
| 868 | 4. *Optionally Remove Any Git or other SCM Subdirectories From the | 868 | #. *Optionally Remove Any Git or other SCM Subdirectories From the |
| 869 | Downloads Directory:* If you want, you can clean up your downloads | 869 | Downloads Directory:* If you want, you can clean up your downloads |
| 870 | directory by removing any Git or other Source Control Management | 870 | directory by removing any Git or other Source Control Management |
| 871 | (SCM) subdirectories such as ``${DL_DIR}/git2/*``. The tarballs | 871 | (SCM) subdirectories such as ``${DL_DIR}/git2/*``. The tarballs |
| @@ -879,7 +879,7 @@ any machine and at any time. | |||
| 879 | Follow these steps to build your target using the files in the downloads | 879 | Follow these steps to build your target using the files in the downloads |
| 880 | directory: | 880 | directory: |
| 881 | 881 | ||
| 882 | 1. *Using Local Files Only:* Inside your ``local.conf`` file, add the | 882 | #. *Using Local Files Only:* Inside your ``local.conf`` file, add the |
| 883 | :term:`SOURCE_MIRROR_URL` variable, inherit the | 883 | :term:`SOURCE_MIRROR_URL` variable, inherit the |
| 884 | :ref:`own-mirrors <ref-classes-own-mirrors>` class, and use the | 884 | :ref:`own-mirrors <ref-classes-own-mirrors>` class, and use the |
| 885 | :term:`BB_NO_NETWORK` variable to your ``local.conf``:: | 885 | :term:`BB_NO_NETWORK` variable to your ``local.conf``:: |
| @@ -894,11 +894,11 @@ directory: | |||
| 894 | BitBake's fetching process in step 3 stays local, which means files | 894 | BitBake's fetching process in step 3 stays local, which means files |
| 895 | from your "own-mirror" are used. | 895 | from your "own-mirror" are used. |
| 896 | 896 | ||
| 897 | 2. *Start With a Clean Build:* You can start with a clean build by | 897 | #. *Start With a Clean Build:* You can start with a clean build by |
| 898 | removing the ``${``\ :term:`TMPDIR`\ ``}`` directory or using a new | 898 | removing the ``${``\ :term:`TMPDIR`\ ``}`` directory or using a new |
| 899 | :term:`Build Directory`. | 899 | :term:`Build Directory`. |
| 900 | 900 | ||
| 901 | 3. *Build Your Target:* Use BitBake to build your target:: | 901 | #. *Build Your Target:* Use BitBake to build your target:: |
| 902 | 902 | ||
| 903 | $ bitbake target | 903 | $ bitbake target |
| 904 | 904 | ||
| @@ -925,16 +925,16 @@ directory: | |||
| 925 | If you do have recipes that use :term:`AUTOREV`, you can take steps to | 925 | If you do have recipes that use :term:`AUTOREV`, you can take steps to |
| 926 | still use the recipes in an offline build. Do the following: | 926 | still use the recipes in an offline build. Do the following: |
| 927 | 927 | ||
| 928 | 1. Use a configuration generated by enabling :ref:`build | 928 | #. Use a configuration generated by enabling :ref:`build |
| 929 | history <dev-manual/build-quality:maintaining build output quality>`. | 929 | history <dev-manual/build-quality:maintaining build output quality>`. |
| 930 | 930 | ||
| 931 | 2. Use the ``buildhistory-collect-srcrevs`` command to collect the | 931 | #. Use the ``buildhistory-collect-srcrevs`` command to collect the |
| 932 | stored :term:`SRCREV` values from the build's history. For more | 932 | stored :term:`SRCREV` values from the build's history. For more |
| 933 | information on collecting these values, see the | 933 | information on collecting these values, see the |
| 934 | ":ref:`dev-manual/build-quality:build history package information`" | 934 | ":ref:`dev-manual/build-quality:build history package information`" |
| 935 | section. | 935 | section. |
| 936 | 936 | ||
| 937 | 3. Once you have the correct source revisions, you can modify | 937 | #. Once you have the correct source revisions, you can modify |
| 938 | those recipes to set :term:`SRCREV` to specific versions of the | 938 | those recipes to set :term:`SRCREV` to specific versions of the |
| 939 | software. | 939 | software. |
| 940 | 940 | ||
diff --git a/documentation/dev-manual/changes.rst b/documentation/dev-manual/changes.rst index 8ccbf0d7ee..9cb25f3549 100644 --- a/documentation/dev-manual/changes.rst +++ b/documentation/dev-manual/changes.rst | |||
| @@ -22,40 +22,40 @@ steps, see the Yocto Project | |||
| 22 | 22 | ||
| 23 | Use the following general steps to submit a bug: | 23 | Use the following general steps to submit a bug: |
| 24 | 24 | ||
| 25 | 1. Open the Yocto Project implementation of :yocto_bugs:`Bugzilla <>`. | 25 | #. Open the Yocto Project implementation of :yocto_bugs:`Bugzilla <>`. |
| 26 | 26 | ||
| 27 | 2. Click "File a Bug" to enter a new bug. | 27 | #. Click "File a Bug" to enter a new bug. |
| 28 | 28 | ||
| 29 | 3. Choose the appropriate "Classification", "Product", and "Component" | 29 | #. Choose the appropriate "Classification", "Product", and "Component" |
| 30 | for which the bug was found. Bugs for the Yocto Project fall into | 30 | for which the bug was found. Bugs for the Yocto Project fall into |
| 31 | one of several classifications, which in turn break down into | 31 | one of several classifications, which in turn break down into |
| 32 | several products and components. For example, for a bug against the | 32 | several products and components. For example, for a bug against the |
| 33 | ``meta-intel`` layer, you would choose "Build System, Metadata & | 33 | ``meta-intel`` layer, you would choose "Build System, Metadata & |
| 34 | Runtime", "BSPs", and "bsps-meta-intel", respectively. | 34 | Runtime", "BSPs", and "bsps-meta-intel", respectively. |
| 35 | 35 | ||
| 36 | 4. Choose the "Version" of the Yocto Project for which you found the | 36 | #. Choose the "Version" of the Yocto Project for which you found the |
| 37 | bug (e.g. &DISTRO;). | 37 | bug (e.g. &DISTRO;). |
| 38 | 38 | ||
| 39 | 5. Determine and select the "Severity" of the bug. The severity | 39 | #. Determine and select the "Severity" of the bug. The severity |
| 40 | indicates how the bug impacted your work. | 40 | indicates how the bug impacted your work. |
| 41 | 41 | ||
| 42 | 6. Choose the "Hardware" that the bug impacts. | 42 | #. Choose the "Hardware" that the bug impacts. |
| 43 | 43 | ||
| 44 | 7. Choose the "Architecture" that the bug impacts. | 44 | #. Choose the "Architecture" that the bug impacts. |
| 45 | 45 | ||
| 46 | 8. Choose a "Documentation change" item for the bug. Fixing a bug might | 46 | #. Choose a "Documentation change" item for the bug. Fixing a bug might |
| 47 | or might not affect the Yocto Project documentation. If you are | 47 | or might not affect the Yocto Project documentation. If you are |
| 48 | unsure of the impact to the documentation, select "Don't Know". | 48 | unsure of the impact to the documentation, select "Don't Know". |
| 49 | 49 | ||
| 50 | 9. Provide a brief "Summary" of the bug. Try to limit your summary to | 50 | #. Provide a brief "Summary" of the bug. Try to limit your summary to |
| 51 | just a line or two and be sure to capture the essence of the bug. | 51 | just a line or two and be sure to capture the essence of the bug. |
| 52 | 52 | ||
| 53 | 10. Provide a detailed "Description" of the bug. You should provide as | 53 | #. Provide a detailed "Description" of the bug. You should provide as |
| 54 | much detail as you can about the context, behavior, output, and so | 54 | much detail as you can about the context, behavior, output, and so |
| 55 | forth that surrounds the bug. You can even attach supporting files | 55 | forth that surrounds the bug. You can even attach supporting files |
| 56 | for output from logs by using the "Add an attachment" button. | 56 | for output from logs by using the "Add an attachment" button. |
| 57 | 57 | ||
| 58 | 11. Click the "Submit Bug" button submit the bug. A new Bugzilla number | 58 | #. Click the "Submit Bug" button submit the bug. A new Bugzilla number |
| 59 | is assigned to the bug and the defect is logged in the bug tracking | 59 | is assigned to the bug and the defect is logged in the bug tracking |
| 60 | system. | 60 | system. |
| 61 | 61 | ||
| @@ -162,16 +162,16 @@ The following sections provide procedures for submitting a change. | |||
| 162 | Preparing Changes for Submission | 162 | Preparing Changes for Submission |
| 163 | -------------------------------- | 163 | -------------------------------- |
| 164 | 164 | ||
| 165 | 1. *Make Your Changes Locally:* Make your changes in your local Git | 165 | #. *Make Your Changes Locally:* Make your changes in your local Git |
| 166 | repository. You should make small, controlled, isolated changes. | 166 | repository. You should make small, controlled, isolated changes. |
| 167 | Keeping changes small and isolated aids review, makes | 167 | Keeping changes small and isolated aids review, makes |
| 168 | merging/rebasing easier and keeps the change history clean should | 168 | merging/rebasing easier and keeps the change history clean should |
| 169 | anyone need to refer to it in future. | 169 | anyone need to refer to it in future. |
| 170 | 170 | ||
| 171 | 2. *Stage Your Changes:* Stage your changes by using the ``git add`` | 171 | #. *Stage Your Changes:* Stage your changes by using the ``git add`` |
| 172 | command on each file you changed. | 172 | command on each file you changed. |
| 173 | 173 | ||
| 174 | 3. *Commit Your Changes:* Commit the change by using the ``git commit`` | 174 | #. *Commit Your Changes:* Commit the change by using the ``git commit`` |
| 175 | command. Make sure your commit information follows standards by | 175 | command. Make sure your commit information follows standards by |
| 176 | following these accepted conventions: | 176 | following these accepted conventions: |
| 177 | 177 | ||
| @@ -257,7 +257,7 @@ Here is the general procedure on how to submit a patch through email | |||
| 257 | without using the scripts once the steps in | 257 | without using the scripts once the steps in |
| 258 | :ref:`dev-manual/changes:preparing changes for submission` have been followed: | 258 | :ref:`dev-manual/changes:preparing changes for submission` have been followed: |
| 259 | 259 | ||
| 260 | 1. *Format the Commit:* Format the commit into an email message. To | 260 | #. *Format the Commit:* Format the commit into an email message. To |
| 261 | format commits, use the ``git format-patch`` command. When you | 261 | format commits, use the ``git format-patch`` command. When you |
| 262 | provide the command, you must include a revision list or a number of | 262 | provide the command, you must include a revision list or a number of |
| 263 | patches as part of the command. For example, either of these two | 263 | patches as part of the command. For example, either of these two |
| @@ -289,7 +289,7 @@ without using the scripts once the steps in | |||
| 289 | or to OpenEmbedded, you might consider requesting a contrib area | 289 | or to OpenEmbedded, you might consider requesting a contrib area |
| 290 | and the necessary associated rights. | 290 | and the necessary associated rights. |
| 291 | 291 | ||
| 292 | 2. *Send the patches via email:* Send the patches to the recipients and | 292 | #. *Send the patches via email:* Send the patches to the recipients and |
| 293 | relevant mailing lists by using the ``git send-email`` command. | 293 | relevant mailing lists by using the ``git send-email`` command. |
| 294 | 294 | ||
| 295 | .. note:: | 295 | .. note:: |
| @@ -352,7 +352,7 @@ been followed: | |||
| 352 | in the | 352 | in the |
| 353 | `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__. | 353 | `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__. |
| 354 | 354 | ||
| 355 | 1. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for | 355 | #. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for |
| 356 | permissions to push to an upstream contrib repository, push the | 356 | permissions to push to an upstream contrib repository, push the |
| 357 | change to that repository:: | 357 | change to that repository:: |
| 358 | 358 | ||
| @@ -367,7 +367,7 @@ been followed: | |||
| 367 | 367 | ||
| 368 | $ git push meta-intel-contrib your_name/README | 368 | $ git push meta-intel-contrib your_name/README |
| 369 | 369 | ||
| 370 | 2. *Determine Who to Notify:* Determine the maintainer or the mailing | 370 | #. *Determine Who to Notify:* Determine the maintainer or the mailing |
| 371 | list that you need to notify for the change. | 371 | list that you need to notify for the change. |
| 372 | 372 | ||
| 373 | Before submitting any change, you need to be sure who the maintainer | 373 | Before submitting any change, you need to be sure who the maintainer |
| @@ -395,7 +395,7 @@ been followed: | |||
| 395 | lists <resources-mailinglist>`" section in | 395 | lists <resources-mailinglist>`" section in |
| 396 | the Yocto Project Reference Manual. | 396 | the Yocto Project Reference Manual. |
| 397 | 397 | ||
| 398 | 3. *Make a Pull Request:* Notify the maintainer or the mailing list that | 398 | #. *Make a Pull Request:* Notify the maintainer or the mailing list that |
| 399 | you have pushed a change by making a pull request. | 399 | you have pushed a change by making a pull request. |
| 400 | 400 | ||
| 401 | The Yocto Project provides two scripts that conveniently let you | 401 | The Yocto Project provides two scripts that conveniently let you |
| @@ -486,30 +486,30 @@ branch can be obtained from the | |||
| 486 | With this in mind, the steps to submit a change for a stable branch are as | 486 | With this in mind, the steps to submit a change for a stable branch are as |
| 487 | follows: | 487 | follows: |
| 488 | 488 | ||
| 489 | 1. *Identify the bug or CVE to be fixed:* This information should be | 489 | #. *Identify the bug or CVE to be fixed:* This information should be |
| 490 | collected so that it can be included in your submission. | 490 | collected so that it can be included in your submission. |
| 491 | 491 | ||
| 492 | See :ref:`dev-manual/vulnerabilities:checking for vulnerabilities` | 492 | See :ref:`dev-manual/vulnerabilities:checking for vulnerabilities` |
| 493 | for details about CVE tracking. | 493 | for details about CVE tracking. |
| 494 | 494 | ||
| 495 | 2. *Check if the fix is already present in the master branch:* This will | 495 | #. *Check if the fix is already present in the master branch:* This will |
| 496 | result in the most straightforward path into the stable branch for the | 496 | result in the most straightforward path into the stable branch for the |
| 497 | fix. | 497 | fix. |
| 498 | 498 | ||
| 499 | a. *If the fix is present in the master branch --- submit a backport request | 499 | #. *If the fix is present in the master branch --- submit a backport request |
| 500 | by email:* You should send an email to the relevant stable branch | 500 | by email:* You should send an email to the relevant stable branch |
| 501 | maintainer and the mailing list with details of the bug or CVE to be | 501 | maintainer and the mailing list with details of the bug or CVE to be |
| 502 | fixed, the commit hash on the master branch that fixes the issue and | 502 | fixed, the commit hash on the master branch that fixes the issue and |
| 503 | the stable branches which you would like this fix to be backported to. | 503 | the stable branches which you would like this fix to be backported to. |
| 504 | 504 | ||
| 505 | b. *If the fix is not present in the master branch --- submit the fix to the | 505 | #. *If the fix is not present in the master branch --- submit the fix to the |
| 506 | master branch first:* This will ensure that the fix passes through the | 506 | master branch first:* This will ensure that the fix passes through the |
| 507 | project's usual patch review and test processes before being accepted. | 507 | project's usual patch review and test processes before being accepted. |
| 508 | It will also ensure that bugs are not left unresolved in the master | 508 | It will also ensure that bugs are not left unresolved in the master |
| 509 | branch itself. Once the fix is accepted in the master branch a backport | 509 | branch itself. Once the fix is accepted in the master branch a backport |
| 510 | request can be submitted as above. | 510 | request can be submitted as above. |
| 511 | 511 | ||
| 512 | c. *If the fix is unsuitable for the master branch --- submit a patch | 512 | #. *If the fix is unsuitable for the master branch --- submit a patch |
| 513 | directly for the stable branch:* This method should be considered as a | 513 | directly for the stable branch:* This method should be considered as a |
| 514 | last resort. It is typically necessary when the master branch is using | 514 | last resort. It is typically necessary when the master branch is using |
| 515 | a newer version of the software which includes an upstream fix for the | 515 | a newer version of the software which includes an upstream fix for the |
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index f433e8e6a9..921022475f 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst | |||
| @@ -297,11 +297,11 @@ If you are unsure whether a variable dependency is being picked up | |||
| 297 | automatically for a given task, you can list the variable dependencies | 297 | automatically for a given task, you can list the variable dependencies |
| 298 | BitBake has determined by doing the following: | 298 | BitBake has determined by doing the following: |
| 299 | 299 | ||
| 300 | 1. Build the recipe containing the task:: | 300 | #. Build the recipe containing the task:: |
| 301 | 301 | ||
| 302 | $ bitbake recipename | 302 | $ bitbake recipename |
| 303 | 303 | ||
| 304 | 2. Inside the :term:`STAMPS_DIR` | 304 | #. Inside the :term:`STAMPS_DIR` |
| 305 | directory, find the signature data (``sigdata``) file that | 305 | directory, find the signature data (``sigdata``) file that |
| 306 | corresponds to the task. The ``sigdata`` files contain a pickled | 306 | corresponds to the task. The ``sigdata`` files contain a pickled |
| 307 | Python database of all the metadata that went into creating the input | 307 | Python database of all the metadata that went into creating the input |
| @@ -319,7 +319,7 @@ BitBake has determined by doing the following: | |||
| 319 | the cached task output. The ``siginfo`` files contain exactly the | 319 | the cached task output. The ``siginfo`` files contain exactly the |
| 320 | same information as ``sigdata`` files. | 320 | same information as ``sigdata`` files. |
| 321 | 321 | ||
| 322 | 3. Run ``bitbake-dumpsig`` on the ``sigdata`` or ``siginfo`` file. Here | 322 | #. Run ``bitbake-dumpsig`` on the ``sigdata`` or ``siginfo`` file. Here |
| 323 | is an example:: | 323 | is an example:: |
| 324 | 324 | ||
| 325 | $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 | 325 | $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 |
| @@ -992,7 +992,7 @@ site <https://sourceware.org/gdb/documentation/>`__. | |||
| 992 | The following steps show you how to debug using the GNU project | 992 | The following steps show you how to debug using the GNU project |
| 993 | debugger. | 993 | debugger. |
| 994 | 994 | ||
| 995 | 1. *Configure your build system to construct the companion debug | 995 | #. *Configure your build system to construct the companion debug |
| 996 | filesystem:* | 996 | filesystem:* |
| 997 | 997 | ||
| 998 | In your ``local.conf`` file, set the following:: | 998 | In your ``local.conf`` file, set the following:: |
| @@ -1012,7 +1012,7 @@ debugger. | |||
| 1012 | the full filesystem for debugging. Subsequent steps in this procedure | 1012 | the full filesystem for debugging. Subsequent steps in this procedure |
| 1013 | show how to combine the partial filesystem with the full filesystem. | 1013 | show how to combine the partial filesystem with the full filesystem. |
| 1014 | 1014 | ||
| 1015 | 2. *Configure the system to include gdbserver in the target filesystem:* | 1015 | #. *Configure the system to include gdbserver in the target filesystem:* |
| 1016 | 1016 | ||
| 1017 | Make the following addition in your ``local.conf`` file:: | 1017 | Make the following addition in your ``local.conf`` file:: |
| 1018 | 1018 | ||
| @@ -1021,7 +1021,7 @@ debugger. | |||
| 1021 | The change makes | 1021 | The change makes |
| 1022 | sure the ``gdbserver`` package is included. | 1022 | sure the ``gdbserver`` package is included. |
| 1023 | 1023 | ||
| 1024 | 3. *Build the environment:* | 1024 | #. *Build the environment:* |
| 1025 | 1025 | ||
| 1026 | Use the following command to construct the image and the companion | 1026 | Use the following command to construct the image and the companion |
| 1027 | Debug Filesystem:: | 1027 | Debug Filesystem:: |
| @@ -1057,7 +1057,7 @@ debugger. | |||
| 1057 | the actual image (e.g. ``gdb-cross-i586``). The suggestion is usually the | 1057 | the actual image (e.g. ``gdb-cross-i586``). The suggestion is usually the |
| 1058 | actual name you want to use. | 1058 | actual name you want to use. |
| 1059 | 1059 | ||
| 1060 | 4. *Set up the*Â ``debugfs``\ *:* | 1060 | #. *Set up the*Â ``debugfs``\ *:* |
| 1061 | 1061 | ||
| 1062 | Run the following commands to set up the ``debugfs``:: | 1062 | Run the following commands to set up the ``debugfs``:: |
| 1063 | 1063 | ||
| @@ -1066,7 +1066,7 @@ debugger. | |||
| 1066 | $ tar xvfj build-dir/tmp/deploy/images/machine/image.rootfs.tar.bz2 | 1066 | $ tar xvfj build-dir/tmp/deploy/images/machine/image.rootfs.tar.bz2 |
| 1067 | $ tar xvfj build-dir/tmp/deploy/images/machine/image-dbg.rootfs.tar.bz2 | 1067 | $ tar xvfj build-dir/tmp/deploy/images/machine/image-dbg.rootfs.tar.bz2 |
| 1068 | 1068 | ||
| 1069 | 5. *Set up GDB:* | 1069 | #. *Set up GDB:* |
| 1070 | 1070 | ||
| 1071 | Install the SDK (if you built one) and then source the correct | 1071 | Install the SDK (if you built one) and then source the correct |
| 1072 | environment file. Sourcing the environment file puts the SDK in your | 1072 | environment file. Sourcing the environment file puts the SDK in your |
| @@ -1075,7 +1075,7 @@ debugger. | |||
| 1075 | If you are using the build system, Gdb is located in | 1075 | If you are using the build system, Gdb is located in |
| 1076 | `build-dir`\ ``/tmp/sysroots/``\ `host`\ ``/usr/bin/``\ `architecture`\ ``/``\ `architecture`\ ``-gdb`` | 1076 | `build-dir`\ ``/tmp/sysroots/``\ `host`\ ``/usr/bin/``\ `architecture`\ ``/``\ `architecture`\ ``-gdb`` |
| 1077 | 1077 | ||
| 1078 | 6. *Boot the target:* | 1078 | #. *Boot the target:* |
| 1079 | 1079 | ||
| 1080 | For information on how to run QEMU, see the `QEMU | 1080 | For information on how to run QEMU, see the `QEMU |
| 1081 | Documentation <https://wiki.qemu.org/Documentation/GettingStartedDevelopers>`__. | 1081 | Documentation <https://wiki.qemu.org/Documentation/GettingStartedDevelopers>`__. |
| @@ -1084,7 +1084,7 @@ debugger. | |||
| 1084 | 1084 | ||
| 1085 | Be sure to verify that your host can access the target via TCP. | 1085 | Be sure to verify that your host can access the target via TCP. |
| 1086 | 1086 | ||
| 1087 | 7. *Debug a program:* | 1087 | #. *Debug a program:* |
| 1088 | 1088 | ||
| 1089 | Debugging a program involves running gdbserver on the target and then | 1089 | Debugging a program involves running gdbserver on the target and then |
| 1090 | running Gdb on the host. The example in this step debugs ``gzip``: | 1090 | running Gdb on the host. The example in this step debugs ``gzip``: |
| @@ -1116,7 +1116,7 @@ debugger. | |||
| 1116 | users ``~/.gdbinit`` file. Upon starting, Gdb automatically runs whatever | 1116 | users ``~/.gdbinit`` file. Upon starting, Gdb automatically runs whatever |
| 1117 | commands are in that file. | 1117 | commands are in that file. |
| 1118 | 1118 | ||
| 1119 | 8. *Deploying without a full image rebuild:* | 1119 | #. *Deploying without a full image rebuild:* |
| 1120 | 1120 | ||
| 1121 | In many cases, during development you want a quick method to deploy a | 1121 | In many cases, during development you want a quick method to deploy a |
| 1122 | new binary to the target and debug it, without waiting for a full | 1122 | new binary to the target and debug it, without waiting for a full |
diff --git a/documentation/dev-manual/gobject-introspection.rst b/documentation/dev-manual/gobject-introspection.rst index 89f21b7d10..28e51240c3 100644 --- a/documentation/dev-manual/gobject-introspection.rst +++ b/documentation/dev-manual/gobject-introspection.rst | |||
| @@ -39,11 +39,11 @@ Enabling the Generation of Introspection Data | |||
| 39 | Enabling the generation of introspection data (GIR files) in your | 39 | Enabling the generation of introspection data (GIR files) in your |
| 40 | library package involves the following: | 40 | library package involves the following: |
| 41 | 41 | ||
| 42 | 1. Inherit the | 42 | #. Inherit the |
| 43 | :ref:`gobject-introspection <ref-classes-gobject-introspection>` | 43 | :ref:`gobject-introspection <ref-classes-gobject-introspection>` |
| 44 | class. | 44 | class. |
| 45 | 45 | ||
| 46 | 2. Make sure introspection is not disabled anywhere in the recipe or | 46 | #. Make sure introspection is not disabled anywhere in the recipe or |
| 47 | from anything the recipe includes. Also, make sure that | 47 | from anything the recipe includes. Also, make sure that |
| 48 | "gobject-introspection-data" is not in | 48 | "gobject-introspection-data" is not in |
| 49 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | 49 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` |
| @@ -51,7 +51,7 @@ library package involves the following: | |||
| 51 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. | 51 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. |
| 52 | In either of these conditions, nothing will happen. | 52 | In either of these conditions, nothing will happen. |
| 53 | 53 | ||
| 54 | 3. Try to build the recipe. If you encounter build errors that look like | 54 | #. Try to build the recipe. If you encounter build errors that look like |
| 55 | something is unable to find ``.so`` libraries, check where these | 55 | something is unable to find ``.so`` libraries, check where these |
| 56 | libraries are located in the source tree and add the following to the | 56 | libraries are located in the source tree and add the following to the |
| 57 | recipe:: | 57 | recipe:: |
| @@ -63,7 +63,7 @@ library package involves the following: | |||
| 63 | See recipes in the ``oe-core`` repository that use that | 63 | See recipes in the ``oe-core`` repository that use that |
| 64 | :term:`GIR_EXTRA_LIBS_PATH` variable as an example. | 64 | :term:`GIR_EXTRA_LIBS_PATH` variable as an example. |
| 65 | 65 | ||
| 66 | 4. Look for any other errors, which probably mean that introspection | 66 | #. Look for any other errors, which probably mean that introspection |
| 67 | support in a package is not entirely standard, and thus breaks down | 67 | support in a package is not entirely standard, and thus breaks down |
| 68 | in a cross-compilation environment. For such cases, custom-made fixes | 68 | in a cross-compilation environment. For such cases, custom-made fixes |
| 69 | are needed. A good place to ask and receive help in these cases is | 69 | are needed. A good place to ask and receive help in these cases is |
| @@ -116,21 +116,21 @@ Testing that Introspection Works in an Image | |||
| 116 | Use the following procedure to test if generating introspection data is | 116 | Use the following procedure to test if generating introspection data is |
| 117 | working in an image: | 117 | working in an image: |
| 118 | 118 | ||
| 119 | 1. Make sure that "gobject-introspection-data" is not in | 119 | #. Make sure that "gobject-introspection-data" is not in |
| 120 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | 120 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` |
| 121 | and that "qemu-usermode" is not in | 121 | and that "qemu-usermode" is not in |
| 122 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. | 122 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. |
| 123 | 123 | ||
| 124 | 2. Build ``core-image-sato``. | 124 | #. Build ``core-image-sato``. |
| 125 | 125 | ||
| 126 | 3. Launch a Terminal and then start Python in the terminal. | 126 | #. Launch a Terminal and then start Python in the terminal. |
| 127 | 127 | ||
| 128 | 4. Enter the following in the terminal:: | 128 | #. Enter the following in the terminal:: |
| 129 | 129 | ||
| 130 | >>> from gi.repository import GLib | 130 | >>> from gi.repository import GLib |
| 131 | >>> GLib.get_host_name() | 131 | >>> GLib.get_host_name() |
| 132 | 132 | ||
| 133 | 5. For something a little more advanced, enter the following see: | 133 | #. For something a little more advanced, enter the following see: |
| 134 | https://python-gtk-3-tutorial.readthedocs.io/en/latest/introduction.html | 134 | https://python-gtk-3-tutorial.readthedocs.io/en/latest/introduction.html |
| 135 | 135 | ||
| 136 | Known Issues | 136 | Known Issues |
diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst index ad22524833..2d809562d1 100644 --- a/documentation/dev-manual/layers.rst +++ b/documentation/dev-manual/layers.rst | |||
| @@ -28,14 +28,14 @@ Creating Your Own Layer | |||
| 28 | 28 | ||
| 29 | Follow these general steps to create your layer without using tools: | 29 | Follow these general steps to create your layer without using tools: |
| 30 | 30 | ||
| 31 | 1. *Check Existing Layers:* Before creating a new layer, you should be | 31 | #. *Check Existing Layers:* Before creating a new layer, you should be |
| 32 | sure someone has not already created a layer containing the Metadata | 32 | sure someone has not already created a layer containing the Metadata |
| 33 | you need. You can see the :oe_layerindex:`OpenEmbedded Metadata Index <>` | 33 | you need. You can see the :oe_layerindex:`OpenEmbedded Metadata Index <>` |
| 34 | for a list of layers from the OpenEmbedded community that can be used in | 34 | for a list of layers from the OpenEmbedded community that can be used in |
| 35 | the Yocto Project. You could find a layer that is identical or close | 35 | the Yocto Project. You could find a layer that is identical or close |
| 36 | to what you need. | 36 | to what you need. |
| 37 | 37 | ||
| 38 | 2. *Create a Directory:* Create the directory for your layer. When you | 38 | #. *Create a Directory:* Create the directory for your layer. When you |
| 39 | create the layer, be sure to create the directory in an area not | 39 | create the layer, be sure to create the directory in an area not |
| 40 | associated with the Yocto Project :term:`Source Directory` | 40 | associated with the Yocto Project :term:`Source Directory` |
| 41 | (e.g. the cloned ``poky`` repository). | 41 | (e.g. the cloned ``poky`` repository). |
| @@ -58,7 +58,7 @@ Follow these general steps to create your layer without using tools: | |||
| 58 | "meta-" string are appended to several variables used in the | 58 | "meta-" string are appended to several variables used in the |
| 59 | configuration. | 59 | configuration. |
| 60 | 60 | ||
| 61 | 3. *Create a Layer Configuration File:* Inside your new layer folder, | 61 | #. *Create a Layer Configuration File:* Inside your new layer folder, |
| 62 | you need to create a ``conf/layer.conf`` file. It is easiest to take | 62 | you need to create a ``conf/layer.conf`` file. It is easiest to take |
| 63 | an existing layer configuration file and copy that to your layer's | 63 | an existing layer configuration file and copy that to your layer's |
| 64 | ``conf`` directory and then modify the file as needed. | 64 | ``conf`` directory and then modify the file as needed. |
| @@ -128,7 +128,7 @@ Follow these general steps to create your layer without using tools: | |||
| 128 | variable is a good way to indicate if your particular layer is | 128 | variable is a good way to indicate if your particular layer is |
| 129 | current. | 129 | current. |
| 130 | 130 | ||
| 131 | 4. *Add Content:* Depending on the type of layer, add the content. If | 131 | #. *Add Content:* Depending on the type of layer, add the content. If |
| 132 | the layer adds support for a machine, add the machine configuration | 132 | the layer adds support for a machine, add the machine configuration |
| 133 | in a ``conf/machine/`` file within the layer. If the layer adds | 133 | in a ``conf/machine/`` file within the layer. If the layer adds |
| 134 | distro policy, add the distro configuration in a ``conf/distro/`` | 134 | distro policy, add the distro configuration in a ``conf/distro/`` |
| @@ -141,7 +141,7 @@ Follow these general steps to create your layer without using tools: | |||
| 141 | Yocto Project, see the ":ref:`bsp-guide/bsp:example filesystem layout`" | 141 | Yocto Project, see the ":ref:`bsp-guide/bsp:example filesystem layout`" |
| 142 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | 142 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. |
| 143 | 143 | ||
| 144 | 5. *Optionally Test for Compatibility:* If you want permission to use | 144 | #. *Optionally Test for Compatibility:* If you want permission to use |
| 145 | the Yocto Project Compatibility logo with your layer or application | 145 | the Yocto Project Compatibility logo with your layer or application |
| 146 | that uses your layer, perform the steps to apply for compatibility. | 146 | that uses your layer, perform the steps to apply for compatibility. |
| 147 | See the | 147 | See the |
| @@ -292,13 +292,13 @@ The Yocto Project Compatibility Program consists of a layer application | |||
| 292 | process that requests permission to use the Yocto Project Compatibility | 292 | process that requests permission to use the Yocto Project Compatibility |
| 293 | Logo for your layer and application. The process consists of two parts: | 293 | Logo for your layer and application. The process consists of two parts: |
| 294 | 294 | ||
| 295 | 1. Successfully passing a script (``yocto-check-layer``) that when run | 295 | #. Successfully passing a script (``yocto-check-layer``) that when run |
| 296 | against your layer, tests it against constraints based on experiences | 296 | against your layer, tests it against constraints based on experiences |
| 297 | of how layers have worked in the real world and where pitfalls have | 297 | of how layers have worked in the real world and where pitfalls have |
| 298 | been found. Getting a "PASS" result from the script is required for | 298 | been found. Getting a "PASS" result from the script is required for |
| 299 | successful compatibility registration. | 299 | successful compatibility registration. |
| 300 | 300 | ||
| 301 | 2. Completion of an application acceptance form, which you can find at | 301 | #. Completion of an application acceptance form, which you can find at |
| 302 | :yocto_home:`/webform/yocto-project-compatible-registration`. | 302 | :yocto_home:`/webform/yocto-project-compatible-registration`. |
| 303 | 303 | ||
| 304 | To be granted permission to use the logo, you need to satisfy the | 304 | To be granted permission to use the logo, you need to satisfy the |
| @@ -870,10 +870,10 @@ checked out first), or into a completely independent location. | |||
| 870 | The replication of the layers is performed by running the ``setup-layers`` script provided | 870 | The replication of the layers is performed by running the ``setup-layers`` script provided |
| 871 | above: | 871 | above: |
| 872 | 872 | ||
| 873 | 1. Clone the bootstrap layer or some other repository to obtain | 873 | #. Clone the bootstrap layer or some other repository to obtain |
| 874 | the json config and the setup script that can use it. | 874 | the json config and the setup script that can use it. |
| 875 | 875 | ||
| 876 | 2. Run the script directly with no options:: | 876 | #. Run the script directly with no options:: |
| 877 | 877 | ||
| 878 | alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers | 878 | alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers |
| 879 | Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. | 879 | Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. |
diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst index afd8bfc945..2decdcb253 100644 --- a/documentation/dev-manual/packages.rst +++ b/documentation/dev-manual/packages.rst | |||
| @@ -554,10 +554,10 @@ to use. In your configuration, you use the | |||
| 554 | :term:`PACKAGE_CLASSES` | 554 | :term:`PACKAGE_CLASSES` |
| 555 | variable to specify the format: | 555 | variable to specify the format: |
| 556 | 556 | ||
| 557 | 1. Open the ``local.conf`` file inside your :term:`Build Directory` (e.g. | 557 | #. Open the ``local.conf`` file inside your :term:`Build Directory` (e.g. |
| 558 | ``poky/build/conf/local.conf``). | 558 | ``poky/build/conf/local.conf``). |
| 559 | 559 | ||
| 560 | 2. Select the desired package format as follows:: | 560 | #. Select the desired package format as follows:: |
| 561 | 561 | ||
| 562 | PACKAGE_CLASSES ?= "package_packageformat" | 562 | PACKAGE_CLASSES ?= "package_packageformat" |
| 563 | 563 | ||
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst index 084e67580d..d431ea4b99 100644 --- a/documentation/dev-manual/qemu.rst +++ b/documentation/dev-manual/qemu.rst | |||
| @@ -44,13 +44,13 @@ To use QEMU, you need to have QEMU installed and initialized as well as | |||
| 44 | have the proper artifacts (i.e. image files and root filesystems) | 44 | have the proper artifacts (i.e. image files and root filesystems) |
| 45 | available. Follow these general steps to run QEMU: | 45 | available. Follow these general steps to run QEMU: |
| 46 | 46 | ||
| 47 | 1. *Install QEMU:* QEMU is made available with the Yocto Project a | 47 | #. *Install QEMU:* QEMU is made available with the Yocto Project a |
| 48 | number of ways. One method is to install a Software Development Kit | 48 | number of ways. One method is to install a Software Development Kit |
| 49 | (SDK). See ":ref:`sdk-manual/intro:the qemu emulator`" section in the | 49 | (SDK). See ":ref:`sdk-manual/intro:the qemu emulator`" section in the |
| 50 | Yocto Project Application Development and the Extensible Software | 50 | Yocto Project Application Development and the Extensible Software |
| 51 | Development Kit (eSDK) manual for information on how to install QEMU. | 51 | Development Kit (eSDK) manual for information on how to install QEMU. |
| 52 | 52 | ||
| 53 | 2. *Setting Up the Environment:* How you set up the QEMU environment | 53 | #. *Setting Up the Environment:* How you set up the QEMU environment |
| 54 | depends on how you installed QEMU: | 54 | depends on how you installed QEMU: |
| 55 | 55 | ||
| 56 | - If you cloned the ``poky`` repository or you downloaded and | 56 | - If you cloned the ``poky`` repository or you downloaded and |
| @@ -66,7 +66,7 @@ available. Follow these general steps to run QEMU: | |||
| 66 | 66 | ||
| 67 | . poky_sdk/environment-setup-core2-64-poky-linux | 67 | . poky_sdk/environment-setup-core2-64-poky-linux |
| 68 | 68 | ||
| 69 | 3. *Ensure the Artifacts are in Place:* You need to be sure you have a | 69 | #. *Ensure the Artifacts are in Place:* You need to be sure you have a |
| 70 | pre-built kernel that will boot in QEMU. You also need the target | 70 | pre-built kernel that will boot in QEMU. You also need the target |
| 71 | root filesystem for your target machine's architecture: | 71 | root filesystem for your target machine's architecture: |
| 72 | 72 | ||
| @@ -84,7 +84,7 @@ available. Follow these general steps to run QEMU: | |||
| 84 | Extensible Software Development Kit (eSDK) manual for information on | 84 | Extensible Software Development Kit (eSDK) manual for information on |
| 85 | how to extract a root filesystem. | 85 | how to extract a root filesystem. |
| 86 | 86 | ||
| 87 | 4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:: | 87 | #. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:: |
| 88 | 88 | ||
| 89 | $ runqemu [option ] [...] | 89 | $ runqemu [option ] [...] |
| 90 | 90 | ||
| @@ -184,7 +184,7 @@ the system does not need root privileges to run. It uses a user space | |||
| 184 | NFS server to avoid that. Follow these steps to set up for running QEMU | 184 | NFS server to avoid that. Follow these steps to set up for running QEMU |
| 185 | using an NFS server. | 185 | using an NFS server. |
| 186 | 186 | ||
| 187 | 1. *Extract a Root Filesystem:* Once you are able to run QEMU in your | 187 | #. *Extract a Root Filesystem:* Once you are able to run QEMU in your |
| 188 | environment, you can use the ``runqemu-extract-sdk`` script, which is | 188 | environment, you can use the ``runqemu-extract-sdk`` script, which is |
| 189 | located in the ``scripts`` directory along with the ``runqemu`` | 189 | located in the ``scripts`` directory along with the ``runqemu`` |
| 190 | script. | 190 | script. |
| @@ -198,7 +198,7 @@ using an NFS server. | |||
| 198 | 198 | ||
| 199 | runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs | 199 | runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs |
| 200 | 200 | ||
| 201 | 2. *Start QEMU:* Once you have extracted the file system, you can run | 201 | #. *Start QEMU:* Once you have extracted the file system, you can run |
| 202 | ``runqemu`` normally with the additional location of the file system. | 202 | ``runqemu`` normally with the additional location of the file system. |
| 203 | You can then also make changes to the files within ``./test-nfs`` and | 203 | You can then also make changes to the files within ``./test-nfs`` and |
| 204 | see those changes appear in the image in real time. Here is an | 204 | see those changes appear in the image in real time. Here is an |
diff --git a/documentation/dev-manual/quilt.rst b/documentation/dev-manual/quilt.rst index 1dd9ff02d4..24343e2fac 100644 --- a/documentation/dev-manual/quilt.rst +++ b/documentation/dev-manual/quilt.rst | |||
| @@ -20,32 +20,32 @@ form of a patch all using Quilt. | |||
| 20 | 20 | ||
| 21 | Follow these general steps: | 21 | Follow these general steps: |
| 22 | 22 | ||
| 23 | 1. *Find the Source Code:* Temporary source code used by the | 23 | #. *Find the Source Code:* Temporary source code used by the |
| 24 | OpenEmbedded build system is kept in the :term:`Build Directory`. See the | 24 | OpenEmbedded build system is kept in the :term:`Build Directory`. See the |
| 25 | ":ref:`dev-manual/temporary-source-code:finding temporary source code`" section to | 25 | ":ref:`dev-manual/temporary-source-code:finding temporary source code`" section to |
| 26 | learn how to locate the directory that has the temporary source code for a | 26 | learn how to locate the directory that has the temporary source code for a |
| 27 | particular package. | 27 | particular package. |
| 28 | 28 | ||
| 29 | 2. *Change Your Working Directory:* You need to be in the directory that | 29 | #. *Change Your Working Directory:* You need to be in the directory that |
| 30 | has the temporary source code. That directory is defined by the | 30 | has the temporary source code. That directory is defined by the |
| 31 | :term:`S` variable. | 31 | :term:`S` variable. |
| 32 | 32 | ||
| 33 | 3. *Create a New Patch:* Before modifying source code, you need to | 33 | #. *Create a New Patch:* Before modifying source code, you need to |
| 34 | create a new patch. To create a new patch file, use ``quilt new`` as | 34 | create a new patch. To create a new patch file, use ``quilt new`` as |
| 35 | below:: | 35 | below:: |
| 36 | 36 | ||
| 37 | $ quilt new my_changes.patch | 37 | $ quilt new my_changes.patch |
| 38 | 38 | ||
| 39 | 4. *Notify Quilt and Add Files:* After creating the patch, you need to | 39 | #. *Notify Quilt and Add Files:* After creating the patch, you need to |
| 40 | notify Quilt about the files you plan to edit. You notify Quilt by | 40 | notify Quilt about the files you plan to edit. You notify Quilt by |
| 41 | adding the files to the patch you just created:: | 41 | adding the files to the patch you just created:: |
| 42 | 42 | ||
| 43 | $ quilt add file1.c file2.c file3.c | 43 | $ quilt add file1.c file2.c file3.c |
| 44 | 44 | ||
| 45 | 5. *Edit the Files:* Make your changes in the source code to the files | 45 | #. *Edit the Files:* Make your changes in the source code to the files |
| 46 | you added to the patch. | 46 | you added to the patch. |
| 47 | 47 | ||
| 48 | 6. *Test Your Changes:* Once you have modified the source code, the | 48 | #. *Test Your Changes:* Once you have modified the source code, the |
| 49 | easiest way to test your changes is by calling the :ref:`ref-tasks-compile` | 49 | easiest way to test your changes is by calling the :ref:`ref-tasks-compile` |
| 50 | task as shown in the following example:: | 50 | task as shown in the following example:: |
| 51 | 51 | ||
| @@ -65,7 +65,7 @@ Follow these general steps: | |||
| 65 | the ":ref:`dev-manual/disk-space:conserving disk space during builds`" | 65 | the ":ref:`dev-manual/disk-space:conserving disk space during builds`" |
| 66 | section. | 66 | section. |
| 67 | 67 | ||
| 68 | 7. *Generate the Patch:* Once your changes work as expected, you need to | 68 | #. *Generate the Patch:* Once your changes work as expected, you need to |
| 69 | use Quilt to generate the final patch that contains all your | 69 | use Quilt to generate the final patch that contains all your |
| 70 | modifications:: | 70 | modifications:: |
| 71 | 71 | ||
| @@ -78,7 +78,7 @@ Follow these general steps: | |||
| 78 | You can find the resulting patch file in the ``patches/`` | 78 | You can find the resulting patch file in the ``patches/`` |
| 79 | subdirectory of the source (:term:`S`) directory. | 79 | subdirectory of the source (:term:`S`) directory. |
| 80 | 80 | ||
| 81 | 8. *Copy the Patch File:* For simplicity, copy the patch file into a | 81 | #. *Copy the Patch File:* For simplicity, copy the patch file into a |
| 82 | directory named ``files``, which you can create in the same directory | 82 | directory named ``files``, which you can create in the same directory |
| 83 | that holds the recipe (``.bb``) file or the append (``.bbappend``) | 83 | that holds the recipe (``.bb``) file or the append (``.bbappend``) |
| 84 | file. Placing the patch here guarantees that the OpenEmbedded build | 84 | file. Placing the patch here guarantees that the OpenEmbedded build |
diff --git a/documentation/dev-manual/runtime-testing.rst b/documentation/dev-manual/runtime-testing.rst index 88b3ed541b..36ccf746ee 100644 --- a/documentation/dev-manual/runtime-testing.rst +++ b/documentation/dev-manual/runtime-testing.rst | |||
| @@ -84,25 +84,25 @@ In order to run tests, you need to do the following: | |||
| 84 | 84 | ||
| 85 | Once you start running the tests, the following happens: | 85 | Once you start running the tests, the following happens: |
| 86 | 86 | ||
| 87 | 1. A copy of the root filesystem is written to ``${WORKDIR}/testimage``. | 87 | #. A copy of the root filesystem is written to ``${WORKDIR}/testimage``. |
| 88 | 88 | ||
| 89 | 2. The image is booted under QEMU using the standard ``runqemu`` script. | 89 | #. The image is booted under QEMU using the standard ``runqemu`` script. |
| 90 | 90 | ||
| 91 | 3. A default timeout of 500 seconds occurs to allow for the boot process | 91 | #. A default timeout of 500 seconds occurs to allow for the boot process |
| 92 | to reach the login prompt. You can change the timeout period by | 92 | to reach the login prompt. You can change the timeout period by |
| 93 | setting | 93 | setting |
| 94 | :term:`TEST_QEMUBOOT_TIMEOUT` | 94 | :term:`TEST_QEMUBOOT_TIMEOUT` |
| 95 | in the ``local.conf`` file. | 95 | in the ``local.conf`` file. |
| 96 | 96 | ||
| 97 | 4. Once the boot process is reached and the login prompt appears, the | 97 | #. Once the boot process is reached and the login prompt appears, the |
| 98 | tests run. The full boot log is written to | 98 | tests run. The full boot log is written to |
| 99 | ``${WORKDIR}/testimage/qemu_boot_log``. | 99 | ``${WORKDIR}/testimage/qemu_boot_log``. |
| 100 | 100 | ||
| 101 | 5. Each test module loads in the order found in :term:`TEST_SUITES`. You can | 101 | #. Each test module loads in the order found in :term:`TEST_SUITES`. You can |
| 102 | find the full output of the commands run over SSH in | 102 | find the full output of the commands run over SSH in |
| 103 | ``${WORKDIR}/testimgage/ssh_target_log``. | 103 | ``${WORKDIR}/testimgage/ssh_target_log``. |
| 104 | 104 | ||
| 105 | 6. If no failures occur, the task running the tests ends successfully. | 105 | #. If no failures occur, the task running the tests ends successfully. |
| 106 | You can find the output from the ``unittest`` in the task log at | 106 | You can find the output from the ``unittest`` in the task log at |
| 107 | ``${WORKDIR}/temp/log.do_testimage``. | 107 | ``${WORKDIR}/temp/log.do_testimage``. |
| 108 | 108 | ||
| @@ -117,13 +117,13 @@ For automated deployment, a "controller image" is installed onto the | |||
| 117 | hardware once as part of setup. Then, each time tests are to be run, the | 117 | hardware once as part of setup. Then, each time tests are to be run, the |
| 118 | following occurs: | 118 | following occurs: |
| 119 | 119 | ||
| 120 | 1. The controller image is booted into and used to write the image to be | 120 | #. The controller image is booted into and used to write the image to be |
| 121 | tested to a second partition. | 121 | tested to a second partition. |
| 122 | 122 | ||
| 123 | 2. The device is then rebooted using an external script that you need to | 123 | #. The device is then rebooted using an external script that you need to |
| 124 | provide. | 124 | provide. |
| 125 | 125 | ||
| 126 | 3. The device boots into the image to be tested. | 126 | #. The device boots into the image to be tested. |
| 127 | 127 | ||
| 128 | When running tests (independent of whether the image has been deployed | 128 | When running tests (independent of whether the image has been deployed |
| 129 | automatically or not), the device is expected to be connected to a | 129 | automatically or not), the device is expected to be connected to a |
| @@ -188,11 +188,11 @@ not need any information in this section. You can skip down to the | |||
| 188 | If you did set :term:`TEST_TARGET` to "SystemdbootTarget", you also need to | 188 | If you did set :term:`TEST_TARGET` to "SystemdbootTarget", you also need to |
| 189 | perform a one-time setup of your controller image by doing the following: | 189 | perform a one-time setup of your controller image by doing the following: |
| 190 | 190 | ||
| 191 | 1. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows:: | 191 | #. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows:: |
| 192 | 192 | ||
| 193 | EFI_PROVIDER = "systemd-boot" | 193 | EFI_PROVIDER = "systemd-boot" |
| 194 | 194 | ||
| 195 | 2. *Build the controller image:* Build the ``core-image-testmaster`` image. | 195 | #. *Build the controller image:* Build the ``core-image-testmaster`` image. |
| 196 | The ``core-image-testmaster`` recipe is provided as an example for a | 196 | The ``core-image-testmaster`` recipe is provided as an example for a |
| 197 | "controller" image and you can customize the image recipe as you would | 197 | "controller" image and you can customize the image recipe as you would |
| 198 | any other recipe. | 198 | any other recipe. |
| @@ -219,13 +219,13 @@ perform a one-time setup of your controller image by doing the following: | |||
| 219 | - Another partition labeled "testrootfs" where test images get | 219 | - Another partition labeled "testrootfs" where test images get |
| 220 | deployed. | 220 | deployed. |
| 221 | 221 | ||
| 222 | 3. *Install image:* Install the image that you just built on the target | 222 | #. *Install image:* Install the image that you just built on the target |
| 223 | system. | 223 | system. |
| 224 | 224 | ||
| 225 | The final thing you need to do when setting :term:`TEST_TARGET` to | 225 | The final thing you need to do when setting :term:`TEST_TARGET` to |
| 226 | "SystemdbootTarget" is to set up the test image: | 226 | "SystemdbootTarget" is to set up the test image: |
| 227 | 227 | ||
| 228 | 1. *Set up your local.conf file:* Make sure you have the following | 228 | #. *Set up your local.conf file:* Make sure you have the following |
| 229 | statements in your ``local.conf`` file:: | 229 | statements in your ``local.conf`` file:: |
| 230 | 230 | ||
| 231 | IMAGE_FSTYPES += "tar.gz" | 231 | IMAGE_FSTYPES += "tar.gz" |
| @@ -233,7 +233,7 @@ The final thing you need to do when setting :term:`TEST_TARGET` to | |||
| 233 | TEST_TARGET = "SystemdbootTarget" | 233 | TEST_TARGET = "SystemdbootTarget" |
| 234 | TEST_TARGET_IP = "192.168.2.3" | 234 | TEST_TARGET_IP = "192.168.2.3" |
| 235 | 235 | ||
| 236 | 2. *Build your test image:* Use BitBake to build the image:: | 236 | #. *Build your test image:* Use BitBake to build the image:: |
| 237 | 237 | ||
| 238 | $ bitbake core-image-sato | 238 | $ bitbake core-image-sato |
| 239 | 239 | ||
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. | |||
| 29 | You can build off these steps and customize the procedure to fit any | 29 | You can build off these steps and customize the procedure to fit any |
| 30 | particular working environment and set of practices. | 30 | particular working environment and set of practices. |
| 31 | 31 | ||
| 32 | 1. *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 | ||
| 55 | 2. *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 | ||
| 69 | 3. *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 | ||
| 75 | 4. *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 | ||
| 112 | 5. *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 | ||
| 131 | 6. *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 | ||
| 148 | 7. *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 | ||
| 186 | 8. *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 | ||
| 191 | 9. *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 | ||
| 216 | 10. *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 | |||
| 296 | Follow these steps to prepare a native Linux machine as your Yocto | 296 | Follow these steps to prepare a native Linux machine as your Yocto |
| 297 | Project Build Host: | 297 | Project Build Host: |
| 298 | 298 | ||
| 299 | 1. *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 | ||
| 309 | 2. *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 | ||
| 312 | 3. *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 | ||
| 332 | 4. *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. | |||
| 361 | Follow these general steps to prepare a Windows, Mac, or Linux machine | 361 | Follow these general steps to prepare a Windows, Mac, or Linux machine |
| 362 | as your Yocto Project build host: | 362 | as your Yocto Project build host: |
| 363 | 363 | ||
| 364 | 1. *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 | ||
| 373 | 2. *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 | ||
| 380 | 3. *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 | ||
| 386 | 4. *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 | ||
| 415 | 5. *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 | ||
| 419 | 6. *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 | ||
| 423 | 7. *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. | |||
| 453 | Follow these general steps to prepare a Windows machine using WSL 2 as | 453 | Follow these general steps to prepare a Windows machine using WSL 2 as |
| 454 | your Yocto Project build host: | 454 | your Yocto Project build host: |
| 455 | 455 | ||
| 456 | 1. *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 | ||
| 472 | 2. *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 | ||
| 482 | 3. *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 | ||
| 492 | 4. *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 | ||
| 495 | 5. *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 | ||
| 498 | 6. *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`. | |||
| 597 | Use the following procedure to locate the latest upstream copy of the | 597 | Use the following procedure to locate the latest upstream copy of the |
| 598 | ``poky`` Git repository: | 598 | ``poky`` Git repository: |
| 599 | 599 | ||
| 600 | 1. *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 | ||
| 604 | 2. *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 | ||
| 607 | 3. *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 | ||
| 631 | Follow these steps to locate and download a particular tarball: | 631 | Follow these steps to locate and download a particular tarball: |
| 632 | 632 | ||
| 633 | 1. *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 | ||
| 645 | 2. *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 | ||
| 648 | 3. *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 | ||
| 652 | 4. *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 | ||
| 655 | Using the Downloads Page | 655 | Using the Downloads Page |
| @@ -661,13 +661,13 @@ release. Rather than Git repositories, these files represent snapshot | |||
| 661 | tarballs similar to the tarballs located in the Index of Releases | 661 | tarballs similar to the tarballs located in the Index of Releases |
| 662 | described in the ":ref:`dev-manual/start:accessing index of releases`" section. | 662 | described in the ":ref:`dev-manual/start:accessing index of releases`" section. |
| 663 | 663 | ||
| 664 | 1. *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 | ||
| 667 | 2. *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 | ||
| 670 | 3. *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 | ||
| 682 | 4. *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 | |||
| 707 | Follow these steps to create a local version of the upstream | 707 | Follow these steps to create a local version of the upstream |
| 708 | :term:`Poky` Git repository. | 708 | :term:`Poky` Git repository. |
| 709 | 709 | ||
| 710 | 1. *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 | ||
| 713 | 2. *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 | ||
| 769 | 1. *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 | ||
| 775 | 2. *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 | ||
| 796 | 3. *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 | ||
| 830 | 1. *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 | ||
| 836 | 2. *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 | ||
| 842 | 3. *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 | ||
| 864 | 4. *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; |
diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst index c41e3e1a5d..dd220cc6c8 100644 --- a/documentation/dev-manual/upgrading-recipes.rst +++ b/documentation/dev-manual/upgrading-recipes.rst | |||
| @@ -51,12 +51,12 @@ commit messages in the layer's tree for the changes made to recipes. | |||
| 51 | 51 | ||
| 52 | The following steps describe how to set up the AUH utility: | 52 | The following steps describe how to set up the AUH utility: |
| 53 | 53 | ||
| 54 | 1. *Be Sure the Development Host is Set Up:* You need to be sure that | 54 | #. *Be Sure the Development Host is Set Up:* You need to be sure that |
| 55 | your development host is set up to use the Yocto Project. For | 55 | your development host is set up to use the Yocto Project. For |
| 56 | information on how to set up your host, see the | 56 | information on how to set up your host, see the |
| 57 | ":ref:`dev-manual/start:Preparing the Build Host`" section. | 57 | ":ref:`dev-manual/start:Preparing the Build Host`" section. |
| 58 | 58 | ||
| 59 | 2. *Make Sure Git is Configured:* The AUH utility requires Git to be | 59 | #. *Make Sure Git is Configured:* The AUH utility requires Git to be |
| 60 | configured because AUH uses Git to save upgrades. Thus, you must have | 60 | configured because AUH uses Git to save upgrades. Thus, you must have |
| 61 | Git user and email configured. The following command shows your | 61 | Git user and email configured. The following command shows your |
| 62 | configurations:: | 62 | configurations:: |
| @@ -69,7 +69,7 @@ The following steps describe how to set up the AUH utility: | |||
| 69 | $ git config --global user.name some_name | 69 | $ git config --global user.name some_name |
| 70 | $ git config --global user.email username@domain.com | 70 | $ git config --global user.email username@domain.com |
| 71 | 71 | ||
| 72 | 3. *Clone the AUH Repository:* To use AUH, you must clone the repository | 72 | #. *Clone the AUH Repository:* To use AUH, you must clone the repository |
| 73 | onto your development host. The following command uses Git to create | 73 | onto your development host. The following command uses Git to create |
| 74 | a local copy of the repository on your system:: | 74 | a local copy of the repository on your system:: |
| 75 | 75 | ||
| @@ -84,7 +84,7 @@ The following steps describe how to set up the AUH utility: | |||
| 84 | AUH is not part of the :term:`OpenEmbedded-Core (OE-Core)` or | 84 | AUH is not part of the :term:`OpenEmbedded-Core (OE-Core)` or |
| 85 | :term:`Poky` repositories. | 85 | :term:`Poky` repositories. |
| 86 | 86 | ||
| 87 | 4. *Create a Dedicated Build Directory:* Run the :ref:`structure-core-script` | 87 | #. *Create a Dedicated Build Directory:* Run the :ref:`structure-core-script` |
| 88 | script to create a fresh :term:`Build Directory` that you use exclusively | 88 | script to create a fresh :term:`Build Directory` that you use exclusively |
| 89 | for running the AUH utility:: | 89 | for running the AUH utility:: |
| 90 | 90 | ||
| @@ -95,7 +95,7 @@ The following steps describe how to set up the AUH utility: | |||
| 95 | recommended as existing settings could cause AUH to fail or behave | 95 | recommended as existing settings could cause AUH to fail or behave |
| 96 | undesirably. | 96 | undesirably. |
| 97 | 97 | ||
| 98 | 5. *Make Configurations in Your Local Configuration File:* Several | 98 | #. *Make Configurations in Your Local Configuration File:* Several |
| 99 | settings are needed in the ``local.conf`` file in the build | 99 | settings are needed in the ``local.conf`` file in the build |
| 100 | directory you just created for AUH. Make these following | 100 | directory you just created for AUH. Make these following |
| 101 | configurations: | 101 | configurations: |
| @@ -128,13 +128,13 @@ The following steps describe how to set up the AUH utility: | |||
| 128 | DISTRO_FEATURES:append = " ptest" | 128 | DISTRO_FEATURES:append = " ptest" |
| 129 | 129 | ||
| 130 | 130 | ||
| 131 | 6. *Optionally Start a vncserver:* If you are running in a server | 131 | #. *Optionally Start a vncserver:* If you are running in a server |
| 132 | without an X11 session, you need to start a vncserver:: | 132 | without an X11 session, you need to start a vncserver:: |
| 133 | 133 | ||
| 134 | $ vncserver :1 | 134 | $ vncserver :1 |
| 135 | $ export DISPLAY=:1 | 135 | $ export DISPLAY=:1 |
| 136 | 136 | ||
| 137 | 7. *Create and Edit an AUH Configuration File:* You need to have the | 137 | #. *Create and Edit an AUH Configuration File:* You need to have the |
| 138 | ``upgrade-helper/upgrade-helper.conf`` configuration file in your | 138 | ``upgrade-helper/upgrade-helper.conf`` configuration file in your |
| 139 | :term:`Build Directory`. You can find a sample configuration file in the | 139 | :term:`Build Directory`. You can find a sample configuration file in the |
| 140 | :yocto_git:`AUH source repository </auto-upgrade-helper/tree/>`. | 140 | :yocto_git:`AUH source repository </auto-upgrade-helper/tree/>`. |
| @@ -346,17 +346,17 @@ you can manually edit the recipe files to upgrade the versions. | |||
| 346 | 346 | ||
| 347 | To manually upgrade recipe versions, follow these general steps: | 347 | To manually upgrade recipe versions, follow these general steps: |
| 348 | 348 | ||
| 349 | 1. *Change the Version:* Rename the recipe such that the version (i.e. | 349 | #. *Change the Version:* Rename the recipe such that the version (i.e. |
| 350 | the :term:`PV` part of the recipe name) | 350 | the :term:`PV` part of the recipe name) |
| 351 | changes appropriately. If the version is not part of the recipe name, | 351 | changes appropriately. If the version is not part of the recipe name, |
| 352 | change the value as it is set for :term:`PV` within the recipe itself. | 352 | change the value as it is set for :term:`PV` within the recipe itself. |
| 353 | 353 | ||
| 354 | 2. *Update* :term:`SRCREV` *if Needed*: If the source code your recipe builds | 354 | #. *Update* :term:`SRCREV` *if Needed*: If the source code your recipe builds |
| 355 | is fetched from Git or some other version control system, update | 355 | is fetched from Git or some other version control system, update |
| 356 | :term:`SRCREV` to point to the | 356 | :term:`SRCREV` to point to the |
| 357 | commit hash that matches the new version. | 357 | commit hash that matches the new version. |
| 358 | 358 | ||
| 359 | 3. *Build the Software:* Try to build the recipe using BitBake. Typical | 359 | #. *Build the Software:* Try to build the recipe using BitBake. Typical |
| 360 | build failures include the following: | 360 | build failures include the following: |
| 361 | 361 | ||
| 362 | - License statements were updated for the new version. For this | 362 | - License statements were updated for the new version. For this |
| @@ -377,22 +377,22 @@ To manually upgrade recipe versions, follow these general steps: | |||
| 377 | issues. If a patch is necessary and failing, you need to rebase it | 377 | issues. If a patch is necessary and failing, you need to rebase it |
| 378 | into the new version. | 378 | into the new version. |
| 379 | 379 | ||
| 380 | 4. *Optionally Attempt to Build for Several Architectures:* Once you | 380 | #. *Optionally Attempt to Build for Several Architectures:* Once you |
| 381 | successfully build the new software for a given architecture, you | 381 | successfully build the new software for a given architecture, you |
| 382 | could test the build for other architectures by changing the | 382 | could test the build for other architectures by changing the |
| 383 | :term:`MACHINE` variable and | 383 | :term:`MACHINE` variable and |
| 384 | rebuilding the software. This optional step is especially important | 384 | rebuilding the software. This optional step is especially important |
| 385 | if the recipe is to be released publicly. | 385 | if the recipe is to be released publicly. |
| 386 | 386 | ||
| 387 | 5. *Check the Upstream Change Log or Release Notes:* Checking both these | 387 | #. *Check the Upstream Change Log or Release Notes:* Checking both these |
| 388 | reveals if there are new features that could break | 388 | reveals if there are new features that could break |
| 389 | backwards-compatibility. If so, you need to take steps to mitigate or | 389 | backwards-compatibility. If so, you need to take steps to mitigate or |
| 390 | eliminate that situation. | 390 | eliminate that situation. |
| 391 | 391 | ||
| 392 | 6. *Optionally Create a Bootable Image and Test:* If you want, you can | 392 | #. *Optionally Create a Bootable Image and Test:* If you want, you can |
| 393 | test the new software by booting it onto actual hardware. | 393 | test the new software by booting it onto actual hardware. |
| 394 | 394 | ||
| 395 | 7. *Create a Commit with the Change in the Layer Repository:* After all | 395 | #. *Create a Commit with the Change in the Layer Repository:* After all |
| 396 | builds work and any testing is successful, you can create commits for | 396 | builds work and any testing is successful, you can create commits for |
| 397 | any changes in the layer holding your upgraded recipe. | 397 | any changes in the layer holding your upgraded recipe. |
| 398 | 398 | ||
diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst index bcbf40acc5..097be9cbde 100644 --- a/documentation/dev-manual/wayland.rst +++ b/documentation/dev-manual/wayland.rst | |||
| @@ -78,13 +78,13 @@ Alternatively, you can run Weston through the command-line interpretor | |||
| 78 | (CLI), which is better suited for development work. To run Weston under | 78 | (CLI), which is better suited for development work. To run Weston under |
| 79 | the CLI, you need to do the following after your image is built: | 79 | the CLI, you need to do the following after your image is built: |
| 80 | 80 | ||
| 81 | 1. Run these commands to export ``XDG_RUNTIME_DIR``:: | 81 | #. Run these commands to export ``XDG_RUNTIME_DIR``:: |
| 82 | 82 | ||
| 83 | mkdir -p /tmp/$USER-weston | 83 | mkdir -p /tmp/$USER-weston |
| 84 | chmod 0700 /tmp/$USER-weston | 84 | chmod 0700 /tmp/$USER-weston |
| 85 | export XDG_RUNTIME_DIR=/tmp/$USER-weston | 85 | export XDG_RUNTIME_DIR=/tmp/$USER-weston |
| 86 | 86 | ||
| 87 | 2. Launch Weston in the shell:: | 87 | #. Launch Weston in the shell:: |
| 88 | 88 | ||
| 89 | weston | 89 | weston |
| 90 | 90 | ||
diff --git a/documentation/dev-manual/wic.rst b/documentation/dev-manual/wic.rst index 7ed887b270..d698cec77c 100644 --- a/documentation/dev-manual/wic.rst +++ b/documentation/dev-manual/wic.rst | |||
| @@ -641,7 +641,7 @@ modify the kernel. | |||
| 641 | The following example examines the contents of the Wic image, deletes | 641 | The following example examines the contents of the Wic image, deletes |
| 642 | the existing kernel, and then inserts a new kernel: | 642 | the existing kernel, and then inserts a new kernel: |
| 643 | 643 | ||
| 644 | 1. *List the Partitions:* Use the ``wic ls`` command to list all the | 644 | #. *List the Partitions:* Use the ``wic ls`` command to list all the |
| 645 | partitions in the Wic image:: | 645 | partitions in the Wic image:: |
| 646 | 646 | ||
| 647 | $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic | 647 | $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic |
| @@ -652,7 +652,7 @@ the existing kernel, and then inserts a new kernel: | |||
| 652 | The previous output shows two partitions in the | 652 | The previous output shows two partitions in the |
| 653 | ``core-image-minimal-qemux86.wic`` image. | 653 | ``core-image-minimal-qemux86.wic`` image. |
| 654 | 654 | ||
| 655 | 2. *Examine a Particular Partition:* Use the ``wic ls`` command again | 655 | #. *Examine a Particular Partition:* Use the ``wic ls`` command again |
| 656 | but in a different form to examine a particular partition. | 656 | but in a different form to examine a particular partition. |
| 657 | 657 | ||
| 658 | .. note:: | 658 | .. note:: |
| @@ -700,12 +700,12 @@ the existing kernel, and then inserts a new kernel: | |||
| 700 | Add mtools_skip_check=1 to your .mtoolsrc file to skip this test | 700 | Add mtools_skip_check=1 to your .mtoolsrc file to skip this test |
| 701 | 701 | ||
| 702 | 702 | ||
| 703 | 3. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the | 703 | #. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the |
| 704 | ``vmlinuz`` file (kernel):: | 704 | ``vmlinuz`` file (kernel):: |
| 705 | 705 | ||
| 706 | $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz | 706 | $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz |
| 707 | 707 | ||
| 708 | 4. *Add In the New Kernel:* Use the ``wic cp`` command to add the | 708 | #. *Add In the New Kernel:* Use the ``wic cp`` command to add the |
| 709 | updated kernel to the Wic image. Depending on how you built your | 709 | updated kernel to the Wic image. Depending on how you built your |
| 710 | kernel, it could be in different places. If you used ``devtool`` and | 710 | kernel, it could be in different places. If you used ``devtool`` and |
| 711 | an SDK to build your kernel, it resides in the ``tmp/work`` directory | 711 | an SDK to build your kernel, it resides in the ``tmp/work`` directory |
