diff options
Diffstat (limited to 'poky/documentation/dev-manual/common-tasks.rst')
| -rw-r--r-- | poky/documentation/dev-manual/common-tasks.rst | 122 |
1 files changed, 97 insertions, 25 deletions
diff --git a/poky/documentation/dev-manual/common-tasks.rst b/poky/documentation/dev-manual/common-tasks.rst index 4a5011ea7..b81f51bf8 100644 --- a/poky/documentation/dev-manual/common-tasks.rst +++ b/poky/documentation/dev-manual/common-tasks.rst @@ -25,7 +25,7 @@ Creating Your Own Layer ----------------------- It is very easy to create your own layers to use with the OpenEmbedded -build system. The Yocto Project ships with tools that speed up creating +build system, as the Yocto Project ships with tools that speed up creating layers. This section describes the steps you perform by hand to create layers so that you can better understand them. For information about the layer-creation tools, see the @@ -422,8 +422,9 @@ Before the OpenEmbedded build system can use your new layer, you need to enable it. To enable your layer, simply add your layer's path to the :term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is found in the :term:`Build Directory`. -The following example shows how to enable a layer named -``meta-mylayer``:: +The following example shows how to enable your new +``meta-mylayer`` layer (note how your new layer exists outside of +the official ``poky`` repository which you would have checked out earlier):: # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly @@ -434,7 +435,7 @@ The following example shows how to enable a layer named /home/user/poky/meta \ /home/user/poky/meta-poky \ /home/user/poky/meta-yocto-bsp \ - /home/user/poky/meta-mylayer \ + /home/user/mystuff/meta-mylayer \ " BitBake parses each ``conf/layer.conf`` file from the top down as @@ -554,6 +555,67 @@ The end result of this ``.bbappend`` file is that on a Raspberry Pi, where used during :ref:`ref-tasks-fetch` and the test for a non-zero file size in :ref:`ref-tasks-install` will return true, and the file will be installed. +Installing Additional Files Using Your Layer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As another example, consider the main ``xserver-xf86-config`` recipe and a +corresponding ``xserver-xf86-config`` append file both from the :term:`Source +Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named +``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at +``meta/recipes-graphics/xorg-xserver``:: + + SUMMARY = "X.Org X server configuration file" + HOMEPAGE = "http://www.x.org" + SECTION = "x11/base" + LICENSE = "MIT-X" + LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + PR = "r33" + + SRC_URI = "file://xorg.conf" + + S = "${WORKDIR}" + + CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf" + + PACKAGE_ARCH = "${MACHINE_ARCH}" + ALLOW_EMPTY:${PN} = "1" + + do_install () { + if test -s ${WORKDIR}/xorg.conf; then + install -d ${D}/${sysconfdir}/X11 + install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/ + fi + } + +Following is the append file, which is named ``xserver-xf86-config_%.bbappend`` +and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The +file is in the layer at ``recipes-graphics/xorg-xserver``:: + + FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" + + SRC_URI:append:rpi = " \ + file://xorg.conf.d/98-pitft.conf \ + file://xorg.conf.d/99-calibration.conf \ + " + do_install:append:rpi () { + PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}" + if [ "${PITFT}" = "1" ]; then + install -d ${D}/${sysconfdir}/X11/xorg.conf.d/ + install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ + install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ + fi + } + + FILES:${PN}:append:rpi = " ${sysconfdir}/X11/xorg.conf.d/*" + +Building off of the previous example, we once again are setting the +:term:`FILESEXTRAPATHS` variable. In this case we are also using +:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in +the list of :term:`OVERRIDES`. The :ref:`ref-tasks-install` task will then perform a +check for an additional :term:`MACHINE_FEATURES` that if set will cause these +additional files to be installed. These additional files are listed in +:term:`FILES` so that they will be packaged. + Prioritizing Your Layer ----------------------- @@ -843,8 +905,8 @@ the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:: IMAGE_INSTALL:append = " strace" -Use of the syntax is important - -specifically, the space between the quote and the package name, which is +Use of the syntax is important; specifically, the leading space +after the opening quote and before the package name, which is ``strace`` in this example. This space is required since the ``:append`` operator does not add the space. @@ -2361,7 +2423,7 @@ into separate packages:: require xorg-lib-common.inc SUMMARY = "Xpm: X Pixmap extension library" - LICENSE = "BSD" + LICENSE = "MIT" LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" DEPENDS += "libxext libsm libxt" PE = "1" @@ -3476,7 +3538,7 @@ Similar to working within a development shell as described in the previous section, you can also spawn and work within an interactive Python development shell. When debugging certain commands or even when just editing packages, ``devpyshell`` can be a useful tool. When you -invoke ``devpyshell``, all tasks up to and including +invoke the ``devpyshell`` task, all tasks up to and including :ref:`ref-tasks-patch` are run for the specified target. Then a new terminal is opened. Additionally, key Python objects and code are available in the same way they are to @@ -3486,7 +3548,7 @@ functions:: pydevshell> d.getVar("STAGING_DIR") '/media/build1/poky/build/tmp/sysroots' - pydevshell> d.getVar("STAGING_DIR") + pydevshell> d.getVar("STAGING_DIR", False) '${TMPDIR}/sysroots' pydevshell> d.setVar("FOO", "bar") pydevshell> d.getVar("FOO") @@ -3517,9 +3579,9 @@ either by using Ctrl+d or closing the terminal window. Building ======== -This section describes various build procedures. For example, the steps -needed for a simple build, a target that uses multiple configurations, -building an image for more than one machine, and so forth. +This section describes various build procedures, such as the steps +needed for a simple build, building a target for multiple configurations, +generating an image for more than one machine, and so forth. Building a Simple Image ----------------------- @@ -3575,8 +3637,10 @@ The following figure and list overviews the build process: .. note:: A common practice is to use a different Build Directory for - different targets. For example, ``~/build/x86`` for a ``qemux86`` - target, and ``~/build/arm`` for a ``qemuarm`` target. + different targets; for example, ``~/build/x86`` for a ``qemux86`` + target, and ``~/build/arm`` for a ``qemuarm`` target. In any + event, it's typically cleaner to locate the build directory + somewhere outside of your source directory. 3. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the ``conf/local.conf`` configuration file, which is found in the Build @@ -3599,7 +3663,7 @@ The following figure and list overviews the build process: The target is the name of the recipe you want to build. Common targets are the images in ``meta/recipes-core/images``, ``meta/recipes-sato/images``, and so forth all found in the - :term:`Source Directory`. Or, the target + :term:`Source Directory`. Alternatively, the target can be the name of a recipe for a specific piece of software such as BusyBox. For more details about the images the OpenEmbedded build system supports, see the @@ -3810,7 +3874,7 @@ Follow these steps to create an initramfs image: .. note:: - It is recommended that you do bundle the initramfs image with the + It is recommended that you bundle the initramfs image with the kernel image to avoid circular dependencies between the kernel recipe and the initramfs recipe should the initramfs image include kernel modules. @@ -3824,6 +3888,12 @@ Follow these steps to create an initramfs image: .. note:: + Bundling the initramfs with the kernel conflates the code in the initramfs + with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 compatible + software may be part of a bundled initramfs. + + .. note:: + If you choose to not bundle the initramfs image with the kernel image, you are essentially using an `Initial RAM Disk (initrd) <https://en.wikipedia.org/wiki/Initrd>`__. @@ -4430,7 +4500,7 @@ directory: SRCREV = "${AUTOREV}" When a recipe sets :term:`SRCREV` to - ``${AUTOREV}``, the build system accesses the network in an + ``${``\ :term:`AUTOREV`\ ``}``, the build system accesses the network in an attempt to determine the latest version of software from the SCM. Typically, recipes that use :term:`AUTOREV` are custom or modified recipes. Recipes that reside in public repositories usually do not @@ -5197,17 +5267,19 @@ command to return the available Wic images as follows:: $ wic list images genericx86 Create an EFI disk image for genericx86* - beaglebone-yocto Create SD card image for Beaglebone edgerouter Create SD card image for Edgerouter - qemux86-directdisk Create a QEMU machine 'pcbios' direct disk image - directdisk-gpt Create a 'pcbios' direct disk image - mkefidisk Create an EFI disk image - directdisk Create a 'pcbios' direct disk image + beaglebone-yocto Create SD card image for Beaglebone + qemux86-directdisk Create a qemu machine 'pcbios' direct disk image systemd-bootdisk Create an EFI disk image with systemd-boot mkhybridiso Create a hybrid ISO image + mkefidisk Create an EFI disk image sdimage-bootpart Create SD card image with a boot partition directdisk-multi-rootfs Create multi rootfs image using rootfs plugin + directdisk Create a 'pcbios' direct disk image directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config + qemuriscv Create qcow2 image for RISC-V QEMU machines + directdisk-gpt Create a 'pcbios' direct disk image + efi-bootdisk Once you know the list of available Wic images, you can use ``help`` with the command to get help on a @@ -7571,7 +7643,7 @@ Selecting a Device Manager The Yocto Project provides multiple ways to manage the device manager (``/dev``): -- Persistent and Pre-Populated\ ``/dev``: For this case, the ``/dev`` +- Persistent and Pre-Populated ``/dev``: For this case, the ``/dev`` directory is persistent and the required device nodes are created during the build. @@ -7581,7 +7653,7 @@ The Yocto Project provides multiple ways to manage the device manager configuration of device nodes is done in user space by a device manager like ``udev`` or ``busybox-mdev``. -Using Persistent and Pre-Populated\ ``/dev`` +Using Persistent and Pre-Populated ``/dev`` -------------------------------------------- To use the static method for device population, you need to set the @@ -10478,7 +10550,7 @@ been followed: and email address. In this example, the email address is a mailing list:: - $ poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org + $ poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@lists.yoctoproject.org You need to follow the prompts as the script is interactive. |