diff options
Diffstat (limited to 'documentation/dev-manual/building.rst')
| -rw-r--r-- | documentation/dev-manual/building.rst | 46 |
1 files changed, 23 insertions, 23 deletions
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 | ||
