Lines Matching +full:build +full:- +full:without +full:- +full:default +full:- +full:features
1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
6 This section describes various build procedures, such as the steps
7 needed for a simple build, building a target for multiple configurations,
13 In the development environment, you need to build an image whenever you
16 you to build an image within the Yocto Project. This section presents
17 the basic steps you need to build a simple image using BitBake from a
18 build host running Linux.
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
32 OpenEmbedded build system, see 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>`__
37 extension for Visual Studio Code to build images.
39 The build process creates an entire Linux distribution from source and
40 places it in your :term:`Build Directory` under ``tmp/deploy/images``. For
41 detailed information on the build process using BitBake, see the
42 ":ref:`overview-manual/concepts:images`" section in the Yocto Project Overview
45 The following figure and list overviews the build process:
47 .. image:: figures/bitbake-build-flow.png
52 build host ready to use the Yocto Project.
54 #. *Initialize the Build Environment:* Initialize the build environment
55 by sourcing the build environment script (i.e.
56 :ref:`structure-core-script`)::
58 $ source oe-init-build-env [build_dir]
60 When you use the initialization script, the OpenEmbedded build system
61 uses ``build`` as the default :term:`Build Directory` in your current work
63 specify a different :term:`Build Directory`.
67 A common practice is to use a different :term:`Build Directory` for
68 different targets; for example, ``~/build/x86`` for a ``qemux86``
69 target, and ``~/build/arm`` for a ``qemuarm`` target. In any
70 event, it's typically cleaner to locate the :term:`Build Directory`
75 :term:`Build Directory`, is set up how you want it. This file defines many
76 aspects of the build environment including the target machine architecture
78 the build (:term:`PACKAGE_CLASSES`), and a centralized tarball download
81 #. *Build the Image:* Build the image using the ``bitbake`` command::
89 The target is the name of the recipe you want to build. Common
90 targets are the images in ``meta/recipes-core/images``,
91 ``meta/recipes-sato/images``, and so forth all found in the
94 BusyBox. For more details about the images the OpenEmbedded build
96 ":ref:`ref-manual/images:Images`" chapter in the Yocto
100 ``core-image-minimal`` image::
102 $ bitbake core-image-minimal
106 kernels built by the OpenEmbedded build system are placed in the
107 :term:`Build Directory` in ``tmp/deploy/images``. For information on how to
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.
155 #. *Build the Kernel Image and the Initramfs Image:* Build your kernel
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
170 to provide the building blocks to build a customized :term:`Initramfs`.
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 -------------------------------------------------------
244 There may be a case where we want to build an :term:`Initramfs` image which does not
248 above the :term:`Initramfs` image will inherit ``TCLIBC="glibc"`` without allowing us
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}"
273 Building a system with such configuration will build the kernel using the
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
386 machines without having to duplicate your process.
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
404 ------------------------
408 happens, which changes the way you build them. You can also modify the
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
464 building? Which drivers do you build by default?
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
494 features you can let go. For example, if you are not going to need
498 to reflect those changes during the next build. You could run
506 configuration change and build cycle.
512 --------------------------------------
520 "package-management" is not part of your
527 ------------------------------------
534 - ``glibc``: In general, follow this process:
536 #. Remove ``glibc`` features from
540 #. Build your distribution.
542 #. If the build fails due to missing symbols in a package, determine
543 if you can reconfigure the package to not need those features. For
546 characters is needed, determine what ``glibc`` features provide
551 - ``busybox``: For BusyBox, use a process similar as described for
555 Busybox because BusyBox handles its own core features and then allows
559 ----------------------
564 can eliminate without limiting your device beyond what you need.
577 each build specifically for the targeted hardware (i.e. "maxing out" the
578 tunings). Doing so can considerably add to build times and package feed
585 specifically for each machine's build). Rather than "max out" each
586 build's tunings, you can take steps that cause the OpenEmbedded build
590 If build speed and package feed maintenance are considerations, you
592 your tunings to best consider build times and package feed maintenance.
594 - *Share the :term:`Build Directory`:* If at all possible, share the
599 machine builds, the OpenEmbedded build system can reuse the existing native
600 and often cross-recipes for multiple machines. Thus, build time decreases.
609 - *Enable the Appropriate Package Architecture:* By default, the
610 OpenEmbedded build system enables three levels of package
615 directly impact the build time.
618 because there are no binaries to build. To specifically enable "all"
620 :ref:`ref-classes-allarch` class.
624 If your recipe needs to generate packages that are machine-specific
625 or when one of the build or runtime dependencies is already
626 machine-architecture dependent, which makes your recipe also
627 machine-architecture dependent, make sure your recipe enables the
637 OpenEmbedded build system defaults to the
642 - *Choose a Generic Tuning File if Possible:* Some tunes are more
650 OpenEmbedded build system reuses software previously built, thus
651 speeding up the overall build time. Realize that even though a new
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
673 behavior reduces the number of packages built and saves build time by
676 - *Use Tools to Debug Issues:* Sometimes you can run into situations
678 example, the OpenEmbedded build system might not be using shared
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
715 By default, the OpenEmbedded build system uses the :term:`Build Directory`
716 when building source code. The build process involves fetching the source
717 files, unpacking them, and then patching them if necessary before the build
720 There are situations where you might want to build software from source
721 files that are external to and thus outside of the OpenEmbedded build
724 build system to the development team so that they can focus on their
731 To build from software that comes from an external source, all you need to do
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"
760 Replicating a Build Offline
764 build and then use that "snapshot" later to replicate the build offline.
768 build.
781 DL_DIR = "/home/your-download-dir/"
791 #. *Populate Your Downloads Directory Without Building:* Use BitBake to
792 fetch your sources but inhibit the build::
794 $ bitbake target --runonly=fetch
798 be used for the build.
807 files, you can create your "own-mirror" and build your target.
808 Understand that you can use the files to build the target offline from
811 Follow these steps to build your target using the files in the downloads
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.
829 #. *Start With a Clean Build:* You can start with a clean build by
831 :term:`Build Directory`.
833 #. *Build Your Target:* Use BitBake to build your target::
837 The build completes using the known local "snapshot" of source
843 The offline build does not work if recipes attempt to find the
851 ``${``\ :term:`AUTOREV`\ ``}``, the build system accesses the network in an
858 still use the recipes in an offline build. Do the following:
860 #. Use a configuration generated by enabling :ref:`build
861 history <dev-manual/build-quality:maintaining build output quality>`.
863 #. Use the ``buildhistory-collect-srcrevs`` command to collect the
864 stored :term:`SRCREV` values from the build's history. For more
866 ":ref:`dev-manual/build-quality:build history package information`"