From 2dcd1f0604e960ab173c7603209ccf2cbdcaaebf Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 29 May 2013 14:09:04 +0300 Subject: dev-manual, kernel-manual: Added links to THISDIR variable There is now a glossary description for the THISDIR variable in ref-manual. I added some cross-reference links to the variable in key places of these two manuals. (From yocto-docs rev: d5e01204b864b81782be33d8119c05ef328f3fd7) Signed-off-by: Scott Rifenbark Conflicts: documentation/dev-manual/dev-manual-common-tasks.xml documentation/kernel-dev/kernel-dev-common.xml Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 248 ++++++++++----------- documentation/kernel-dev/kernel-dev-advanced.xml | 2 +- documentation/kernel-dev/kernel-dev-common.xml | 33 +-- 3 files changed, 143 insertions(+), 140 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 219ee68d40..f4358e13d3 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -411,7 +411,7 @@ install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ fi } - In the main recipe, note the + In the main recipe, note the SRC_URI variable, which tells the OpenEmbedded build system where to find files during the build. @@ -431,27 +431,27 @@ - By default, the build system uses the + By default, the build system uses the FILESPATH variable to locate files. - This append file extends the locations by setting the + This append file extends the locations by setting the FILESEXTRAPATHS variable. Setting this variable in the .bbappend - file is the most reliable and recommended method for adding - directories to the search path used by the build system + file is the most reliable and recommended method for adding + directories to the search path used by the build system to find files. - The statement in this example extends the directories to include - ${THISDIR}/${PN}, - which resolves to a directory named - formfactor in the same directory + The statement in this example extends the directories to include + ${THISDIR}/${PN}, + which resolves to a directory named + formfactor in the same directory in which the append file resides (i.e. meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor. - This implies that you must have the supporting directory - structure set up that will contain any files or patches you + This implies that you must have the supporting directory + structure set up that will contain any files or patches you will be including from the layer. @@ -660,7 +660,7 @@ script to accept the default value. Once the script completes, the new layer is created in the current working directory. - The script names the layer by prepending + The script names the layer by prepending meta- to the name you provide. @@ -1270,7 +1270,7 @@ To add a post-installation script to a package, add a - pkg_postinst_PACKAGENAME() function to the + pkg_postinst_PACKAGENAME() function to the .bb file and use PACKAGENAME as the name of the package you want to attach to the postinst script. @@ -1504,8 +1504,8 @@ By default, the PACKAGES variable contains ${PN}-staticdev, which includes all static library files. - Some previously released versions of the Yocto Project - defined the static library files through + Some previously released versions of the Yocto Project + defined the static library files through ${PN}-dev. Following, is part of the BitBake configuration file. @@ -1810,7 +1810,7 @@ To use the menuconfig tool in the Yocto Project development environment, you must build the tool using BitBake. - Thus, the environment must be set up using the + Thus, the environment must be set up using the &OE_INIT_FILE; script found in the Build Directory. @@ -2240,7 +2240,7 @@ The FILESEXTRAPATHS and SRC_URI statements enable the OpenEmbedded build system to find the patch file. - For more information on using append files, see the + For more information on using append files, see the "Using .bbappend Files" section. @@ -2262,7 +2262,7 @@ Build for the correct target architecture: Your selected MACHINE - definition within the local.conf file in the + definition within the local.conf file in the Build Directory specifies the target architecture used when building the Linux kernel. By default, MACHINE is set to @@ -2270,7 +2270,7 @@ Intel Architecture target machine suitable for the QEMU emulator. Identify your meta-mylayer - layer: The + layer: The BBLAYERS variable in the bblayers.conf file found in the @@ -2306,7 +2306,7 @@ Be sure your build environment is initialized: Your environment should be set up since you previously sourced - the + the &OE_INIT_FILE; script. If it is not, source the script again from poky. @@ -2322,7 +2322,7 @@ $ bitbake -c cleansstate linux-yocto Never remove any files by hand from the tmp/deploy - directory inside the + directory inside the Build Directory. Always use the various BitBake clean tasks to clear out previous build artifacts. @@ -2390,7 +2390,7 @@ configurations in a local.conf configuration file makes it easier to reproduce the same build configuration when using multiple build machines. - See the + See the "Creating a General Layer Using the yocto-layer Script" section for information on how to quickly set up a layer. @@ -2416,7 +2416,7 @@ DISTRO_NAME [required] DISTRO_VERSION [required] - These following variables are optional and you typically + These following variables are optional and you typically set them from the distribution configuration file: DISTRO_FEATURES [optional] @@ -2427,7 +2427,7 @@ If you want to base your distribution configuration file on the very basic configuration from OE-Core, you - can use + can use conf/distro/defaultsetup.conf as a reference and just include variables that differ as compared to defaultsetup.conf. @@ -2573,7 +2573,7 @@ poky-tiny. To use poky-tiny in your build, - set the + set the DISTRO variable in your local.conf file to "poky-tiny" @@ -3069,7 +3069,7 @@ The alternative to setting up a PR Service is to manually - bump the + bump the PR variable. @@ -3102,8 +3102,8 @@ When upgrading the version of a package, assuming the PV - changes, the PR variable should be - reset to "r0" (or "$(INC_PR).0" if you are using + changes, the PR variable should be + reset to "r0" (or "$(INC_PR).0" if you are using INC_PR). @@ -3163,7 +3163,7 @@ $ bitbake world -f -c distro_check The results are stored in the build/tmp/log/distro_check-${DATETIME}.results - file found in the + file found in the Source Directory. @@ -3203,7 +3203,7 @@ The do_split_packages function searches for a pattern of files or directories under a specified path and creates a package for each one it finds - by appending to the + by appending to the PACKAGES variable and setting the appropriate values for FILES_packagename, @@ -3241,7 +3241,7 @@ Thus, if a file in ${libdir} called mod_alias.so is found, a package called lighttpd-module-alias - is created for it and the + is created for it and the DESCRIPTION is set to "Lighttpd module for alias". @@ -3265,7 +3265,7 @@ do_split_packages, see the connman.inc file in the meta/recipes-connectivity/connman/ - directory of the poky + directory of the poky source repository. You can also find examples in meta/classes/kernel.bbclass. @@ -3535,33 +3535,33 @@ Testing Packages With ptest - A Package Test (ptest) runs tests against packages built + A Package Test (ptest) runs tests against packages built by the OpenEmbedded build system on the target machine. - A ptest contains at least two items: the actual test, and + A ptest contains at least two items: the actual test, and a shell script (run-ptest) that starts the test. - The shell script that starts the test must not contain + The shell script that starts the test must not contain the actual test, the script only starts it. On the other hand, the test can be anything from a simple - shell script that runs a binary and checks the output to + shell script that runs a binary and checks the output to an elaborate system of test binaries and data files. - The test generates output in the format used by + The test generates output in the format used by Automake: <result>: <testname> - where the result can be PASS, + where the result can be PASS, FAIL, or SKIP, and the testname can be any identifying string. With this release of the Yocto Project, three recipes exist - that are "ptest-enabled": bash, - glib-2.0, and + that are "ptest-enabled": bash, + glib-2.0, and dbus. These three recipes are Autotool-enabled. @@ -3570,20 +3570,20 @@ Adding ptest to Your Build - To add package testing to your build, add the + To add package testing to your build, add the DISTRO_FEATURES and EXTRA_IMAGE_FEATURES - variables to your local.conf file, - which is found in the + variables to your local.conf file, + which is found in the Build Directory: - EXTRA_IMAGE_FEATURES += "ptest" + EXTRA_IMAGE_FEATURES += "ptest" DISTRO_FEATURES_append = " ptest-pkgs" Once your build is complete, the ptest files are installed into the /usr/lib/<package>/ptest - directory within the image, where - <package> is the name of the + directory within the image, where + <package> is the name of the package. @@ -3592,21 +3592,21 @@ Running ptest - The ptest-runner package installs a - shell script that loops through all installed ptest test - suites and runs them in sequence. + The ptest-runner package installs a + shell script that loops through all installed ptest test + suites and runs them in sequence. Consequently, you might want to add this package to - your image. + your image. - +
Getting Your Package Ready - + - In order to enable a recipe to run installed ptests - on target hardware, - you need to prepare the recipes that build the packages + In order to enable a recipe to run installed ptests + on target hardware, + you need to prepare the recipes that build the packages you want to test. Here is what you have to do for each recipe: @@ -3619,10 +3619,10 @@ Create run-ptest: This script starts your test. - Locate the script where you will refer to it - using + Locate the script where you will refer to it + using SRC_URI. - Here is an example that starts a test for + Here is an example that starts a test for dbus: #!/bin/sh @@ -3632,45 +3632,45 @@ Ensure dependencies are met: - If the test adds build or runtime dependencies - that normally do not exist for the package - (such as requiring "make" to run the test suite), - use the + If the test adds build or runtime dependencies + that normally do not exist for the package + (such as requiring "make" to run the test suite), + use the DEPENDS - and + and RDEPENDS variables in your recipe in order for the package - to meet the dependencies. - Here is an example where the package has a runtime + to meet the dependencies. + Here is an example where the package has a runtime dependency on "make": RDEPENDS_${PN}-ptest += "make" - Add a function to build the + Add a function to build the test suite: - Not many packages support cross-compilation of - their test suites. - Consequently, you usually need to add a + Not many packages support cross-compilation of + their test suites. + Consequently, you usually need to add a cross-compilation function to the package. - Many packages based on Automake compile and + Many packages based on Automake compile and run the test suite by using a single command such as make check. However, the native make check - builds and runs on the same computer, while - cross-compiling requires that the package is built + builds and runs on the same computer, while + cross-compiling requires that the package is built on the host but executed on the target. - The built version of Automake that ships with the - Yocto Project includes a patch that separates + The built version of Automake that ships with the + Yocto Project includes a patch that separates building and execution. - Consequently, packages that use the unaltered, + Consequently, packages that use the unaltered, patched version of make check automatically cross-compiles. - However, you still must add a - do_compile_ptest function to + However, you still must add a + do_compile_ptest function to build the test suite. - Add a function similar to the following to your + Add a function similar to the following to your recipe: do_compile_ptest() { @@ -3680,26 +3680,26 @@ Ensure special configurations are set: - If the package requires special configurations + If the package requires special configurations prior to compiling the test code, you must insert a do_configure_ptest function into the recipe. - Install the test + Install the test suite: - The ptest.bbclass class - automatically copies the file - run-ptest to the target and + The ptest.bbclass class + automatically copies the file + run-ptest to the target and then runs make install-ptest - to run the tests. - If this is not enough, you need to create a - do_install_ptest function and - make sure it gets called after the + to run the tests. + If this is not enough, you need to create a + do_install_ptest function and + make sure it gets called after the "make install-ptest" completes. -
+ @@ -3779,9 +3779,9 @@ It is recommended that you create your own distribution configuration - file to hold these settings instead of using your + file to hold these settings instead of using your local.conf file. - For information on creating your own distribution, see the + For information on creating your own distribution, see the "Creating Your Own Distribution" section. @@ -3797,7 +3797,7 @@ VIRTUAL-RUNTIME_init_manager = "systemd" You can also prevent the sysvinit - distribution feature from + distribution feature from being automatically enabled as follows: DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" @@ -3838,7 +3838,7 @@ However, on rare occasions where you might want to use a layer but exclude parts that are causing problems, such as introducing a different version of a recipe, you can - use + use BBMASK to exclude the recipe. @@ -3978,7 +3978,7 @@ creation: Not using $D in front of absolute paths: - The build system defines + The build system defines $D at root filesystem creation time, and it is blank when run on the target device. @@ -4034,9 +4034,9 @@ - For best results, install -dbg packages for + For best results, install -dbg packages for the applications you are going to debug. - Doing so makes extra debug symbols available that give you more + Doing so makes extra debug symbols available that give you more meaningful output. @@ -4097,11 +4097,11 @@ Before you can initiate a remote debugging session, you need to be sure you have set up the cross-development environment, - toolchain, and sysroot. + toolchain, and sysroot. The "Preparing for Application Development" chapter of the Yocto Project Application Developer's Guide describes this process. - Be sure you have read that chapter and have set up + Be sure you have read that chapter and have set up your environment. @@ -4111,22 +4111,22 @@ Make sure Gdbserver is installed on the target. - If it is not, install the package + If it is not, install the package gdbserver, which needs the libthread-db1 package. - Here is an example that when entered from the host - connects to the target and launches Gdbserver in order to + 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: $ gdbserver localhost:2345 /usr/bin/helloworld Gdbserver should now be listening on port 2345 for debugging - commands coming from a remote GDB process that is running on + commands coming from a remote GDB process that is running on the host computer. - Communication between Gdbserver and the host GDB are done + Communication between Gdbserver and the host GDB are done using TCP. To use other communication protocols, please refer to the Gdbserver documentation. @@ -4144,23 +4144,23 @@
Build the Cross-GDB Package - A suitable GDB cross-binary is required that runs on your - host computer but also knows about the the ABI of the + A suitable GDB cross-binary is required that runs on your + host computer but also knows about the the ABI of the remote target. - You can get this binary from the + You can get this binary from the Cross-Development Toolchain. Here is an example where the toolchain has been installed - in the default directory + in the default directory /opt/poky/&DISTRO;: /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb - where arm is the target architecture + where arm is the target architecture and linux-gnueabi is the target ABI. - Alternatively, you can use BitBake to build the + Alternatively, you can use BitBake to build the gdb-cross binary. Here is an example: @@ -4190,10 +4190,10 @@ - You need to add a statement in the + You need to add a statement in the .gdbinit file that points to your root filesystem. - Here is an example that points to the root filesystem for + Here is an example that points to the root filesystem for an ARM-based target device: set sysroot /home/jzhang/sysroot_arm @@ -4205,14 +4205,14 @@ Launch the Host GDB - Before launching the host GDB, you need to be sure - you have sourced the cross-debugging environment script, - which if you installed the root filesystem in the default - location is at /opt/poky/&DISTRO; + Before launching the host GDB, you need to be sure + you have sourced the cross-debugging environment script, + which if you installed the root filesystem in the default + location is at /opt/poky/&DISTRO; and begins with the string "environment-setup". - For more information, see the + For more information, see the "Setting Up the Cross-Development Environment" - section in the Yocto Project Application Developer's + section in the Yocto Project Application Developer's Guide. @@ -4222,7 +4222,7 @@ Provide the binary file you are going to debug. For example, the following command continues with the example used in the previous section by loading - the helloworld binary as well as the + the helloworld binary as well as the debugging information: $ arm-poky-linux-gnuabi-gdb helloworld @@ -4238,7 +4238,7 @@ From the target, you need to connect to the remote GDB - server that is running on the host. + server that is running on the host. You need to specify the remote host and port. Here is the command continuing with the example: @@ -4315,7 +4315,7 @@ DEBUG_BUILD variable to "1" in the local.conf configuration file. If you use the DEBUG_BUILD variable, - you also add extra debugging information that can make the debug + you also add extra debugging information that can make the debug packages large. @@ -4390,8 +4390,8 @@ . If the "tools-profile" image feature is selected, all necessary binaries are installed onto the target device for OProfileUI interaction. - For a list of image features that ship with the Yocto Project, - see the + For a list of image features that ship with the Yocto Project, + see the "Images" section in the Yocto Project Reference Manual. @@ -4460,7 +4460,7 @@ - Downloaded archives reside in the + Downloaded archives reside in the Build Directory in /tmp and are cleared up when they are no longer in use. @@ -4604,7 +4604,7 @@ release of proprietary software. The Yocto Project provides an archiver class to help avoid some of these concerns. - See the + See the "Archiving Sources - archive*.bbclass" section in the Yocto Project Reference Manual for information on this class. @@ -4752,7 +4752,7 @@ ##COREBASE##/meta-yocto \ " - Creating and providing an archive of the + Creating and providing an archive of the Metadata layers (recipes, configuration files, and so forth) enables you to meet your diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 2626f691dc..d15e26ffbf 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -203,7 +203,7 @@ oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb to a recipe in your layer, FILESEXTRAPATHS is typically set to - ${THISDIR}/${PN}. + ${THISDIR}/${PN}. See the "Modifying an Existing Recipe" section for more information. diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index f0e95aca07..fb258f286c 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -92,10 +92,13 @@ FILESEXTRAPATHS := "${THISDIR}/${PN}" - The path ${THISDIR}/${PN} expands - to "linux-yocto" in the current directory for this example. - If you add any new files that modify the kernel recipe, - you need to place them in your layer in the following area: + The path ${THISDIR}/${PN} + expands to "linux-yocto" in the current directory for this + example. + If you add any new files that modify the kernel recipe and you + have extended FILESPATH as + described above, you must place the files in your layer in the + following area: <your-layer>/recipes-kernel/linux/linux-yocto/ @@ -149,15 +152,15 @@ You can make wholesale or incremental changes to the Linux kernel .config file by including a defconfig or by specifying - configuration fragments in the + configuration fragments in the SRC_URI. If you have a complete Linux kernel .config - file you want to use, copy it to a directory named - files, which must be in - your layer's recipes-kernel/linux + file you want to use, copy it to a directory named + files, which must be in + your layer's recipes-kernel/linux directory, and name the file "defconfig". Then, add the following lines to your linux-yocto .bbappend file in your layer: @@ -165,13 +168,13 @@ FILESEXTRAPATHS_prepend := "${THISDIR}/files:" SRC_URI += "file://defconfig" - The - SRC_URI tells the build system how to - search for the file, while the + The + SRC_URI tells the build system how to + search for the file, while the FILESEXTRAPATHS - extends the + extends the FILESPATH - variable (search directories) to include the + variable (search directories) to include the files directory you created for the configuration changes. @@ -193,8 +196,8 @@ CONFIG_SERIAL_CORE=y CONFIG_SERIAL_CORE_CONSOLE=y - Next, include this configuration fragment and extend the - FILESPATH variable in your + Next, include this configuration fragment and extend the + FILESPATH variable in your .bbappend file: FILESEXTRAPATHS_prepend := "${THISDIR}/files:" -- cgit v1.2.3-54-g00ecf