From f819f3d7b168e620844b150eded3d8ca80ec4ba2 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 15 Aug 2014 21:14:51 +0300 Subject: dev-manual: General edits to "Common Tasks" chapter. * Found and fixed several areas with issues. * Scrubbed for user-supplied input to make it use the tags. (From yocto-docs rev: 0e1c7ad31921ee7d4ee0d7d4ece01303a25a5d60) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 334 +++++++++++---------- 1 file changed, 182 insertions(+), 152 deletions(-) (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 604c484f30..5611d56838 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -421,7 +421,7 @@ Store custom layers in a Git repository that uses the - meta-<layer_name> format. + meta-layer_name format. Clone the repository alongside other meta directories in the @@ -678,7 +678,7 @@ Use the following form when running the layer management tool. - $ bitbake-layers <command> [arguments] + $ bitbake-layers command [arguments] The following list describes the available commands: @@ -782,7 +782,7 @@ The default mode of the script's operation is to prompt you for information needed to generate the layer: - The layer priority + The layer priority. Whether or not to create a sample recipe. @@ -823,7 +823,7 @@ This directory contains the layer's configuration file. The root name for the file is the same as the root name your provided for the layer (e.g. - <layer>.conf). + layer.conf). The COPYING.MIT file: @@ -839,7 +839,7 @@ If you choose to generate a sample recipe file, the script prompts you for the name for the recipe and then creates it - in <layer>/recipes-example/example/. + in layer/recipes-example/example/. The script creates a .bb file and a directory, which contains a sample helloworld.c source file, along with @@ -851,7 +851,7 @@ If you choose to generate a sample append file, the script prompts you for the name for the file and then creates it - in <layer>/recipes-example-bbappend/example-bbappend/. + in layer/recipes-example-bbappend/example-bbappend/. The script creates a .bbappend file and a directory, which contains a sample patch file. If you do not provide a recipe name, the script uses @@ -1228,7 +1228,7 @@ S = "${WORKDIR}/${PN}-${PV}" - inherit <stuff> + inherit stuff Modifying this recipe is the recommended method for creating a new recipe. @@ -1274,7 +1274,7 @@ When you name your recipe, you need to follow this naming convention: - <basename>_<version>.bb + basename_version.bb Use lower-cased characters and do not include the reserved suffixes -native, @@ -1394,13 +1394,13 @@ Using Variables: ${...} - - Use the ${<varname>} syntax to + Use the ${varname} syntax to access the contents of a variable: SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" - Quote All Assignments: "<value>" - + Quote All Assignments: "value" - Use double quotes around the value in all variable assignments. @@ -1541,12 +1541,12 @@ Realize that some layers have a policy to use spaces for all indentation. - Using Python for Complex Operations: ${@<python_code>} - + Using Python for Complex Operations: ${@python_code} - For more advanced processing, it is possible to use Python code during variable assignments (e.g. search and replacement on a variable). You indicate Python code using the - ${@<python_code>} + ${@python_code} syntax for the variable assignment: SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz @@ -1589,10 +1589,10 @@ Build Directory, use BitBake to process your recipe. All you need to provide is the - <basename> of the recipe as described + basename of the recipe as described in the previous section: - $ bitbake <basename> + $ bitbake basename @@ -1632,7 +1632,7 @@ You can find log files for each task in the recipe's temp directory (e.g. poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp). - Log files are named log.<taskname> + Log files are named log.taskname (e.g. log.do_configure, log.do_fetch, and log.do_compile). @@ -1993,6 +1993,12 @@ incorrect md5 strings, attempt to build the software, and then note the resulting error messages that will report the correct md5 strings. + See the + "Fetching Code" + section for additional information. + + + Here is an example that assumes the software has a COPYING file: @@ -2087,7 +2093,7 @@ configure.ac file, then your software is built using Autotools. If this is the case, you just need to worry about - tweaking the configuration. + modifying the configuration. When using Autotools, your recipe needs to inherit the autotools @@ -2104,7 +2110,7 @@ CMakeLists.txt file, then your software is built using CMake. If this is the case, you just need to worry about - tweaking the configuration. + modifying the configuration. When you use CMake, your recipe needs to inherit the cmake @@ -2152,8 +2158,8 @@ that it did not find something that it needed for some desired optional functionality, then you would need to add those to DEPENDS. - Looking at the log might also reveal items being checked for - and/or enabled that you do not want, or items not being found + Looking at the log might also reveal items being checked for, + enabled, or both that you do not want, or items not being found that are in DEPENDS, in which case you would need to look at passing extra options to the configure script as needed. @@ -2197,7 +2203,12 @@ to an empty string: PARALLEL_MAKE = "" - + + + For information on parallel Makefile issues, see the + "Debugging Parallel Make Rases" + section. + Improper host path usage: This failure applies to recipes building for the target or nativesdk only. @@ -2287,7 +2298,7 @@ make install, you should do this using a do_install_append function using the install command as described in - Manual later in this list. + the "Manual" bulleted item later in this list. Other (using make install): @@ -2336,39 +2347,47 @@ files have been installed correctly. - - During the installation process, you might need to modify - some of the installed files to suit the target layout. - For example, you might need to replace hard-coded paths in an - initscript with values of variables provided by the build - system, such as replacing /usr/bin/ with - ${bindir}. - If you do perform such modifications during - do_install, be sure to modify the - destination file after copying rather than before copying. - Modifying after copying ensures that the build system can - re-execute do_install if needed. - - - - oe_runmake install, which can be run - directly or can be run indirectly by the - autotools - and - cmake - classes, runs make install in parallel. - Sometimes, a Makefile can have missing dependencies between - targets that can result in race conditions. - If you experience intermittent failures during - do_install, you might be able to work - around them by disabling parallel Makefile installs - by adding the following to the recipe: - + Notes + + + During the installation process, you might need to + modify some of the installed files to suit the target + layout. + For example, you might need to replace hard-coded paths + in an initscript with values of variables provided by + the build system, such as replacing + /usr/bin/ with + ${bindir}. + If you do perform such modifications during + do_install, be sure to modify the + destination file after copying rather than before + copying. + Modifying after copying ensures that the build system + can re-execute do_install if + needed. + + + oe_runmake install, which can be + run directly or can be run indirectly by the + autotools + and + cmake + classes, runs make install in + parallel. + Sometimes, a Makefile can have missing dependencies + between targets that can result in race conditions. + If you experience intermittent failures during + do_install, you might be able to + work around them by disabling parallel Makefile + installs by adding the following to the recipe: + PARALLEL_MAKEINST = "" - - See - PARALLEL_MAKEINST - for additional information. + + See + PARALLEL_MAKEINST + for additional information. + + @@ -2464,7 +2483,9 @@ that files are split up and packaged correctly. Running QA Checks: - The insane class adds a step to + The + insane + class adds a step to the package generation process so that output quality assurance checks are generated by the OpenEmbedded build system. @@ -2537,7 +2558,7 @@ Ensuring that the package architecture is correct is not critical while you are doing the first few builds of your recipe. - However, it is important in order to + However, it is important in order to ensure that your recipe rebuilds (or does not rebuild) appropriately in response to changes in configuration, and to ensure that you get the @@ -2575,7 +2596,7 @@ recommended convention is to set PV within the recipe to - "<previous version>+<current version>". + "previous_version+current_version". You can use an additional variable so that you can use the current version elsewhere. Here is an example: @@ -2591,7 +2612,7 @@ Post-installation scripts run immediately after installing - a package on the target, or during image creation when a + a package on the target or during image creation when a package is included in an image. To add a post-installation script to a package, add a pkg_postinst_PACKAGENAME() function to @@ -2703,7 +2724,7 @@ Building an application from a single file that is stored - locally (e.g. under files/) requires + locally (e.g. under files) requires a recipe that has the file listed in the SRC_URI variable. @@ -2794,7 +2815,7 @@ If you need additional make options, you should store them in the EXTRA_OEMAKE variable. - BitBake passes these options into the make GNU invocation. + BitBake passes these options into the GNU make invocation. Note that a do_install task is still required. Otherwise, BitBake runs an empty do_install task by default. @@ -3045,7 +3066,7 @@ TARGET_ARCH (e.g. "arm") PREFERRED_PROVIDER_virtual/kernel - (see below) + MACHINE_FEATURES (e.g. "apm screen wifi") @@ -3515,7 +3536,7 @@ The wic command and the infrastructure it is based on is by definition incomplete. Its purpose is to allow the generation of customized images, - and as such was designed to be completely extensible via a + and as such was designed to be completely extensible through a plugin interface. See the "Plugins" @@ -3638,7 +3659,7 @@ create and list. You can get help for these commands as follows: - $ wic help <command> + $ wic help command @@ -3652,7 +3673,7 @@ a given topic by prefacing the topic with wic help: - $ wic help <help topic> + $ wic help help_topic @@ -3661,9 +3682,9 @@ wic creates using the existing kickstart files with the following form of the command: - $ wic list <image> help + $ wic list image help - where <image> is either + where image is either directdisk or mkefidisk. @@ -3881,8 +3902,8 @@ - The output specifies exactly which image was - created as well as where it was created. + The output specifies the exact created as well as where + it was created. The output also names the artifacts used and the exact .wks script that was used to generate the image. @@ -4139,7 +4160,7 @@ To be more concrete, here is the plugin definition that matches a - '‐‐source bootimg-pcbios' usage, + ‐‐source bootimg-pcbios usage, along with an example method called by the wic implementation when it needs to invoke an implementation-specific @@ -4223,7 +4244,7 @@ The code that then needs to call the plugin methods uses plugin.get_source_plugin_methods() to find the method or methods needed by the call. - Retrieval of those methods is accomplished is accomplished + Retrieval of those methods is accomplished by filling up a dict with keys containing the method names of interest. On success, these will be filled in with the actual @@ -4273,13 +4294,14 @@ This command creates a partition on the system and uses the following syntax: - part <mntpoint> + part mntpoint - The <mntpoint> is where the + The mntpoint + is where the partition will be mounted and must be of one of the following forms: - /<path>: + /path: For example, /, /usr, and /home @@ -4327,7 +4349,7 @@ follows for more information. If you use - ‐‐source <plugin-name>, + ‐‐source plugin-name, wic creates a partition as large as needed and fills it with the contents of the partition that is generated by the @@ -4426,7 +4448,7 @@ You can use the menuconfig tool and configuration fragments to make sure your .config file is just how you need it. This section describes how to use menuconfig, create and use - configuration fragments, and how to interactively tweak your .config + configuration fragments, and how to interactively modify your .config file to create the leanest kernel configuration file possible. @@ -5230,8 +5252,8 @@ Gateways via their Web Interfaces" To set up passwords, use the - extrausers class, which is the - preferred method. + extrausers + class, which is the preferred method. For an example on how to set up both root and user passwords, see the "extrausers.bbclass" @@ -5252,7 +5274,7 @@ Gateways via their Web Interfaces" Consider enabling a Mandatory Access Control (MAC) - framework (such as SMACK or SELinux) and tuning it + framework such as SMACK or SELinux and tuning it appropriately for your device's usage. @@ -5682,7 +5704,7 @@ Gateways via their Web Interfaces" section of the Yocto Project Linux Kernel Development Manual and the "Creating Configuration Fragments" section, which is in this manual. - bitbake -u depexp -g <bitbake_target>: + bitbake -u depexp -g bitbake_target: Using the BitBake command with these options brings up a Dependency Explorer from which you can view file dependencies. @@ -5701,7 +5723,7 @@ Gateways via their Web Interfaces" libraries, and applications. To change things, you can configure how the packaging happens, which changes the way you build them. - You can also tweak the filesystem itself or select a different + You can also modify the filesystem itself or select a different filesystem. @@ -5709,7 +5731,7 @@ Gateways via their Web Interfaces" First, find out what is hogging your root filesystem by running the dirsize.py script from your root directory: - $ cd <root-directory-of-image> + $ cd root-directory-of-image $ dirsize.py 100000 > dirsize-100k.log $ cat dirsize-100k.log @@ -5729,8 +5751,8 @@ Gateways via their Web Interfaces" One way to see how packages relate to each other is by using the Dependency Explorer UI with the BitBake command: - $ cd <image-directory> - $ bitbake -u depexp -g <image> + $ cd image-directory + $ bitbake -u depexp -g image Use the interface to select potential packages you wish to eliminate and see their dependency relationships. @@ -5797,7 +5819,7 @@ Gateways via their Web Interfaces" Linux build directory to get an idea of what is making up the kernel: - $ cd <top-level-linux-build-directory> + $ cd top-level-linux-build-directory $ ksize.py > ksize.log $ cat ksize.log @@ -6148,7 +6170,7 @@ Gateways via their Web Interfaces" For this scenario, you need to start the PR Service using the bitbake-prserv command: - bitbake-prserv ‐‐host <ip> ‐‐port <port> ‐‐start + bitbake-prserv ‐‐host ip ‐‐port port ‐‐start In addition to hand-starting the service, you need to update the local.conf file of each @@ -6667,7 +6689,7 @@ Gateways via their Web Interfaces" Realize that it is not sufficient to simply do the following: - $ bitbake <some-package> package-index + $ bitbake some-package package-index This is because BitBake does not properly schedule the package-index target fully after any @@ -6687,7 +6709,7 @@ Gateways via their Web Interfaces" When your build is complete, your packages reside in the - ${TMPDIR}/deploy/<package-format> + ${TMPDIR}/deploy/package-format directory. For example, if ${TMPDIR} is tmp and your selected package type @@ -6785,7 +6807,7 @@ Gateways via their Web Interfaces" If you are using lighttpd, all you need to do is to provide a link from your - ${TMPDIR}/deploy/<package-format> + ${TMPDIR}/deploy/package-format directory to lighttpd's document-root. You can determine the specifics of your lighttpd installation by looking through its configuration file, @@ -6936,7 +6958,7 @@ Gateways via their Web Interfaces" a shell script (run-ptest) that starts the test. The shell script that starts the test must not contain - the actual test, the script only starts it. + the actual test - the script only starts the test. On the other hand, the test can be anything from a simple shell script that runs a binary and checks the output to an elaborate system of test binaries and data files. @@ -6946,7 +6968,7 @@ Gateways via their Web Interfaces" The test generates output in the format used by Automake: - <result>: <testname> + result: testname where the result can be PASS, FAIL, or SKIP, @@ -6974,10 +6996,11 @@ Gateways via their Web Interfaces" EXTRA_IMAGE_FEATURES += "ptest-pkgs" Once your build is complete, the ptest files are installed - into the /usr/lib/<package>/ptest + into the + /usr/lib/package/ptest directory within the image, where - <package> is the name of the - package. + package + is the name of the package. @@ -7062,7 +7085,7 @@ Gateways via their Web Interfaces" Consequently, packages that use the unaltered, patched version of make check automatically cross-compiles. - However, you still must add a + Regardless, you still must add a do_compile_ptest function to build the test suite. Add a function similar to the following to your @@ -7185,7 +7208,7 @@ Gateways via their Web Interfaces" Use the following BitBake command form to fetch all the necessary sources without starting the build: - $ bitbake -c fetchall <target> + $ bitbake -c fetchall target This variation of the BitBake command guarantees that you have all the sources for that BitBake target should you @@ -7200,8 +7223,8 @@ Gateways via their Web Interfaces" By default, the OpenEmbedded build system uses the - Build Directory to - build source code. + Build Directory when + building source code. The build process involves fetching the source files, unpacking them, and then patching them if necessary before the build takes place. @@ -7235,7 +7258,7 @@ Gateways via their Web Interfaces" local.conf file: INHERIT += "externalsrc" - EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree" + EXTERNALSRC_pn-myrecipe = "path-to-your-source-tree" @@ -7249,7 +7272,7 @@ Gateways via their Web Interfaces" EXTERNALSRC_BUILD to point to that directory: - EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree" + EXTERNALSRC_BUILD_pn-myrecipe = "path-to-your-source-tree" @@ -7310,7 +7333,7 @@ Gateways via their Web Interfaces" Using systemd for the Main Image and Using SysVinit for the Rescue Image - Set the these variables in your distribution configuration + Set these variables in your distribution configuration file as follows: DISTRO_FEATURES_append = " systemd" @@ -7354,7 +7377,7 @@ Gateways via their Web Interfaces" Then, you can add the following to your local.conf: - SRCREV_pn-<PN> = "${AUTOREV}" + SRCREV_pn-PN = "${AUTOREV}" PN is the name of the recipe for which you want to enable automatic source @@ -7559,8 +7582,8 @@ Gateways via their Web Interfaces" Enabling Tests - Depending on whether you are planning on running tests using - QEMU or on running them on the hardware, you have to take + Depending on whether you are planning to run tests using + QEMU or on the hardware, you have to take different steps to enable the tests. See the following subsections for information on how to enable both types of tests. @@ -7580,7 +7603,7 @@ Gateways via their Web Interfaces" Add NOPASSWD for your user in /etc/sudoers either for - ALL commands or just for + all commands or just for runqemu-ifup. You must provide the full path as that can change if you are using multiple clones of the @@ -7622,7 +7645,7 @@ Gateways via their Web Interfaces" Once you start running the tests, the following happens: - + A copy of the root filesystem is written to ${WORKDIR}/testimage. @@ -7652,7 +7675,7 @@ Gateways via their Web Interfaces" unittest in the task log at ${WORKDIR}/temp/log.do_testimage. - + @@ -7779,7 +7802,8 @@ Gateways via their Web Interfaces" kmod). Uses a custom - initramfs image with a custom installer. + Initial RAM Disk (initramfs) image with a + custom installer. A normal image that you can install usually creates a single rootfs partition. This image uses another installer that @@ -7859,7 +7883,7 @@ Gateways via their Web Interfaces" In this example, the expect script does the following: - ssh test@10.11.12.1 "pyctl nuc1 <arg>" + ssh test@10.11.12.1 "pyctl nuc1 arg" It then runs a Python script that controls power for a label called nuc1. @@ -7922,7 +7946,7 @@ Gateways via their Web Interfaces" Next, use BitBake to run the tests: - bitbake -c testimage <image> + bitbake -c testimage image @@ -7944,7 +7968,7 @@ Gateways via their Web Interfaces" BBPATH in the local.conf file as normal. Be sure that tests reside in - <layer>/lib/oeqa/runtime. + layer/lib/oeqa/runtime. Be sure that module names do not collide with module names used in the default set of test modules in @@ -7990,7 +8014,7 @@ Gateways via their Web Interfaces" The default tests for the image are defined as: - DEFAULT_TEST_SUITES_pn-<image> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" + DEFAULT_TEST_SUITES_pn-image = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" Add your own test to the list of the by using the following: @@ -8021,7 +8045,7 @@ Gateways via their Web Interfaces" - If you image is already built, make sure the following are set + If your image is already built, make sure the following are set in your local.conf file. Be sure to provide the IP address you need: @@ -8041,22 +8065,6 @@ Gateways via their Web Interfaces" TEST_EXPORT_DIR variable. - - The exported data (i.e. testdata.json) - contains paths to the Build Directory. - Thus, the contents of the directory can be moved - to another machine as long as you update some paths in the - JSON. - Usually you only care about the - ${DEPLOY_DIR}/rpm directory (assuming the RPM and Smart tests - are enabled). - Consequently, running the tests on other machine - means that you have to move the contents and call - runexported with "‐‐deploy-dir PATH: - ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json - runexported.py accepts other arguments as well, see ‐‐help. - - You can now run the tests outside of the build environment: @@ -8071,6 +8079,27 @@ Gateways via their Web Interfaces" runexported.py + + + The exported data (i.e. testdata.json) + contains paths to the Build Directory. + Thus, the contents of the directory can be moved + to another machine as long as you update some paths in the + JSON. + Usually, you only care about the + ${DEPLOY_DIR}/rpm directory + (assuming the RPM and Smart tests are enabled). + Consequently, running the tests on other machine + means that you have to move the contents and call + runexported.py with + "‐‐deploy-dir path" as + follows: + + ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json + + runexported.py accepts other arguments + as well as described using ‐‐help. +
@@ -8081,8 +8110,8 @@ Gateways via their Web Interfaces" proper place for the build system to find them. New tests for additional functionality outside of the core should be added to the layer that adds the functionality, in - <layer>/lib/oeqa/runtime (as - long as + layer/lib/oeqa/runtime + (as long as BBPATH is extended in the layer's layer.conf file as normal). @@ -8192,11 +8221,11 @@ Gateways via their Web Interfaces" The command returns a tuple: (status, output), which are what their names imply - the return code - of 'cmd' and whatever output + of "cmd" and whatever output it produces. The optional timeout argument represents the number of seconds the - test should wait for 'cmd' to + test should wait for "cmd" to return. If the argument is "None", the test uses the default instance's @@ -8293,8 +8322,8 @@ Gateways via their Web Interfaces" Because the host GDB is responsible for loading the debugging information and - for doing the necessary processing to make actual debugging happen, the - user has to make sure the host can access the unstripped binaries complete + for doing the necessary processing to make actual debugging happen, + you have to make sure the host can access the unstripped binaries complete with their debugging information and also be sure the target is compiled with no optimizations. The host GDB must also have local access to all the libraries used by the debugged program. @@ -8342,7 +8371,7 @@ Gateways via their Web Interfaces" - Here is an example that when entered from the host + Here is an example, that when entered from the host, connects to the target and launches Gdbserver in order to "debug" a binary named helloworld: @@ -8393,7 +8422,7 @@ Gateways via their Web Interfaces" Once the binary is built, you can find it here: - tmp/sysroots/<host-arch>/usr/bin/<target-platform>/<target-abi>-gdb + tmp/sysroots/host-arch/usr/bin/target-platform/target-abi-gdb
@@ -8709,7 +8738,7 @@ Gateways via their Web Interfaces" The final thing you need to do to implement the fix in the build is to update the "neard" recipe (i.e. - neard-0.14.bb so that the + neard-0.14.bb) so that the SRC_URI statement includes the patch file. The recipe file is in the folder above the patch. @@ -8922,19 +8951,20 @@ Gateways via their Web Interfaces" Notes - - For information on how to delete information from the Toaster - database, see the - Deleting a Build from the Toaster Database - wiki page. - - - - For information on how to set up an instance of Toaster on - a remote host, see the - Setting Up a Toaster Instance on a Remote Host - wiki page. - + + + For information on how to delete information from the + Toaster database, see the + Deleting a Build from the Toaster Database + wiki page. + + + For information on how to set up an instance of Toaster + on a remote host, see the + Setting Up a Toaster Instance on a Remote Host + wiki page. + + @@ -9179,8 +9209,8 @@ Gateways via their Web Interfaces" If you wish to perform kernel profiling, you need to be sure a vmlinux file that matches the running kernel is available. In the source directory, that file is usually located in - /boot/vmlinux-KERNELVERSION, where - KERNEL-version is the version of the kernel. + /boot/vmlinux-kernelversion, where + kernelversion is the version of the kernel. The OpenEmbedded build system generates separate vmlinux packages for each kernel it builds. Thus, it should just be a question of making sure a matching package is @@ -9282,7 +9312,7 @@ Gateways via their Web Interfaces" The Yocto Project generates a license manifest during image creation that is located - in ${DEPLOY_DIR}/licenses/<image_name-datestamp> + in ${DEPLOY_DIR}/licenses/image_name-datestamp to assist with any audits. -- cgit v1.2.3-54-g00ecf