diff options
Diffstat (limited to 'external/poky/documentation/dev-manual/dev-manual-common-tasks.xml')
| -rw-r--r-- | external/poky/documentation/dev-manual/dev-manual-common-tasks.xml | 814 |
1 files changed, 692 insertions, 122 deletions
diff --git a/external/poky/documentation/dev-manual/dev-manual-common-tasks.xml b/external/poky/documentation/dev-manual/dev-manual-common-tasks.xml index c75e718d..e9ce182a 100644 --- a/external/poky/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/external/poky/documentation/dev-manual/dev-manual-common-tasks.xml @@ -184,6 +184,10 @@ variable. </para></listitem> <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></ulink>: + Lists all layers on which this layer depends (if any). + </para></listitem> + <listitem><para> <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>: Lists the <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Yocto Project</ulink> @@ -315,12 +319,26 @@ DEPENDS_append_one = " foo" DEPENDS_prepend_one = "foo " </literallayout> - As an actual example, here's a line from the recipe - for gnutls, which adds dependencies on - "argp-standalone" when building with the musl C - library: + As an actual example, here's a snippet from the + generic kernel include file + <filename>linux-yocto.inc</filename>, + wherein the kernel compile and link options are + adjusted in the case of a subset of the supported + architectures: <literallayout class='monospaced'> - DEPENDS_append_libc-musl = " argp-standalone" + DEPENDS_append_aarch64 = " libgcc" + KERNEL_CC_append_aarch64 = " ${TOOLCHAIN_OPTIONS}" + KERNEL_LD_append_aarch64 = " ${TOOLCHAIN_OPTIONS}" + + DEPENDS_append_nios2 = " libgcc" + KERNEL_CC_append_nios2 = " ${TOOLCHAIN_OPTIONS}" + KERNEL_LD_append_nios2 = " ${TOOLCHAIN_OPTIONS}" + + DEPENDS_append_arc = " libgcc" + KERNEL_CC_append_arc = " ${TOOLCHAIN_OPTIONS}" + KERNEL_LD_append_arc = " ${TOOLCHAIN_OPTIONS}" + + KERNEL_FEATURES_append_qemuall=" features/debug/printk.scc" </literallayout> <note> Avoiding "+=" and "=+" and using @@ -580,11 +598,19 @@ <filename>bitbake -e</filename>). </para></listitem> <listitem><para> + <filename>common.test_world</filename>: + Verifies that <filename>bitbake world</filename> works. + </para></listitem> + <listitem><para> <filename>common.test_signatures</filename>: Tests to be sure that BSP and DISTRO layers do not come with recipes that change signatures. </para></listitem> <listitem><para> + <filename>common.test_layerseries_compat</filename>: + Verifies layer compatibility is set properly. + </para></listitem> + <listitem><para> <filename>bsp.test_bsp_defines_machines</filename>: Tests if a BSP layer has machine configurations. </para></listitem> @@ -594,11 +620,22 @@ machine when the layer is added. </para></listitem> <listitem><para> + <filename>bsp.test_machine_world</filename>: + Verifies that <filename>bitbake world</filename> + works regardless of which machine is selected. + </para></listitem> + <listitem><para> + <filename>bsp.test_machine_signatures</filename>: + Verifies that building for a particular machine + affects only the signature of tasks specific to that + machine. + </para></listitem> + <listitem><para> <filename>distro.test_distro_defines_distros</filename>: Tests if a DISTRO layer has distro configurations. </para></listitem> <listitem><para> - <filename>distro.test_distro_no_set_distro</filename>: + <filename>distro.test_distro_no_set_distros</filename>: Tests to ensure a DISTRO layer does not set the distribution when the layer is added. </para></listitem> @@ -1397,7 +1434,7 @@ package specified in the <filename>PACKAGES</filename> statement. <note> - The <filename>inherit packages</filename> should be + The <filename>inherit packagegroup</filename> line should be located near the top of the recipe, certainly before the <filename>PACKAGES</filename> statement. </note> @@ -1417,28 +1454,32 @@ <para> Here is a short, fabricated example showing the same basic - pieces: + pieces for a hypothetical packagegroup defined in + <filename>packagegroup-custom.bb</filename>, where the + variable <filename>PN</filename> is the standard way to + abbreviate the reference to the full packagegroup name + <filename>packagegroup-custom</filename>: <literallayout class='monospaced'> DESCRIPTION = "My Custom Package Groups" inherit packagegroup PACKAGES = "\ - packagegroup-custom-apps \ - packagegroup-custom-tools \ + ${PN}-apps \ + ${PN}-tools \ " - RDEPENDS_packagegroup-custom-apps = "\ + RDEPENDS_${PN}-apps = "\ dropbear \ portmap \ psplash" - RDEPENDS_packagegroup-custom-tools = "\ + RDEPENDS_${PN}-tools = "\ oprofile \ oprofileui-server \ lttng-tools" - RRECOMMENDS_packagegroup-custom-tools = "\ + RRECOMMENDS_${PN}-tools = "\ kernel-module-oprofile" </literallayout> </para> @@ -1883,7 +1924,8 @@ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink> task uses the prefix of each entry in the <filename>SRC_URI</filename> variable value to determine which - fetcher to use to get your source files. + <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetcher</ulink> + to use to get your source files. It is the <filename>SRC_URI</filename> variable that triggers the fetcher. The @@ -1899,9 +1941,9 @@ <para> The <filename>SRC_URI</filename> variable in your recipe must define each unique location for your source files. - It is good practice to not hard-code pathnames in an URL used + It is good practice to not hard-code version numbers in a URL used in <filename>SRC_URI</filename>. - Rather than hard-code these paths, use + Rather than hard-code these values, use <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink><filename>}</filename>, which causes the fetch process to use the version specified in the recipe filename. @@ -1912,13 +1954,13 @@ <para> Here is a simple example from the - <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a20.bb</filename> + <filename>meta/recipes-devtools/strace/strace_5.5.bb</filename> recipe where the source comes from a single tarball. Notice the use of the <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> variable: <literallayout class='monospaced'> - SRC_URI = "ftp://ftp.berlios.de/pub/cdrecord/alpha/cdrtools-${PV}.tar.bz2" + SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \ </literallayout> </para> @@ -1977,16 +2019,17 @@ For these cases, you provide a name for each URL as part of the <filename>SRC_URI</filename> and then reference that name in the subsequent checksum statements. - Here is an example: + Here is an example combining lines from the files + <filename>git.inc</filename> and + <filename>git_2.24.1.bb</filename>: <literallayout class='monospaced'> - SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \ - ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch" + SRC_URI = "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \ + ${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages" - SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8" - SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d" - - SRC_URI[patch.md5sum] = "57e1b689264ea80f78353519eece0c92" - SRC_URI[patch.sha256sum] = "7905ff96be93d725544d0040e425c42f9c05580db3c272f11cff75b9aa89d430" + SRC_URI[tarball.md5sum] = "166bde96adbbc11c8843d4f8f4f9811b" + SRC_URI[tarball.sha256sum] = "ad5334956301c86841eb1e5b1bb20884a6bad89a10a6762c958220c7cf64da02" + SRC_URI[manpages.md5sum] = "31c2272a8979022497ba3d4202df145d" + SRC_URI[manpages.sha256sum] = "9a7ae3a093bea39770eb96ca3e5b40bff7af0b9f6123f089d7821d0e5b8e1230" </literallayout> </para> @@ -2348,7 +2391,7 @@ Most software provides some means of setting build-time configuration options before compilation. Typically, setting these options is accomplished by running a - configure script with some options, or by modifying a build + configure script with options, or by modifying a build configuration file. <note> As of Yocto Project Release 1.7, some of the core recipes @@ -2388,6 +2431,7 @@ software is built using Autotools. If this is the case, you just need to worry about modifying the configuration.</para> + <para>When using Autotools, your recipe needs to inherit the <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> @@ -2400,13 +2444,15 @@ or <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> to pass any needed configure options that are specific - to the recipe.</para></listitem> + to the recipe. + </para></listitem> <listitem><para><emphasis>CMake:</emphasis> If your source files have a <filename>CMakeLists.txt</filename> file, then your software is built using CMake. If this is the case, you just need to worry about modifying the configuration.</para> + <para>When you use CMake, your recipe needs to inherit the <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink> @@ -2416,7 +2462,16 @@ You can make some adjustments by setting <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink> to pass any needed configure options that are specific - to the recipe.</para></listitem> + to the recipe. + <note> + If you need to install one or more custom CMake + toolchain files that are supplied by the + application you are building, install the files to + <filename>${D}${datadir}/cmake/</filename> Modules + during + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>. + </note> + </para></listitem> <listitem><para><emphasis>Other:</emphasis> If your source files do not have a <filename>configure.ac</filename> or @@ -2779,6 +2834,14 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> for additional information. </para></listitem> + <listitem><para> + If you need to install one or more custom CMake + toolchain files that are supplied by the + application you are building, install the files to + <filename>${D}${datadir}/cmake/</filename> Modules + during + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>. + </para></listitem> </itemizedlist> </note> </section> @@ -3221,8 +3284,6 @@ The script defined in the post-installation function is called when the root filesystem is created. 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. <note> Any RPM post-installation script that runs on the target should return a 0 exit code. @@ -3241,7 +3302,7 @@ mark post installs to defer to the target. You can use <filename>pkg_postinst_ontarget()</filename> or call - <filename>postinst-intercepts defer_to_first_boot</filename> + <filename>postinst_intercept delay_to_first_boot</filename> from <filename>pkg_postinst()</filename>. Any failure of a <filename>pkg_postinst()</filename> script (including exit 1) triggers an error during the @@ -4196,11 +4257,27 @@ built by layer recipes. It is recommended to keep recipes up-to-date with upstream version releases. + </para> + + <para> + While several methods exist that allow you upgrade a recipe, + you might consider checking on the upgrade status of a recipe + first. + You can do so using the + <filename>devtool check-upgrade-status</filename> command. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#devtool-checking-on-the-upgrade-status-of-a-recipe'>Checking on the Upgrade Status of a Recipe</ulink>" + section in the Yocto Project Reference Manual for more information. + </para> + + <para> + The remainder of this section describes three ways you can + upgrade a recipe. You can use the Automated Upgrade Helper (AUH) to set up automatic version upgrades. Alternatively, you can use <filename>devtool upgrade</filename> to set up semi-automatic version upgrades. - Finally, you can even manually upgrade a recipe by editing the + Finally, you can manually upgrade a recipe by editing the recipe itself. </para> @@ -4319,12 +4396,6 @@ Make these following configurations: <itemizedlist> <listitem><para> - Enable "distrodata" as follows: - <literallayout class='monospaced'> - INHERIT =+ "distrodata" - </literallayout> - </para></listitem> - <listitem><para> If you want to enable <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Build History</ulink>, which is optional, you need the following @@ -5116,15 +5187,15 @@ So, commands such as the following are useful when exploring the data store and running functions: <literallayout class='monospaced'> - pydevshell> d.getVar("STAGING_DIR", True) + pydevshell> d.getVar("STAGING_DIR") '/media/build1/poky/build/tmp/sysroots' - pydevshell> d.getVar("STAGING_DIR", False) + pydevshell> d.getVar("STAGING_DIR") '${TMPDIR}/sysroots' pydevshell> d.setVar("FOO", "bar") - pydevshell> d.getVar("FOO", True) + pydevshell> d.getVar("FOO") 'bar' pydevshell> d.delVar("FOO") - pydevshell> d.getVar("FOO", True) + pydevshell> d.getVar("FOO") pydevshell> bb.build.exec_func("do_unpack", d) pydevshell> </literallayout> @@ -5409,26 +5480,39 @@ <literallayout class='monospaced'> BBMULTICONFIG = "x86 arm" </literallayout> + <note> + A "default" configuration already exists by + definition. + This configuration is named: "" (i.e. empty + string) and is defined by the variables coming + from your <filename>local.conf</filename> file. + Consequently, the previous example actually + adds two additional configurations to your + build: "arm" and "x86" along with "". + </note> </para></listitem> <listitem><para> <emphasis>Launch BitBake</emphasis>: Use the following BitBake command form to launch the multiple configuration build: <literallayout class='monospaced'> - $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] + $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] </literallayout> For the example in this section, the following command applies: <literallayout class='monospaced'> - $ bitbake multiconfig:x86:core-image-minimal multiconfig:arm:core-image-sato + $ bitbake mc:x86:core-image-minimal mc:arm:core-image-sato mc::core-image-base </literallayout> The previous BitBake command builds a <filename>core-image-minimal</filename> image that is configured through the - <filename>x86.conf</filename> configuration file - and builds a <filename>core-image-sato</filename> + <filename>x86.conf</filename> configuration file, + a <filename>core-image-sato</filename> image that is configured through the - <filename>arm.conf</filename> configuration file. + <filename>arm.conf</filename> configuration file + and a <filename>core-image-base</filename> that is + configured through your + <filename>local.conf</filename> configuration file. </para></listitem> </itemizedlist> <note> @@ -5468,7 +5552,7 @@ build, you must declare the dependencies in the recipe using the following statement form: <literallayout class='monospaced'> - <replaceable>task_or_package</replaceable>[mcdepends] = "multiconfig:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>" + <replaceable>task_or_package</replaceable>[mcdepends] = "mc:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>" </literallayout> To better show how to use this statement, consider the example scenario from the first paragraph of this section. @@ -5476,7 +5560,7 @@ that builds the <filename>core-image-sato</filename> image: <literallayout class='monospaced'> - do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_rootfs" + do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" </literallayout> In this example, the <replaceable>from_multiconfig</replaceable> is "x86". @@ -5491,7 +5575,7 @@ Once you set up this dependency, you can build the "x86" multiconfig using a BitBake command as follows: <literallayout class='monospaced'> - $ bitbake multiconfig:x86:core-image-sato + $ bitbake mc:x86:core-image-sato </literallayout> This command executes all the tasks needed to create the <filename>core-image-sato</filename> image for the @@ -5507,7 +5591,7 @@ Consider this change to the statement in the <filename>core-image-sato</filename> recipe: <literallayout class='monospaced'> - do_image[mcdepends] = "multiconfig:x86:arm:core-image-minimal:do_image" + do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" </literallayout> In this case, BitBake must create the <filename>core-image-minimal</filename> image for the @@ -6323,9 +6407,180 @@ </literallayout> </para> </section> - </section> + <section id="replicating-a-build-offline"> + <title>Replicating a Build Offline</title> + <para> + It can be useful to take a "snapshot" of upstream sources + used in a build and then use that "snapshot" later to + replicate the build offline. + To do so, you need to first prepare and populate your downloads + directory your "snapshot" of files. + Once your downloads directory is ready, you can use it at + any time and from any machine to replicate your build. + </para> + + <para> + Follow these steps to populate your Downloads directory: + <orderedlist> + <listitem><para> + <emphasis>Create a Clean Downloads Directory:</emphasis> + Start with an empty downloads directory + (<ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>). + You start with an empty downloads directory by either + removing the files in the existing directory or by + setting + <filename>DL_DIR</filename> to point to either an + empty location or one that does not yet exist. + </para></listitem> + <listitem><para> + <emphasis>Generate Tarballs of the Source Git Repositories:</emphasis> + Edit your <filename>local.conf</filename> configuration + file as follows: + <literallayout class='monospaced'> + DL_DIR = "/home/<replaceable>your-download-dir</replaceable>/" + BB_GENERATE_MIRROR_TARBALLS = "1" + </literallayout> + During the fetch process in the next step, BitBake + gathers the source files and creates tarballs in + the directory pointed to by <filename>DL_DIR</filename>. + See the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink> + variable for more information. + </para></listitem> + <listitem><para> + <emphasis>Populate Your Downloads Directory Without Building:</emphasis> + Use BitBake to fetch your sources but inhibit the + build: + <literallayout class='monospaced'> + $ bitbake <replaceable>target</replaceable> --runonly=fetch + </literallayout> + The downloads directory (i.e. + <filename>${DL_DIR}</filename>) now has a "snapshot" of + the source files in the form of tarballs, which can + be used for the build. + </para></listitem> + <listitem><para> + <emphasis>Optionally Remove Any Git or other SCM Subdirectories From the Downloads Directory:</emphasis> + If you want, you can clean up your downloads directory + by removing any Git or other Source Control Management + (SCM) subdirectories such as + <filename>${DL_DIR}/git2/*</filename>. + The tarballs already contain these subdirectories. + </para></listitem> + </orderedlist> + </para> + + <para> + Once your downloads directory has everything it needs regarding + source files, you can create your "own-mirror" and build + your target. + Understand that you can use the files to build the target + offline from any machine and at any time. + </para> + + <para> + Follow these steps to build your target using the files in the + downloads directory: + <orderedlist> + <listitem><para> + <emphasis>Using Local Files Only:</emphasis> + Inside your <filename>local.conf</filename> file, add + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></ulink> + variable, + inherit the <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-own-mirrors'><filename>own-mirrors</filename></ulink> + class, and use the + <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></ulink> + variable to your <filename>local.conf</filename>. + <literallayout class='monospaced'> + SOURCE_MIRROR_URL ?= "file:///home/<replaceable>your-download-dir</replaceable>/" + INHERIT += "own-mirrors" + BB_NO_NETWORK = "1" + </literallayout> + The <filename>SOURCE_MIRROR_URL</filename> and + <filename>own-mirror</filename> class set up the system + to use the downloads directory as your "own mirror". + Using the <filename>BB_NO_NETWORK</filename> + variable makes sure that BitBake's fetching process + in step 3 stays local, which means files from + your "own-mirror" are used. + </para></listitem> + <listitem><para> + <emphasis>Start With a Clean Build:</emphasis> + You can start with a clean build by removing the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink><filename>}</filename> + directory or using a new + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Build Your Target:</emphasis> + Use BitBake to build your target: + <literallayout class='monospaced'> + $ bitbake <replaceable>target</replaceable> + </literallayout> + The build completes using the known local "snapshot" of + source files from your mirror. + The resulting tarballs for your "snapshot" of source + files are in the downloads directory. + <note> + <para>The offline build does not work if recipes + attempt to find the latest version of software + by setting + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + to + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink><filename>}</filename>: + <literallayout class='monospaced'> + SRCREV = "${AUTOREV}" + </literallayout> + When a recipe sets + <filename>SRCREV</filename> to + <filename>${AUTOREV}</filename>, the build system + accesses the network in an attempt to determine the + latest version of software from the SCM. + Typically, recipes that use + <filename>AUTOREV</filename> are custom or + modified recipes. + Recipes that reside in public repositories + usually do not use <filename>AUTOREV</filename>. + </para> + + <para>If you do have recipes that use + <filename>AUTOREV</filename>, you can take steps to + still use the recipes in an offline build. + Do the following: + <orderedlist> + <listitem><para> + Use a configuration generated by + enabling + <link linkend='maintaining-build-output-quality'>build history</link>. + </para></listitem> + <listitem><para> + Use the + <filename>buildhistory-collect-srcrevs</filename> + command to collect the stored + <filename>SRCREV</filename> values from + the build's history. + For more information on collecting these + values, see the + "<link linkend='build-history-package-information'>Build History Package Information</link>" + section. + </para></listitem> + <listitem><para> + Once you have the correct source + revisions, you can modify those recipes + to to set <filename>SRCREV</filename> + to specific versions of the software. + </para></listitem> + </orderedlist> + </para> + </note> + </para></listitem> + </orderedlist> + </para> + </section> + </section> <section id='speeding-up-a-build'> <title>Speeding Up a Build</title> @@ -6892,8 +7147,8 @@ <literallayout class='monospaced'> MACHINE = "qemux86-64" DEFAULTTUNE = "x86-64-x32" - baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ - or 'INVALID'), True) or 'lib'}" + baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE') \ + or 'INVALID')) or 'lib'}" </literallayout> Once you have set up your configuration file, use BitBake to build an image that supports the x32 psABI. @@ -6947,7 +7202,8 @@ This problem is solved with the OpenEmbedded build system by running the code through QEMU, which allows precisely that. Unfortunately, QEMU does not always work perfectly as mentioned - in the xxx section. + in the + "<link linkend='known-issues'>Known Issues</link>" section. </para> <section id='enabling-the-generation-of-introspection-data'> @@ -7216,17 +7472,17 @@ it is based on is by definition incomplete. The purpose of the command is to allow the generation of customized images, and as such, was designed to be - completely extensible through a plug-in interface. + completely extensible through a plugin interface. See the - "<link linkend='wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</link>" - section for information on these plug-ins. + "<link linkend='wic-using-the-wic-plugin-interface'>Using the Wic PlugIn Interface</link>" + section for information on these plugins. </para> <para> This section provides some background information on Wic, describes what you need to have in place to run the tool, provides instruction on how to use - the Wic utility, provides information on using the Wic plug-ins + the Wic utility, provides information on using the Wic plugins interface, and provides several examples that show how to use Wic. </para> @@ -7393,7 +7649,6 @@ available Wic images as follows: <literallayout class='monospaced'> $ wic list images - mpc8315e-rdb Create SD card image for MPC8315E-RDB genericx86 Create an EFI disk image for genericx86* beaglebone-yocto Create SD card image for Beaglebone edgerouter Create SD card image for Edgerouter @@ -7581,7 +7836,6 @@ files: <literallayout class='monospaced'> $ wic list images - mpc8315e-rdb Create SD card image for MPC8315E-RDB genericx86 Create an EFI disk image for genericx86* beaglebone-yocto Create SD card image for Beaglebone edgerouter Create SD card image for Edgerouter @@ -7621,28 +7875,28 @@ </para> </section> - <section id='wic-using-the-wic-plug-ins-interface'> - <title>Using the Wic Plug-Ins Interface</title> + <section id='wic-using-the-wic-plugin-interface'> + <title>Using the Wic Plugin Interface</title> <para> You can extend and specialize Wic functionality by using - Wic plug-ins. - This section explains the Wic plug-in interface. + Wic plugins. + This section explains the Wic plugin interface. <note> - Wic plug-ins consist of "source" and "imager" plug-ins. - Imager plug-ins are beyond the scope of this section. + Wic plugins consist of "source" and "imager" plugins. + Imager plugins are beyond the scope of this section. </note> </para> <para> - Source plug-ins provide a mechanism to customize partition + Source plugins provide a mechanism to customize partition content during the Wic image generation process. - You can use source plug-ins to map values that you specify + You can use source plugins to map values that you specify using <filename>--source</filename> commands in kickstart - files (i.e. <filename>*.wks</filename>) to a plug-in + files (i.e. <filename>*.wks</filename>) to a plugin implementation used to populate a given partition. <note> - If you use plug-ins that have build-time dependencies + If you use plugins that have build-time dependencies (e.g. native tools, bootloaders, and so forth) when building a Wic image, you need to specify those dependencies using the @@ -7652,43 +7906,43 @@ </para> <para> - Source plug-ins are subclasses defined in plug-in files. - As shipped, the Yocto Project provides several plug-in + Source plugins are subclasses defined in plugin files. + As shipped, the Yocto Project provides several plugin files. - You can see the source plug-in files that ship with the + You can see the source plugin files that ship with the Yocto Project <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>. - Each of these plug-in files contains source plug-ins that + Each of these plugin files contains source plugins that are designed to populate a specific Wic image partition. </para> <para> - Source plug-ins are subclasses of the + Source plugins are subclasses of the <filename>SourcePlugin</filename> class, which is defined in the <filename>poky/scripts/lib/wic/pluginbase.py</filename> file. For example, the <filename>BootimgEFIPlugin</filename> - source plug-in found in the + source plugin found in the <filename>bootimg-efi.py</filename> file is a subclass of the <filename>SourcePlugin</filename> class, which is found in the <filename>pluginbase.py</filename> file. </para> <para> - You can also implement source plug-ins in a layer outside + You can also implement source plugins in a layer outside of the Source Repositories (external layer). - To do so, be sure that your plug-in files are located in + To do so, be sure that your plugin files are located in a directory whose path is <filename>scripts/lib/wic/plugins/source/</filename> within your external layer. - When the plug-in files are located there, the source - plug-ins they contain are made available to Wic. + When the plugin files are located there, the source + plugins they contain are made available to Wic. </para> <para> When the Wic implementation needs to invoke a - partition-specific implementation, it looks for the plug-in + partition-specific implementation, it looks for the plugin with the same name as the <filename>--source</filename> parameter used in the kickstart file given to that partition. @@ -7698,13 +7952,13 @@ part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 </literallayout> The methods defined as class members of the matching - source plug-in (i.e. <filename>bootimg-pcbios</filename>) - in the <filename>bootimg-pcbios.py</filename> plug-in file + source plugin (i.e. <filename>bootimg-pcbios</filename>) + in the <filename>bootimg-pcbios.py</filename> plugin file are used. </para> <para> - To be more concrete, here is the corresponding plug-in + To be more concrete, here is the corresponding plugin definition from the <filename>bootimg-pcbios.py</filename> file for the previous command along with an example method called by the Wic implementation when it needs to @@ -7736,19 +7990,19 @@ . . </literallayout> - If a subclass (plug-in) itself does not implement a + If a subclass (plugin) itself does not implement a particular function, Wic locates and uses the default version in the superclass. - It is for this reason that all source plug-ins are derived + It is for this reason that all source plugins are derived from the <filename>SourcePlugin</filename> class. </para> <para> The <filename>SourcePlugin</filename> class defined in the <filename>pluginbase.py</filename> file defines - a set of methods that source plug-ins can implement or + a set of methods that source plugins can implement or override. - Any plug-ins (subclass of + Any plugins (subclass of <filename>SourcePlugin</filename>) that do not implement a particular method inherit the implementation of the method from the <filename>SourcePlugin</filename> class. @@ -7809,11 +8063,11 @@ </para> <para> - You can extend the source plug-in mechanism. - To add more hooks, create more source plug-in methods + You can extend the source plugin mechanism. + To add more hooks, create more source plugin methods within <filename>SourcePlugin</filename> and the corresponding derived subclasses. - The code that calls the plug-in methods uses the + The code that calls the plugin methods uses the <filename>plugin.get_source_plugin_methods()</filename> function to find the method or methods needed by the call. Retrieval of those methods is accomplished by filling up @@ -8792,11 +9046,17 @@ <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> </para></listitem> <listitem><para> - <link linkend='using-runtime-package-management'>Using Runtime Package Management</link> + <link linkend='using-runtime-package-management'>Using runtime package management</link> + </para></listitem> + <listitem><para> + <link linkend='generating-and-using-signed-packages'>Generating and using signed packages</link> </para></listitem> <listitem><para> <link linkend='testing-packages-with-ptest'>Setting up and running package test (ptest)</link> </para></listitem> + <listitem><para> + <link linkend='creating-node-package-manager-npm-packages'>Creating node package manager (NPM) packages</link> + </para></listitem> </itemizedlist> </para> @@ -9233,7 +9493,7 @@ <para> Many pieces of software split functionality into optional - modules (or plug-ins) and the plug-ins that are built + modules (or plugins) and the plugins that are built might depend on configuration options. To avoid having to duplicate the logic that determines what modules are available in your recipe or to avoid having @@ -10225,6 +10485,282 @@ </para> </section> </section> + + <section id='creating-node-package-manager-npm-packages'> + <title>Creating Node Package Manager (NPM) Packages</title> + + <para> + <ulink url='https://en.wikipedia.org/wiki/Npm_(software)'>NPM</ulink> + is a package manager for the JavaScript programming + language. + The Yocto Project supports the NPM + <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetcher</ulink>. + You can use this fetcher in combination with + <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename></ulink> + to create recipes that produce NPM packages. + </para> + + <para> + Two workflows exist that allow you to create NPM packages + using <filename>devtool</filename>: the NPM registry modules + method and the NPM project code method. + <note> + While it is possible to create NPM recipes manually, + using <filename>devtool</filename> is far simpler. + </note> + Additionally, some requirements and caveats exist. + </para> + + <section id='npm-package-creation-requirements'> + <title>Requirements and Caveats</title> + + <para> + You need to be aware of the following before using + <filename>devtool</filename> to create NPM packages: + <itemizedlist> + <listitem><para> + Of the two methods that you can use + <filename>devtool</filename> to create NPM + packages, the registry approach is slightly + simpler. + However, you might consider the project + approach because you do not have to publish + your module in the NPM registry + (<ulink url='https://docs.npmjs.com/misc/registry'><filename>npm-registry</filename></ulink>), + which is NPM's public registry. + </para></listitem> + <listitem><para> + Be familiar with + <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename></ulink>. + </para></listitem> + <listitem><para> + The NPM host tools need the native + <filename>nodejs-npm</filename> package, which + is part of the OpenEmbedded environment. + You need to get the package by cloning the + <ulink url='https://github.com/openembedded/meta-openembedded'></ulink> + repository out of GitHub. + Be sure to add the path to your local copy to + your <filename>bblayers.conf</filename> file. + </para></listitem> + <listitem><para> + <filename>devtool</filename> cannot detect + native libraries in module dependencies. + Consequently, you must manually add packages + to your recipe. + </para></listitem> + <listitem><para> + While deploying NPM packages, + <filename>devtool</filename> cannot determine + which dependent packages are missing on the + target (e.g. the node runtime + <filename>nodejs</filename>). + Consequently, you need to find out what + files are missing and be sure they are on the + target. + </para></listitem> + <listitem><para> + Although you might not need NPM to run your + node package, it is useful to have NPM on your + target. + The NPM package name is + <filename>nodejs-npm</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='npm-using-the-registry-modules-method'> + <title>Using the Registry Modules Method</title> + + <para> + This section presents an example that uses the + <filename>cute-files</filename> module, which is a + file browser web application. + <note> + You must know the <filename>cute-files</filename> + module version. + </note> + </para> + + <para> + The first thing you need to do is use + <filename>devtool</filename> and the NPM fetcher to + create the recipe: + <literallayout class='monospaced'> + $ devtool add "npm://registry.npmjs.org;package=cute-files;version=1.0.2" + </literallayout> + The <filename>devtool add</filename> command runs + <filename>recipetool create</filename> and uses the + same fetch URI to download each dependency and capture + license details where possible. + The result is a generated recipe. + </para> + + <para> + The recipe file is fairly simple and contains every + license that <filename>recipetool</filename> finds + and includes the licenses in the recipe's + <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> + variables. + You need to examine the variables and look for those + with "unknown" in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> + field. + You need to track down the license information for + "unknown" modules and manually add the information to the + recipe. + </para> + + <para> + <filename>recipetool</filename> creates a "shrinkwrap" file + for your recipe. + Shrinkwrap files capture the version of all dependent + modules. + Many packages do not provide shrinkwrap files. + <filename>recipetool</filename> create a shrinkwrap + file as it runs. + <note> + A package is created for each sub-module. + This policy is the only practical way to have the + licenses for all of the dependencies represented + in the license manifest of the image. + </note> + </para> + + <para> + The <filename>devtool edit-recipe</filename> command + lets you take a look at the recipe: + <literallayout class='monospaced'> + $ devtool edit-recipe cute-files + SUMMARY = "Turn any folder on your computer into a cute file browser, available on the local network." + LICENSE = "MIT & ISC & Unknown" + LIC_FILES_CHKSUM = "file://LICENSE;md5=71d98c0a1db42956787b1909c74a86ca \ + file://node_modules/toidentifier/LICENSE;md5=1a261071a044d02eb6f2bb47f51a3502 \ + file://node_modules/debug/LICENSE;md5=ddd815a475e7338b0be7a14d8ee35a99 \ + ... + + SRC_URI = " \ + npm://registry.npmjs.org/;package=cute-files;version=${PV} \ + npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ + " + + S = "${WORKDIR}/npm" + + inherit npm + + LICENSE_${PN} = "MIT" + LICENSE_${PN}-accepts = "MIT" + LICENSE_${PN}-array-flatten = "MIT" + ... + LICENSE_${PN}-vary = "MIT" + </literallayout> + Three key points exist in the previous example: + <itemizedlist> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + uses the NPM scheme so that the NPM fetcher + is used. + </para></listitem> + <listitem><para> + <filename>recipetool</filename> collects all + the license information. + If a sub-module's license is unavailable, + the sub-module's name appears in the comments. + </para></listitem> + <listitem><para> + The <filename>inherit npm</filename> statement + causes the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-npm'><filename>npm</filename></ulink> + class to package up all the modules. + </para></listitem> + </itemizedlist> + </para> + + <para> + You can run the following command to build the + <filename>cute-files</filename> package: + <literallayout class='monospaced'> + $ devtool build cute-files + </literallayout> + Remember that <filename>nodejs</filename> must be + installed on the target before your package. + </para> + + <para> + Assuming 192.168.7.2 for the target's IP address, use + the following command to deploy your package: + <literallayout class='monospaced'> + $ devtool deploy-target -s cute-files root@192.168.7.2 + </literallayout> + Once the package is installed on the target, you can + test the application: + <note> + Because of a know issue, you cannot simply run + <filename>cute-files</filename> as you would if you + had run <filename>npm install</filename>. + </note> + <literallayout class='monospaced'> + $ cd /usr/lib/node_modules/cute-files + $ node cute-files.js + </literallayout> + On a browser, go to + <filename>http://192.168.7.2:3000</filename> and you + see the following: + <imagedata fileref="figures/cute-files-npm-example.png" align="center" width="6in" depth="4in" /> + </para> + + <para> + You can find the recipe in + <filename>workspace/recipes/cute-files</filename>. + You can use the recipe in any layer you choose. + </para> + </section> + + <section id='npm-using-the-npm-projects-method'> + <title>Using the NPM Projects Code Method</title> + + <para> + Although it is useful to package modules already in the + NPM registry, adding <filename>node.js</filename> projects + under development is a more common developer use case. + </para> + + <para> + This section covers the NPM projects code method, which is + very similar to the "registry" approach described in the + previous section. + In the NPM projects method, you provide + <filename>devtool</filename> with an URL that points to the + source files. + </para> + + <para> + Replicating the same example, (i.e. + <filename>cute-files</filename>) use the following command: + <literallayout class='monospaced'> + $ devtool add https://github.com/martinaglv/cute-files.git + </literallayout> + The recipe this command generates is very similar to the + recipe created in the previous section. + However, the <filename>SRC_URI</filename> looks like the + following: + <literallayout class='monospaced'> + SRC_URI = " \ + git://github.com/martinaglv/cute-files.git;protocol=https \ + npmsw://${THISDIR}/${BPN}/npm-shrinkwrap.json \ + " + </literallayout> + In this example, the main module is taken from the Git + repository and dependents are taken from the NPM registry. + Other than those differences, the recipe is basically the + same between the two methods. + You can build and deploy the package exactly as described + in the previous section that uses the registry modules + method. + </para> + </section> + </section> </section> <section id='efficiently-fetching-source-files-during-a-build'> @@ -10314,7 +10850,7 @@ Use the following BitBake command form to fetch all the necessary sources without starting the build: <literallayout class='monospaced'> - $ bitbake -c <replaceable>target</replaceable> runall="fetch" + $ bitbake <replaceable>target</replaceable> --runall=fetch </literallayout> This variation of the BitBake command guarantees that you have all the sources for that BitBake target should you @@ -10337,6 +10873,38 @@ </para> <para> + Within the system, SysVinit treats system components as services. + These services are maintained as shell scripts stored in the + <filename>/etc/init.d/</filename> directory. + Services organize into different run levels. + This organization is maintained by putting links to the services + in the <filename>/etc/rcN.d/</filename> directories, where + <replaceable>N/</replaceable> is one of the following options: + "S", "0", "1", "2", "3", "4", "5", or "6". + <note> + Each runlevel has a dependency on the previous runlevel. + This dependency allows the services to work properly. + </note> + </para> + + <para> + In comparison, systemd treats components as units. + Using units is a broader concept as compared to using a service. + A unit includes several different types of entities. + Service is one of the types of entities. + The runlevel concept in SysVinit corresponds to the concept of a + target in systemd, where target is also a type of supported unit. + </para> + + <para> + In a SysVinit-based system, services load sequentially (i.e. one + by one) during and parallelization is not supported. + With systemd, services start in parallel. + Needless to say, the method can have an impact on system startup + performance. + </para> + + <para> If you want to use SysVinit, you do not have to do anything. But, if you want to use systemd, you must @@ -10347,7 +10915,7 @@ <title>Using systemd Exclusively</title> <para> - Set the these variables in your distribution configuration + Set these variables in your distribution configuration file as follows: <literallayout class='monospaced'> DISTRO_FEATURES_append = " systemd" @@ -10615,18 +11183,18 @@ <para> To create the read-only root filesystem, simply add the - "read-only-rootfs" feature to your image. - Using either of the following statements in your - image recipe or from within the - <filename>local.conf</filename> file found in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> - causes the build system to create a read-only root filesystem: + "read-only-rootfs" feature to your image, normally in one of two ways. + The first way is to add the "read-only-rootfs" image feature + in the image's recipe file via the + <filename>IMAGE_FEATURES</filename> variable: <literallayout class='monospaced'> - IMAGE_FEATURES = "read-only-rootfs" + IMAGE_FEATURES += "read-only-rootfs" </literallayout> - or + As an alternative, you can add the same feature from within your + build directory's <filename>local.conf</filename> file with the + associated <filename>EXTRA_IMAGE_FEATURES</filename> variable, as in: <literallayout class='monospaced'> - EXTRA_IMAGE_FEATURES += "read-only-rootfs" + EXTRA_IMAGE_FEATURES = "read-only-rootfs" </literallayout> </para> @@ -11489,15 +12057,15 @@ In order to run tests on hardware, you need to set <filename>TEST_TARGET</filename> to an appropriate value. For QEMU, you do not have to change anything, the default - value is "QemuTarget". + value is "qemu". For running tests on hardware, the following options exist: <itemizedlist> - <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis> - Choose "SimpleRemoteTarget" if you are going to + <listitem><para><emphasis>"simpleremote":</emphasis> + Choose "simpleremote" if you are going to run tests on a target system that is already running the image to be tested and is available on the network. - You can use "SimpleRemoteTarget" in conjunction + You can use "simpleremote" in conjunction with either real hardware or an image running within a separately started QEMU or any other virtual machine manager. @@ -11672,7 +12240,7 @@ <title>Power Control</title> <para> - For most hardware targets other than SimpleRemoteTarget, + For most hardware targets other than "simpleremote", you can control power: <itemizedlist> <listitem><para> @@ -12069,7 +12637,7 @@ <listitem><para><emphasis><filename>target</filename>:</emphasis> The target controller object used to deploy and start an image on a particular target - (e.g. QemuTarget, SimpleRemote, and + (e.g. Qemu, SimpleRemote, and SystemdbootTarget). Tests usually use the following: <itemizedlist> @@ -12318,14 +12886,6 @@ </itemizedlist> </para> - <para> - For debugging information within the popular - <trademark class='trade'>Eclipse</trademark> IDE, see the - "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>" - section in the Yocto Project Application Development and the - Extensible Software Development Kit (eSDK) manual. - </para> - <section id='dev-debugging-viewing-logs-from-failed-tasks'> <title>Viewing Logs from Failed Tasks</title> @@ -12363,6 +12923,16 @@ <title>Viewing Variable Values</title> <para> + Sometimes you need to know the value of a variable as a + result of BitBake's parsing step. + This could be because some unexpected behavior occurred + in your project. + Perhaps an attempt to + <ulink url='&YOCTO_DOCS_BB_URL;#modifying-existing-variables'>modify a variable</ulink> + did not work out as expected. + </para> + + <para> BitBake's <filename>-e</filename> option is used to display variable values after parsing. The following command displays the variable values after the @@ -14888,12 +15458,12 @@ </para> <para> - Specifying audio and video plug-ins as part of the + Specifying audio and video plugins as part of the <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements (along with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the - plug-ins or components into built images, thus adding + plugins or components into built images, thus adding support for media formats or components. </para> </section> |