diff options
Diffstat (limited to 'documentation/poky-ref-manual/extendpoky.xml')
| -rw-r--r-- | documentation/poky-ref-manual/extendpoky.xml | 1027 |
1 files changed, 0 insertions, 1027 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml deleted file mode 100644 index 5bf22e547a..0000000000 --- a/documentation/poky-ref-manual/extendpoky.xml +++ /dev/null @@ -1,1027 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='extendpoky'> - -<title>Extending Poky</title> - <para> - This chapter provides information about how to extend the functionality - already present in Poky. - The chapter also documents standard tasks such as adding new - software packages, extending or customizing images or porting Poky to - new hardware (adding a new machine). - Finally, the chapter contains advice about how to make changes to Poky to achieve the best results. - </para> - - <section id='usingpoky-extend-addpkg'> - <title>Adding a Package</title> - <para> - To add a package into Poky you need to write a recipe for it. - Writing a recipe means creating a <filename>.bb</filename> file that sets some - variables. - For information on variables that are useful for recipes and for information about recipe naming - issues, see the <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link> - appendix. - </para> - <para> - Before writing a recipe from scratch it is often useful to check - whether someone else has written one already. - OpenEmbedded is a good place to look as it has a wider scope and range of packages. - Because Poky aims to be compatible with OpenEmbedded, most recipes should - simply work in Poky. - </para> - <para> - For new packages, the simplest way to add a recipe is to base it on a similar - pre-existing recipe. - Following are some examples showing how to add standard types of packages: - </para> - - <section id='usingpoky-extend-addpkg-singlec'> - <title>Single .c File Package (Hello World!)</title> - <para> - Building an application from a single file that is stored locally (e.g. under - <filename>files/</filename>) requires a recipe that has the file listed in - the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. - Additionally, you need to manually write the "do_compile" and - "do_install" tasks. - The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the - directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'> - WORKDIR</link></glossterm> in this case - the directory BitBake uses for the build. - </para> - <programlisting> -DESCRIPTION = "Simple helloworld application" -SECTION = "examples" -LICENSE = "MIT" -PR = "r0" - -SRC_URI = "file://helloworld.c" - -S = "${WORKDIR}" - -do_compile() { - ${CC} helloworld.c -o helloworld -} - -do_install() { - install -d ${D}${bindir} - install -m 0755 helloworld ${D}${bindir} -} - </programlisting> - <para> - By default, the "helloworld", "helloworld-dbg" and "helloworld-dev" - packages are built. - For information on how to customize the packaging process, see - <link linkend='usingpoky-extend-addpkg-files'>Controlling Package Content</link>. - </para> - </section> - - <section id='usingpoky-extend-addpkg-autotools'> - <title>Autotooled Package</title> - <para> - Applications that use autotools such as <filename>autoconf</filename> and - <filename>automake</filename> require a recipe that has a source archive listed in - <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and - also inherits autotools, which instructs BitBake to use the - <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps - needed to build an autotooled application. - The result of the build is automatically packaged. - And, if the application uses NLS for localization, packages with local information are - generated (one package per language). - Following is one example: (<filename>hello_2.2.bb</filename>) - </para> - <programlisting> -DESCRIPTION = "GNU Helloworld application" -SECTION = "examples" -LICENSE = "GPLv2+" -LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" -PR = "r0" - -SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" - -inherit autotools gettext - </programlisting> - <para> - The variable <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link> - </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> - track source license changes</link>. - You can quickly create autotool-based recipes in a manner similar to the previous example. - </para> - - </section> - - <section id='usingpoky-extend-addpkg-makefile'> - <title>Makefile-Based Package</title> - <para> - Applications that use GNU <filename>make</filename> also require a recipe that has - the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. - You do not need to add a "do_compile" step since by default BitBake - starts the <filename>make</filename> command to compile the application. - If you need additional <filename>make</filename> options you should store them in the - <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable. - BitBake passes these options into the <filename>make</filename> GNU invocation. - Note that a "do_install" task is still required. - Otherwise BitBake runs an empty "do_install" task by default. - </para> - <para> - Some applications might require extra parameters to be passed to the compiler. - For example the application might need an additional header path. - You can accomplish this by adding to the <glossterm><link linkend='var-CFLAGS'>CFLAGS</link> - </glossterm> variable. - The following example shows this: - </para> - <programlisting> -CFLAGS_prepend = "-I ${S}/include " - </programlisting> - <para> - In the following example <filename>mtd-utils</filename> is a makefile-based package: - </para> - <programlisting> -DESCRIPTION = "Tools for managing memory technology devices." -SECTION = "base" -DEPENDS = "zlib lzo e2fsprogs util-linux" -HOMEPAGE = "http://www.linux-mtd.infradead.org/" -LICENSE = "GPLv2" - -SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}" - -S = "${WORKDIR}/git/" - -EXTRA_OEMAKE = "'CC=${CC}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' \ - 'BUILDDIR=${S}'" - -do_install () { - oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \ - INCLUDEDIR=${includedir} - install -d ${D}${includedir}/mtd/ - for f in ${S}/include/mtd/*.h; do - install -m 0644 $f ${D}${includedir}/mtd/ - done -} - </programlisting> - - </section> - - <section id='usingpoky-extend-addpkg-files'> - <title>Controlling Package Content</title> - <para> - You can use the variables <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> and - <glossterm><link linkend='var-FILES'>FILES</link></glossterm> to split an application into - multiple packages. - </para> - <para> - Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>). - By default, the "libXpm" recipe generates a single package that contains the library along - with a few binaries. - You can modify the recipe to split the binaries into separate packages: - </para> - <programlisting> -require xorg-lib-common.inc - -DESCRIPTION = "X11 Pixmap library" -LICENSE = "X-BSD" -DEPENDS += "libxext libsm libxt" -PR = "r3" -PE = "1" - -XORG_PN = "libXpm" - -PACKAGES =+ "sxpm cxpm" -FILES_cxpm = "${bindir}/cxpm" -FILES_sxpm = "${bindir}/sxpm" - </programlisting> - <para> - In the previous example we want to ship the "sxpm" and "cxpm" binaries - in separate packages. - Since "bindir" would be packaged into the main - <glossterm><link linkend='var-PN'>PN</link></glossterm> - package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link> - </glossterm> variable so additional package names are added to the start of list. - This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_* - variables then containing information that define which files and - directories go into which packages. - Files included by earlier packages are skipped by latter packages. - Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include - the above listed files. - </para> - </section> - - <section id='usingpoky-extend-addpkg-postinstalls'> - <title>Post Install Scripts</title> - - <para> - To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME() - </filename> function to the <filename>.bb</filename> file and use - <filename>PACKAGENAME</filename> as the name of the package you want to attach to the - <filename>postinst</filename> script. - Normally <glossterm><link linkend='var-PN'>PN</link></glossterm> can be used, which - automatically expands to PACKAGENAME. - A post-installation function has the following structure: - </para> - <programlisting> -pkg_postinst_PACKAGENAME () { -#!/bin/sh -e -# Commands to carry out -} - </programlisting> - <para> - The script defined in the post-installation function is called when the rootfs is made. - If the script succeeds, the package is marked as installed. - If the script fails, the package is marked as unpacked and the script is - executed when the image boots again. - </para> - <para> - Sometimes it is necessary for the execution of a post-installation - script to be delayed until the first boot. - For example, the script might need to be executed on the device itself. - To delay script execution until boot time, use the following structure in the - post-installation script: - </para> - <programlisting> -pkg_postinst_PACKAGENAME () { -#!/bin/sh -e -if [ x"$D" = "x" ]; then - # Actions to carry out on the device go here -else - exit 1 -fi -} - </programlisting> - <para> - The previous example delays execution until the image boots again because the - <glossterm><link linkend='var-D'>D</link></glossterm> variable points - to the 'image' directory when the rootfs is being made at build time but - is unset when executed on the first boot. - </para> - </section> - </section> - - <section id='usingpoky-extend-customimage'> - <title>Customizing Images</title> - <para> - You can customize Poky images to satisfy particular requirements. - This section describes several methods and provides guidelines for each. - </para> - - <section id='usingpoky-extend-customimage-custombb'> - <title>Customizing Images Using Custom .bb Files</title> - <para> - One way to get additional software into an image is to create a custom image. - The following example shows the form for the two lines you need: - </para> - <programlisting> -IMAGE_INSTALL = "task-poky-x11-base package1 package2" - -inherit poky-image - </programlisting> - <para> - By creating a custom image, a developer has total control - over the contents of the image. - It is important to use the correct names of packages in the - <glossterm><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable. - You must use the OpenEmbedded notation and not the Debian notation for the names - (e.g. "glibc-dev" instead of "libc6-dev"). - </para> - <para> - The other method for creating a custom image is to modify an existing image. - For example, if a developer wants to add "strace" into "poky-image-sato", they can use - the following recipe: - </para> - <programlisting> -require poky-image-sato.bb - -IMAGE_INSTALL += "strace" - </programlisting> - </section> - - <section id='usingpoky-extend-customimage-customtasks'> - <title>Customizing Images Using Custom Tasks</title> - <para> - For complex custom images, the best approach is to create a custom task package - that is used to build the image or images. - A good example of a tasks package is - <filename>meta/recipes-sato/tasks/task-poky.bb</filename>. - The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> - variable lists the task packages to build along with the complementary - -dbg and -dev packages. - For each package added, you can use - <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> - and <glossterm><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></glossterm> - entries to provide a list of packages the parent task package should contain. - Following is an example: - </para> - <para> - <programlisting> -DESCRIPTION = "My Custom Tasks" - -PACKAGES = "\ - task-custom-apps \ - task-custom-apps-dbg \ - task-custom-apps-dev \ - task-custom-tools \ - task-custom-tools-dbg \ - task-custom-tools-dev \ - " - -RDEPENDS_task-custom-apps = "\ - dropbear \ - portmap \ - psplash" - -RDEPENDS_task-custom-tools = "\ - oprofile \ - oprofileui-server \ - lttng-control \ - lttng-viewer" - -RRECOMMENDS_task-custom-tools = "\ - kernel-module-oprofile" - </programlisting> - </para> - <para> - In the previous example, two task packages are created with their dependencies and their - recommended package dependencies listed: <filename>task-custom-apps</filename>, and - <filename>task-custom-tools</filename>. - To build an image using these task packages, you need to add - "task-custom-apps" and/or "task-custom-tools" to <glossterm><link - linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>. - For other forms of image dependencies see the other areas of this section. - </para> - </section> - - <section id='usingpoky-extend-customimage-imagefeatures'> - <title>Customizing Images Using Custom IMAGE_FEATURES</title> - <para> - Ultimately users might want to add extra image "features" as used by Poky with the - <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> - variable. - To create these features, the best reference is - <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this. - In summary, the file looks at the contents of the - <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> - variable and then maps that into a set of tasks or packages. - Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link> - </glossterm> variable is generated automatically. - Users can add extra features by extending the class or creating a custom class for use - with specialized image <filename>.bb</filename> files. - </para> - <para> - Poky ships with two SSH servers you can use in your images: Dropbear and OpenSSH. - Dropbear is a minimal SSH server appropriate for resource-constrained environments, - while OpenSSH is a well-known standard SSH server implementation. - By default, poky-image-sato is configured to use Dropbear. - The poky-image-basic and poky-image-lsb images both include OpenSSH. - To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable - so that it sets the image you are working with to include ssh-server-dropbear - or ssh-server-openssh. - </para> - </section> - - <section id='usingpoky-extend-customimage-localconf'> - <title>Customizing Images Using local.conf</title> - <para> - It is possible to customize image contents by using variables used by distribution - maintainers in the <filename>local.conf</filename>. - This method only allows the addition of packages and is not recommended. - </para> - <para> - For example, to add the "strace" package into the image you would add this package to the - <filename>local.conf</filename> file: - </para> - <programlisting> -DISTRO_EXTRA_RDEPENDS += "strace" - </programlisting> - <para> - However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> - DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for - distribution maintainers, adding packages using this method is not as simple as adding - them using a custom <filename>.bb</filename> file. - Using the <filename>local.conf</filename> file method could result in some packages - needing to be recreated. - For example, if packages were previously created and the image was rebuilt then the packages - would need to be recreated. - </para> - <para> - Cleaning task-* packages are required because they use the - <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'> - DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. - You do not have to build them by hand because Poky images depend on the packages they contain. - This means dependencies are automatically built when the image builds. - For this reason we don't use the "rebuild" task. - In this case the "rebuild" task does not care about - dependencies - it only rebuilds the specified package. - </para> - <programlisting> -$ bitbake -c clean task-boot task-base task-poky -$ bitbake poky-image-sato - </programlisting> - </section> - - </section> - - <section id="platdev-newmachine"> - <title>Porting Poky to a New Machine</title> - <para> - Adding a new machine to Poky is a straightforward process. - This section provides information that gives you an idea of the changes you must make. - The information covers adding machines similar to those Poky already supports. - Although well within the capabilities of Poky, adding a totally new architecture might require - changes to <filename>gcc/glibc</filename> and to the site information, which is - beyond the scope of this manual. - </para> - - <section id="platdev-newmachine-conffile"> - <title>Adding the Machine Configuration File</title> - <para> - To add a machine configuration you need to add a <filename>.conf</filename> file - with details of the device being added to the <filename>conf/machine/</filename> file. - The name of the file determines the name Poky uses to reference the new machine. - </para> - <para> - The most important variables to set in this file are <glossterm> - <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm> (e.g. "arm"), - <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel - (see below) and <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm> - (e.g. "kernel26 apm screen wifi"). - You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE - </link></glossterm> (e.g. "115200 ttyS0"), <glossterm> - <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link> - </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'> - IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2"). - You can find full details on these variables in the reference section. - You can leverage many existing machine <filename>.conf</filename> files from - <filename>meta/conf/machine/</filename>. - </para> - </section> - - <section id="platdev-newmachine-kernel"> - <title>Adding a Kernel for the Machine</title> - <para> - Poky needs to be able to build a kernel for the machine. - You need to either create a new kernel recipe for this machine, or extend an - existing recipe. - You can find several kernel examples in the <filename>meta/recipes-kernel/linux</filename> - directory that can be used as references. - </para> - <para> - If you are creating a new recipe, the "normal" recipe-writing rules apply for setting - up a <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. - This means specifying any necessary patches and setting <glossterm> - <link linkend='var-S'>S</link></glossterm> to point at the source code. - You need to create a "configure" task that configures the unpacked kernel with a defconfig. - You can do this by using a <filename>make defconfig</filename> command or - more commonly by copying in a suitable <filename>defconfig</filename> file and and then running - <filename>make oldconfig</filename>. - By making use of "inherit kernel" and potentially some of the - <filename>linux-*.inc</filename> files, most other functionality is - centralized and the the defaults of the class normally work well. - </para> - <para> - If you are extending an existing kernel, it is usually a matter of adding a - suitable <filename>defconfig</filename> file. - The file needs to be added into a location similar to <filename>defconfig</filename> files - used for other machines in a given kernel. - A possible way to do this is by listing the file in the - <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> - and adding the machine to the expression in - <glossterm><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></glossterm>: - </para> - <programlisting> -COMPATIBLE_MACHINE = '(qemux86|qemumips)' - </programlisting> - </section> - - <section id="platdev-newmachine-formfactor"> - <title>Adding a Formfactor Configuration File</title> - <para> - A formfactor configuration file provides information about the - target hardware on which Poky is running and information that Poky cannot - obtain from other sources such as the kernel. - Some examples of information contained in a formfactor configuration file include - framebuffer orientation, whether or not the system has a keyboard, - the positioning of the keyboard in relation to the screen, and - the screen resolution. - </para> - <para> - Reasonable defaults are used in most cases, but if customization is - necessary you need to create a <filename>machconfig</filename> file - under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>, - where <filename>MACHINENAME</filename> is the name for which this information - applies. - For information about the settings available and the defaults, see - <filename>meta/recipes-bsp/formfactor/files/config</filename>. - Following is an example for qemuarm: - </para> - <programlisting> -HAVE_TOUCHSCREEN=1 -HAVE_KEYBOARD=1 - -DISPLAY_CAN_ROTATE=0 -DISPLAY_ORIENTATION=0 -#DISPLAY_WIDTH_PIXELS=640 -#DISPLAY_HEIGHT_PIXELS=480 -#DISPLAY_BPP=16 -DISPLAY_DPI=150 -DISPLAY_SUBPIXEL_ORDER=vrgb - </programlisting> - </section> - </section> - - <section id="usingpoky-changes"> - <title>Making and Maintaining Changes</title> - <para> - Because Poky is extremely configurable and flexible, we recognize that people will want - to extend, configure or optimize Poky for their specific uses. - To best keep pace with future Poky changes we recommend you make controlled changes to Poky. - </para> - <para> - Poky supports the idea of <link linkend='usingpoky-changes-layers'>"layers"</link>. - If you use layers properly you can ease future upgrades and allow segregation - between the Poky core and a given developer's changes. - The following section provides more advice on managing changes to Poky. - </para> - - <section id="usingpoky-changes-layers"> - <title>BitBake Layers</title> - <para> - Often, people want to extend Poky either by adding packages - or by overriding files contained within Poky to add their own - functionality. - BitBake has a powerful mechanism called - "layers", which provides a way to handle this extension in a fully - supported and non-invasive fashion. - </para> - <para> - The Poky tree includes several additional layers such as meta-emenlow and meta-extras - that demonstrate this functionality. - The meta-emenlow layer is an example layer that, by default, is enabled. - However, the meta-extras repository is not enabled by default. - It is easy though to enable any layer. - You simply add the layer's path to the - <glossterm><link linkend='var-BBLAYERS'>BBLAYERS</link></glossterm> variable in your - <filename>bblayers.conf</filename> file. - The following example shows how to enable meta-extras in the Poky build: - </para> - <para> - <programlisting> -LCONF_VERSION = "1" - -BBFILES ?= "" -BBLAYERS = " \ - /path/to/poky/meta \ - /path/to/poky/meta-emenlow \ - /path/to/poky/meta-extras \ - " - </programlisting> - </para> - - <para> - BitBake parses each <filename>conf/layer.conf</filename> file for each layer in BBLAYERS - and adds the recipes, classes and configuration contained within the layer to Poky. - To create your own layer, independent of the main Poky repository, - simply create a directory with a <filename>conf/layer.conf</filename> file and - add the directory to your <filename>bblayers.conf</filename> file. - </para> - <para> - The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax: - <programlisting> -# We have a conf and classes directory, add to BBPATH -BBPATH := "${BBPATH}:${LAYERDIR}" - -# We have a recipes directory containing both .bb and .bbappend files, add to BBFILES -BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ - ${LAYERDIR}/recipes/*/*.bbappend" - -BBFILE_COLLECTIONS += "emenlow" -BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" -BBFILE_PRIORITY_emenlow = "6" - </programlisting> - </para> - <para> - In the previous example, the recipes for the layers are added to - <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm>. - The <glossterm><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></glossterm> - variable is then appended with the layer name. - The <glossterm><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></glossterm> variable - immediately expands with a regular expression used to match files from BBFILES into - a particular layer, in this case by using the base pathname. - The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable - then assigns different priorities to the files in different layers. - Applying priorities is useful in situations where the same package might appear in multiple - layers and allows you to choose what layer should take precedence. - </para> - <para> - Note the use of the <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm> - variable with the immediate expansion operator. - The LAYERDIR variable expands to the directory of the current layer and - requires the immediate expansion operator so that BitBake does not wait to expand the variable - when it's parsing a different directory. - </para> - <para> - BitBake can locate where other bbclass and configuration files are applied through - the <glossterm><link linkend='var-BBPATH'>BBPATH</link></glossterm> - environment variable. - For these cases, BitBake uses the first file with the matching name found in BBPATH. - This is similar to the way the PATH variable is used for binaries. - We recommend, therefore, that you use unique bbclass and configuration file names in your - custom layer. - </para> - <para> - We also recommend the following: - <itemizedlist> - <listitem><para>Store custom layers in a git repository that uses the - meta-prvt-XXXX format.</para></listitem> - <listitem><para>Clone the repository alongside other meta directories in the Poky - tree.</para></listitem> - </itemizedlist> - Following these recommendations keeps your Poky tree and its configuration entirely - inside POKYBASE. - </para> - </section> - - <section id="usingpoky-changes-commits"> - <title>Committing Changes</title> - <para> - Modifications to Poky are often managed under some kind of source - revision control system. - Because some simple practices can significantly improve usability, policy for committing changes - is important. - It helps to use a consistent documentation style when committing changes. - We have found the following style works well. - </para> - <para> - Following are suggestions for committing changes to the Poky core: - </para> - - <para> - <itemizedlist> - <listitem><para>The first line of the commit summarizes the change and begins with the - name of the affected package or packages. - However, not all changes apply to specific packages. - Consequently, the prefix could also be a machine name or class name for - example.</para></listitem> - <listitem><para>The second part of the commit (if needed) is a longer more detailed - description of the changes. Placing a blank line between the first and second parts - helps with readability.</para></listitem> - </itemizedlist> - </para> - <para> - Following is an example commit: - </para> - <literallayout class='monospaced'> - bitbake/data.py: Add emit_func() and generate_dependencies() functions - - These functions allow generation of dependency data between functions and - variables allowing moves to be made towards generating checksums and allowing - use of the dependency information in other parts of bitbake. - - Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org - </literallayout> - - <para> - All commits should be self-contained such that they leave the - metadata in a consistent state that builds both before and after the - commit is made. - Besides being a good policy to follow, this helps ensure the autobuilder test results - are valid. - </para> - </section> - - <section id="usingpoky-changes-prbump"> - <title>Package Revision Incrementing</title> - <para> - If a committed change results in changing the package output - then the value of the <glossterm><link linkend='var-PR'>PR</link> - </glossterm> variable needs to be increased (or 'bumped') as part of that commit. - This means that for new recipes you must be sure to add the PR variable and set its initial value - equal to "r0". - Failing to define PR makes it easy to miss when you bump a package. - Note that you can only use integer values following the "r" in the PR variable. - </para> - <para> - If you are sharing a common .inc file with multiple recipes, you can also use the - <glossterm><link linkend='var-INC_PR'>INC_PR</link></glossterm> variable to ensure that - the recipes sharing the .inc file are rebuilt when the .inc file itself is changed. The - .inc file must set INC_PR (initially to "r0"), and all recipes referring to it should set PR to - "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. If the - .inc file is changed then its INC_PR should be incremented. - </para> - <para> - When upgrading the version of a package, assuming the <glossterm><link - linkend='var-PV'>PV</link></glossterm> changes, the PR variable should be reset to "r0" - (or "$(INC_PR).0" if you are using INC_PR). - </para> - <para> - Usually, version increases occur only to packages. - However, if for some reason PV changes but does not increase, you can increase the - <glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch). - The PE variable defaults to "0". - </para> - <para> - Version numbering strives to follow the - <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> - Debian Version Field Policy Guidelines</ulink>. - These guidelines define how versions are compared and what "increasing" a version means. - </para> - <para> - There are two reasons for following these guidelines. - First, to ensure that when a developer updates and rebuilds, they get all the changes to - the repository and don't have to remember to rebuild any sections. - Second, to ensure that target users are able to upgrade their - devices using package manager commands such as <filename>opkg upgrade</filename> - (or similar commands for dpkg/apt or rpm-based systems). - </para> - <para> - The goal is to ensure Poky has upgradeable packages in all cases. - </para> - </section> - - <section id="usingpoky-changes-collaborate"> - <title>Using Poky in a Team Environment</title> - <para> - It might not be immediately clear how you can use Poky in a team environment, - or scale it for a large team of developers. - The specifics of any situation determine the best solution. - Granted that Poky offers immense flexibility regarding this, practices do exist - that experience has shown work well. - </para> - <para> - The core component of any development effort with Poky is often an - automated build testing framework and an image generation process. - You can use these core components to check that the metadata can be built, - highlight when commits break the build, and provide up-to-date images that - allow people to test the end result and use it as a base platform for further - development. - Experience shows that buildbot is a good fit for this role. - What works well is to configure buildbot to make two types of builds: - incremental and full (from scratch). - See <ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink> - for an example implementation that uses buildbot. - </para> - <para> - You can tie incremental builds to a commit hook that triggers the build - each time a commit is made to the metadata. - This practice results in useful acid tests that determine whether a given commit - breaks the build in some serious way. - Associating a build to a commit can catch a lot of simple errors. - Furthermore, the tests are fast so developers can get quick feedback on changes. - </para> - <para> - Full builds build and test everything from the ground up. - They usually happen at predetermined times like during the night when the machine - load is low. - </para> - <para> - Most teams have many pieces of software undergoing active development at any given time. - You can derive large benefits by putting these pieces under the control of a source - control system that is compatible with Poky (i.e. git or svn). - You can then set the autobuilder to pull the latest revisions of the packages - and test the latest commits by the builds. - This practice quickly highlights issues. - Poky easily supports testing configurations that use both a stable known good revision - and a floating revision. - Poky can also take just the changes from specific source control branches. - This capability allows you to track and test specific changes. - </para> - <para> - Perhaps the hardest part of setting this up is defining the software project or - Poky metadata policies that surround the different source control systems. - Of course circumstances will be different in each case. - However, this situation reveals one of Poky's advantages - the system itself does not - force any particular policy on users, unlike a lot of build systems. - The system allows the best policies to be chosen for the given circumstances. - </para> - </section> - - <section id="usingpoky-changes-updatingimages"> - <title>Updating Existing Images</title> - <para> - Often, rather than re-flashing a new image you might wish to install updated - packages into an existing running system. - You can do this by first sharing the - <filename class="directory">tmp/deploy/ipk/</filename> directory - through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename> - to point at the shared server. - Following is an example: - </para> - <literallayout class='monospaced'> - src/gz all http://www.mysite.com/somedir/deploy/ipk/all - src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a - src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard - </literallayout> - </section> - </section> - - <section id="usingpoky-modifing-packages"> - <title>Modifying Package Source Code</title> - <para> - Although Poky is usually used to build software, you can use it to modify software. - </para> - <para> - During a build, source is available in the - <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory. - The actual location depends on the type of package and the architecture of the target device. - For a standard recipe not related to - <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> the location is - <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>. - For target device-dependent packages you should use the <filename>MACHINE</filename> - variable instead of - <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></glossterm> - in the directory name. - </para> - <tip> - <para> - Be sure the package recipe sets the - <glossterm><link linkend='var-S'>S</link></glossterm> variable to something - other than the standard <filename>WORKDIR/PN-PV/</filename> value. - </para> - </tip> - <para> - After building a package, you can modify the package source code without problems. - The easiest way to test your changes is by calling the "compile" task as shown in the - following example: - </para> - - <literallayout class='monospaced'> - $ bitbake -c compile -f NAME_OF_PACKAGE - </literallayout> - - <para> - The "-f" or "--force" option forces re-execution of the specified task. - You can call other tasks this way as well. - But note that all the modifications in - <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> - are gone once you execute "-c clean" for a package. - </para> - - <section id="usingpoky-modifying-packages-quilt"> - <title>Modifying Package Source Code with quilt</title> - <para> - By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink> - to manage patches in the "do_patch" task. - This is a powerful tool that you can use to track all modifications to package sources. - </para> - <para> - Before modifying source code, it is important to notify quilt so it can track the changes - into the new patch file: - - <literallayout class='monospaced'> - quilt new NAME-OF-PATCH.patch - </literallayout> - - After notifying quilt, add all modified files into that patch: - <literallayout class='monospaced'> - quilt add file1 file2 file3 - </literallayout> - - You can now start editing. - Once you are done editing, you need to use quilt to generate the final patch that - will contain all your modifications. - <literallayout class='monospaced'> - quilt refresh - </literallayout> - - You can find the resulting patch file in the - <filename>patches/</filename> subdirectory of the source - (<glossterm><link linkend='var-S'>S</link></glossterm>) directory. - For future builds you should copy the patch into Poky metadata and add it into the - <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe. - Here is an example: - <programlisting> -SRC_URI += "file://NAME-OF-PATCH.patch" - </programlisting> - Finally, don't forget to 'bump' the - <glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe since - the resulting packages have changed. - </para> - </section> - - </section> - - <section id="usingpoky-configuring-LIC_FILES_CHKSUM"> - <title>Track License Change</title> - <para> - The license of an upstream project might change in the future. - Poky uses the <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable - to track license changes. - </para> - - <section id="usingpoky-specifying-LIC_FILES_CHKSUM"> - <title>Specifying the LIC_FILES_CHKSUM Variable</title> - <para> - The <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> - variable contains checksums of the license text in the recipe source code. - Poky uses this to track changes in the license text of the source code files. - Following is an example of LIC_FILES_CHKSUM: - </para> - <programlisting> -LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \ - file://licfile1.txt; beginline=5; endline=29;md5=yyyy \ - file://licfile2.txt; endline=50;md5=zzzz \ - ..." - </programlisting> - <para> - Poky uses the <glossterm><link linkend='var-S'>S</link></glossterm> variable as the - default directory used when searching files listed in LIC_FILES_CHKSUM. - The previous example employs the default directory. - </para> - <para> - You can also use relative paths as shown in the following example: - </para> - <programlisting> -LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ - md5=bb14ed3c4cda583abc85401304b5cd4e" -LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" - </programlisting> - <para> - In this example the first line locates a file in - <glossterm><link linkend='var-S'>S</link></glossterm><filename>/src/ls.c</filename>. - The second line refers to a file in - <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent - of <glossterm><link linkend='var-S'>S</link></glossterm>. - </para> - </section> - - <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"> - <title>Explanation of Syntax</title> - <para> - As mentioned in the previous section the LIC_FILES_CHKSUM variable lists all the - important files that contain the license text for the source code. - Using this variable you can specify the line on which the license text starts and ends - by supplying "beginline" and "endline" parameters. - If you do not use the "beginline" parameter then it is assumed that the text begins on the - first line of the file. - Similarly, if you do not use the "endline" parameter it is assumed that the license text - ends as the last line of the file. - </para> - <para> - The "md5" parameter stores the md5 checksum of the license text. - If the license text changes in any way as compared to this parameter - then a mis-match occurs. - This mismatch triggers a build failure and notifies the developer. - Notification allows the developer to review and address the license text changes. - Also note that if a mis-match occurs during the build, the correct md5 - checksum is placed in the build log and can be easily copied to a .bb file. - </para> - <para> - There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable. - Generally, however, every project requires a few specifications for license tracking. - Many projects have a "COPYING" file that stores the license information for all the source - code files. - This practice allow you to just track the "COPYING" file as long as it is kept up to date. - </para> - <tip> - If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match - error and displays the correct "md5" parameter value during the build. The correct parameter - is also captured in the build log. - </tip> - <tip> - If the whole file contains only license text, you do not need to use the "beginline" and - "endline" parameters. - </tip> - </section> - </section> - - <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> - <title>Handling Package Name Alias</title> - <para> - Sometimes a package name you are using might exist under an alias or as a similarly named - package in a different distribution. - Poky implements a "distro_check" task that automatically connects to major distributions - and checks for these situations. - If the package exists under a different name in a different distribution you get a - distro_check mismatch. - You can resolve this problem by defining a per-distro recipe name alias using the - <glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm> variable. - </para> - - <section id="usingpoky-specifying-DISTRO_PN_ALIAS"> - <title>Specifying the DISTRO_PN_ALIAS Variable</title> - <para> - Following is an example that shows how you specify the DISTRO_PN_ALIAS variable: - <programlisting> -DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ - distro2=package_name_alias2 \ - distro3=package_name_alias3 \ - ..." - </programlisting> - </para> - <para> - If you have more than one distribution alias, separate them with a space. - Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu, - and Mandriva distributions for source package recipes without having to specify them - using the DISTRO_PN_ALIAS variable. - For example, the following command generates a report that lists the Linux distributions - that include the sources for each of the Poky recipes. - <literallayout class='monospaced'> - $ bitbake world -f -c distro_check - </literallayout> - The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> - file. - </para> - </section> - </section> -</chapter> - -<!-- -vim: expandtab tw=80 ts=4 ---> |