documentation/dev-manual/building.rst

1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
22    -  For information on how to build an image using
24       :doc:`/toaster-manual/index`.
26    -  For information on how to use ``devtool`` to build images, see the
27       ":ref:`sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow`"
31    -  For a quick example on how to build an image using the
33       :doc:`/brief-yoctoprojectqs/index` document.
35    -  You can also use the `Yocto Project BitBake
36       <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__
42 ":ref:`overview-manual/concepts:images`" section in the Yocto Project Overview
47 .. image:: figures/bitbake-build-flow.png
56    :ref:`structure-core-script`)::
58       $ source oe-init-build-env [build_dir]
90    targets are the images in ``meta/recipes-core/images``,
91    ``meta/recipes-sato/images``, and so forth all found in the
96    ":ref:`ref-manual/images:Images`" chapter in the Yocto
100    ``core-image-minimal`` image::
102       $ bitbake core-image-minimal
108    run pre-built images such as ``qemux86`` and ``qemuarm``, see the
109    :doc:`/sdk-manual/index` manual. For
129    ``core-image-minimal-initramfs.bb`` recipe found in the
130    ``meta/recipes-core`` directory of the :term:`Source Directory`
131    as an example from which to work. The ``core-image-minimal-initramfs`` recipe
132    is based on the :ref:`initramfs-framework <dev-manual/building:Customizing an
133    Initramfs using \`\`initramfs-framework\`\`>` recipe described below.
152    necessarily want that are set by the :ref:`ref-classes-image`
153    or :ref:`ref-classes-core-image` classes.
161 Customizing an Initramfs using ``initramfs-framework``
162 ------------------------------------------------------
164 The ``core-image-minimal-initramfs.bb`` recipe found in
165 :oe_git:`meta/recipes-core/images
166 </openembedded-core/tree/meta/recipes-core/images>` uses the
167 :oe_git:`initramfs-framework_1.0.bb
168 </openembedded-core/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb>`
169 recipe as its base component. The goal of the ``initramfs-framework`` recipe is
172 The ``initramfs-framework`` recipe relies on shell initialization scripts
173 defined in :oe_git:`meta/recipes-core/initrdscripts/initramfs-framework
174 </openembedded-core/tree/meta/recipes-core/initrdscripts/initramfs-framework>`. Since some of
175 these scripts do not apply for all use cases, the ``initramfs-framework`` recipe
178 -  ``initramfs-framework-base``: this package installs the basic components of
183 -  ``initramfs-module-exec``: support for execution of applications.
184 -  ``initramfs-module-mdev``: support for `mdev
186 -  ``initramfs-module-udev``: support for :wikipedia:`Udev <Udev>`.
187 -  ``initramfs-module-e2fs``: support for :wikipedia:`ext4/ext3/ext2
189 -  ``initramfs-module-nfsrootfs``: support for locating and mounting the root
191 -  ``initramfs-module-rootfs``: support for locating and mounting the root
193 -  ``initramfs-module-debug``: dynamic debug support.
194 -  ``initramfs-module-lvm``: :wikipedia:`LVM <Logical_volume_management>` rootfs support.
195 -  ``initramfs-module-overlayroot``: support for mounting a read-write overlay
196    on top of a read-only root filesystem.
198 In addition to the packages defined by the ``initramfs-framework`` recipe
200 :oe_git:`meta/recipes-core/initrdscripts </openembedded-core/tree/meta/recipes-core/initrdscripts>`:
202 -  ``initramfs-module-install``: module to create and install a partition layout
204 -  ``initramfs-module-install-efi``: module to create and install an EFI
206 -  ``initramfs-module-setup-live``: module to start a shell in the
207    :term:`Initramfs` if ``root=/dev/ram0`` in passed in the `Kernel command-line
208    <https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html>`__
213 <dev-manual/layers:Appending Other Layers Metadata With Your Layer>` on the
214 ``core-image-minimal-initramfs`` recipe, or create a custom recipe for the
215 :term:`Initramfs` taking ``core-image-minimal-initramfs`` as example.
218 recipes. The recipes are conventionally named ``initramfs-module-<module name>``
220 :term:`RDEPENDS` package-specific variables to include
221 ``initramfs-framework-base`` and the other packages on which the module depends
225 ``/init.d`` and must follow the ``<number>-<script name>`` naming scheme where:
227 -  ``<number>`` is a *two-digit* number that affects the execution order of the
228    script compared to others. For example, the script ``80-setup-live`` would be
229    executed after ``01-udev`` because 80 is greater than 01.
231    This number being two-digits is important here as the scripts are executed
232    alphabetically. For example, the script ``10-script`` would be executed
233    before the script ``8-script``, because ``1`` is inferior to ``8``.
234    Therefore, the script should be named ``08-script``.
236 -  ``<script name>`` is the script name which you can choose freely.
242 -------------------------------------------------------
254 …on ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`"…
258       TMPDIR="${TOPDIR}/tmp-initramfscfg"
266      INITRAMFS_DEPLOY_DIR_IMAGE = "${TOPDIR}/tmp-initramfscfg/deploy/images/${MACHINE}"
274    main configuration but the :ref:`ref-tasks-bundle_initramfs` task will grab the
280    or to build a different :term:`DISTRO` for it such as ``poky-tiny``.
287 requiring less on-die or in-package memory (cheaper), better performance
290 real-world examples where a very small distribution gives you distinct
295 distribution to even smaller sizes than the ``poky-tiny`` distribution,
296 which is around 5 Mbytes, that can be built out-of-the-box using the
300 --------------------
307 -  :ref:`Determine your goals and guiding principles
308    <dev-manual/building:goals and guiding principles>`
310 -  :ref:`dev-manual/building:understand what contributes to your image size`
312 -  :ref:`Reduce the size of the root filesystem
313    <dev-manual/building:trim the root filesystem>`
315 -  :ref:`Reduce the size of the kernel <dev-manual/building:trim the kernel>`
317 -  :ref:`dev-manual/building:remove package management requirements`
319 -  :ref:`dev-manual/building:look for other ways to minimize size`
321 -  :ref:`dev-manual/building:iterate on the process`
324 ----------------------------
330 -  Determine how much space you need (e.g. a kernel that is 1 Mbyte or
333 -  Find the areas that are currently taking 90% of the space and
336 -  Do not create any difficult "hacks" to achieve your goals.
338 -  Leverage the device-specific options.
340 -  Work in a separate layer so that you keep changes isolated. For
342    ":ref:`dev-manual/layers:understanding and creating layers`" section.
345 ----------------------------------------------
348 distribution. You can use the Yocto Project out-of-the-box to create the
349 ``poky-tiny`` distribution. Ultimately, you will want to make changes in
350 your own distribution that are likely modeled after ``poky-tiny``.
354    To use ``poky-tiny`` in your build, set the :term:`DISTRO` variable in your
355    ``local.conf`` file to "poky-tiny" as described in the
356    ":ref:`dev-manual/custom-distribution:creating your own distribution`"
373 -  ``ksize.py``: Reports component sizes for the kernel build objects.
375 -  ``dirsize.py``: Reports component sizes for the root filesystem.
378 view file dependencies in a human-readable form:
380 -  ``merge_config.sh``: Helps you manage configuration files and
389    repositories (i.e. ``linux-yocto-3.14``, ``linux-yocto-3.10``,
390    ``linux-yocto-3.8``, and so forth) in the ``scripts/kconfig``
394    ":ref:`kernel-dev/common:creating configuration fragments`"
397 -  ``bitbake -u taskexp -g bitbake_target``: Using the BitBake command
399    view file dependencies. Understanding these dependencies allows you
404 ------------------------
414    $ cd root-directory-of-image
415    $ dirsize.py 100000 > dirsize-100k.log
416    $ cat dirsize-100k.log
429    $ cd image-directory
430    $ bitbake -u taskexp -g image
445    VIRTUAL-RUNTIME_dev_manager = ""
451 Mbyte journal. If you are okay with running read-only, you do not need
460 ---------------
462 The kernel is built by including policies for hardware-independent
470 Run the ``ksize.py`` script from the top-level Linux build directory to
473    $ cd top-level-linux-build-directory
478 the built-in ``.o`` files for drivers, networking, core kernel files,
484 To examine, or drill down, into any particular area, use the ``-d``
487    $ ksize.py -d > ksize.log
512 --------------------------------------
520 "package-management" is not part of your
527 ------------------------------------
534 -  ``glibc``: In general, follow this process:
551 -  ``busybox``: For BusyBox, use a process similar as described for
559 ----------------------
594 -  *Share the :term:`Build Directory`:* If at all possible, share the
600    and often cross-recipes for multiple machines. Thus, build time decreases.
609 -  *Enable the Appropriate Package Architecture:* By default, the
620    :ref:`ref-classes-allarch` class.
624    If your recipe needs to generate packages that are machine-specific
626    machine-architecture dependent, which makes your recipe also
627    machine-architecture dependent, make sure your recipe enables the
642 -  *Choose a Generic Tuning File if Possible:* Some tunes are more
655 -  *Manage Granular Level Packaging:* Sometimes there are cases where
660    :yocto_git:`meta-freescale </meta-freescale/>`.
662 …:yocto_git:`fsl-dynamic-packagearch </meta-freescale/tree/classes/fsl-dynamic-packagearch.bbclass>`
664    the AMD GPU. The i.MX6-based boards can do the same because all
667    the sub-architecture values. If so, the class sets the
670    provide or depend on one of the sub-architecture values but it
671    matches a value in the machine-specific filter, it sets
676 -  *Use Tools to Debug Issues:* Sometimes you can run into situations
680    situations are usually due to references to machine-specific
685    and so forth in code that is supposed to only be tune-specific or
703    -  ``state-diff-machines.sh``*:* You can find this tool in the
707    -  *BitBake's "-S printdiff" Option:* Using this option causes
732 is inherit the :ref:`ref-classes-externalsrc` class and then set
737    EXTERNALSRC:pn-myrecipe = "path-to-your-source-tree"
748    locally inherit the :ref:`ref-classes-externalsrc` class.
750 By default, :ref:`ref-classes-externalsrc` builds the source code in a
758    EXTERNALSRC_BUILD:pn-myrecipe = "path-to-your-source-tree"
781       DL_DIR = "/home/your-download-dir/"
794       $ bitbake target --runonly=fetch
807 files, you can create your "own-mirror" and build your target.
816    :ref:`ref-classes-own-mirrors` class, and use the
819       SOURCE_MIRROR_URL ?= "file:///home/your-download-dir/"
820       INHERIT += "own-mirrors"
823    The :term:`SOURCE_MIRROR_URL` and :ref:`ref-classes-own-mirrors`
827    from your "own-mirror" are used.
861          history <dev-manual/build-quality:maintaining build output quality>`.
863       #. Use the ``buildhistory-collect-srcrevs`` command to collect the
866          ":ref:`dev-manual/build-quality:build history package information`"