summaryrefslogtreecommitdiff
path: root/documentation/poky-ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual')
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml448
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml38
2 files changed, 221 insertions, 265 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index aedd7c1c6..763670e17 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -4,53 +4,50 @@
<chapter id='extendpoky'>
<title>Extending Poky</title>
-
<para>
- This section gives information about how to extend the functionality
- already present in Poky, documenting standard tasks such as adding new
- software packages, extending or customising images or porting poky to
- new hardware (adding a new machine). It also contains advice about how
- to manage the process of making changes to Poky to achieve best results.
+ This section provides information about how to extend the functionality
+ already present in Poky.
+ The section also documents standard tasks such as adding new
+ software packages, extending or customizing images or porting Poky to
+ new hardware (adding a new machine).
+ Finally, the section contains advice about how
+ to make changes to Poky to achieve the best results.
</para>
<section id='usingpoky-extend-addpkg'>
<title>Adding a Package</title>
-
<para>
- To add package into Poky you need to write a recipe for it.
- Writing a recipe means creating a .bb file which sets various
- variables. The variables
- useful for recipes are detailed in the <link linkend='ref-varlocality-recipe-required'>
- recipe reference</link> section along with more detailed information
- about issues such as recipe naming.
+ To add a package into Poky you need to write a recipe for it.
+ Writing a recipe means creating a <filename>.bb</filename> file that sets some
+ variables.
+ For information on variables that are useful for recipes and for information about recipe naming
+ issues, see <link linkend='ref-varlocality-recipe-required'>Recipe Variables - Required</link>
+ appendix.
</para>
-
<para>
Before writing a recipe from scratch it is often useful to check
- whether someone else has written one already. OpenEmbedded is a good place
- to look as it has a wider scope and hence a wider range of packages.
- Poky aims to be compatible with OpenEmbedded so most recipes should
+ whether someone else has written one already.
+ OpenEmbedded is a good place to look as it has a wider scope and range of packages.
+ Because Poky aims to be compatible with OpenEmbedded, most recipes should
just work in Poky.
</para>
-
<para>
For new packages, the simplest way to add a recipe is to base it on a similar
- pre-existing recipe. There are some examples below of how to add
- standard types of packages:
+ pre-existing recipe.
+ Following are some examples showing how to add standard types of packages:
</para>
<section id='usingpoky-extend-addpkg-singlec'>
<title>Single .c File Package (Hello World!)</title>
-
<para>
- To build an application from a single file stored locally (e.g. under "files/")
- requires a recipe which has the file listed in the <glossterm><link
- linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition
- the <function>do_compile</function> and <function>do_install</function>
- tasks need to be manually written. The <glossterm><link linkend='var-S'>
- S</link></glossterm> variable defines the directory containing the source
- code which in this case is set equal to <glossterm><link linkend='var-WORKDIR'>
- WORKDIR</link></glossterm>, the directory BitBake uses for the build.
+ Building an application from a single file that is stored locally (e.g. under
+ <filename>files/</filename>) requires a recipe that has the file listed in
+ the <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable.
+ Additionally, you need to manually write the <function>do_compile</function> and
+ <function>do_install</function> tasks.
+ The <glossterm><link linkend='var-S'>S</link></glossterm> variable defines the
+ directory containing the source code, which is set to <glossterm><link linkend='var-WORKDIR'>
+ WORKDIR</link></glossterm> in this case - the directory BitBake uses for the build.
</para>
<programlisting>
DESCRIPTION = "Simple helloworld application"
@@ -71,32 +68,28 @@ do_install() {
install -m 0755 helloworld ${D}${bindir}
}
</programlisting>
-
<para>
- As a result of the build process "helloworld", "helloworld-dbg" and "hellworld-dev"
- packages will be built by default. It is possible to<link linkend='usingpoky-extend-addpkg-files'>
- customise the packaging process</link>.
+ By default, the "helloworld", "helloworld-dbg" and "hellworld-dev"
+ packages are built.
+ For information on how to customize the packaging process, see
+ <link linkend='usingpoky-extend-addpkg-files'>Controlling Package Content</link>.
</para>
</section>
<section id='usingpoky-extend-addpkg-autotools'>
<title>Autotooled Package</title>
-
<para>
- Applications which use autotools (autoconf, automake)
- require a recipe which has a source archive listed in
- <glossterm><link
- linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
- <command>inherit autotools</command> to instruct BitBake to use the
- <filename>autotools.bbclass</filename> which has
- definitions of all the steps
+ Applications that use autotools such as <filename>autoconf</filename> and
+ <filename>automake</filename> require a recipe that has a source archive listed in
+ <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
+ <filename>also inherits autotools</filename>, which instructs BitBake to use the
+ <filename>autotools.bbclass</filename> containing the definitions of all the steps
needed to build an autotooled application.
- The result of the build will be automatically packaged and if
- the application uses NLS to localise then packages with
- locale information will be generated (one package per
- language). Below is one example (hello_2.2.bb)
+ The result of the build is automatically packaged.
+ And, if the application uses NLS for localization, packages with local information are
+ generated (one package per language).
+ Following is one example (<filename>hello_2.2.bb</filename>)
</para>
-
<programlisting>
DESCRIPTION = "GNU Helloworld application"
SECTION = "examples"
@@ -108,50 +101,40 @@ SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
inherit autotools gettext
</programlisting>
-
<para>
- <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
- </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
- track source license change</link>. Autotool based recipe can be quickly
- created this way like above example.
+ <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
+ </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
+ track source license change</link>.
+ You can quickly create autotool-based recipes in a manner similar to the previous example.
</para>
</section>
-
<section id='usingpoky-extend-addpkg-makefile'>
<title>Makefile-Based Package</title>
-
<para>
- Applications which use GNU make require a recipe which has
- the source archive listed in <glossterm><link
- linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
- Adding a <function>do_compile</function> step
- is not needed as by default BitBake will start the "make"
- command to compile the application. If there is a need for
- additional options to make then they should be stored in the
- <glossterm><link
- linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable - BitBake
- will pass them into the GNU
- make invocation. A <function>do_install</function> task is required
- - otherwise BitBake will run an empty <function>do_install</function>
- task by default.
+ Applications that use GNU <filename>make</filename> also require a recipe that has
+ the source archive listed in <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
+ You do not need to add a <function>do_compile</function> step since by default BitBake
+ starts the <filename>make</filename> command to compile the application.
+ If you need additional <filename>make</filename> options you should store them in the
+ <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable.
+ Bitbake passes these options into the <filename>make</filename> GNU invocation.
+ Note that a <function>do_install</function> task is still required.
+ Otherwise BitBake runs an empty <function>do_install</function> task by default.
</para>
-
<para>
- Some applications may require extra parameters to be passed to
- the compiler, for example an additional header path. This can
- be done buy adding to the <glossterm><link
- linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below:
+ Some applications might require extra parameters to be passed to the compiler.
+ For example the application might need an additional header path.
+ You can accomplish this by adding to the <glossterm><link linkend='var-CFLAGS'>CFLAGS</link>
+ </glossterm> variable.
+ The following example shows this:
</para>
-
<programlisting>
CFLAGS_prepend = "-I ${S}/include "
</programlisting>
-
<para>
- mtd-utils is an example as Makefile-based:
+ In the following example <filename>mtd-utils</filename> is a Makefile-based package:
</para>
-
<programlisting>
DESCRIPTION = "Tools for managing memory technology devices."
SECTION = "base"
@@ -177,25 +160,19 @@ do_install () {
</programlisting>
</section>
-
<section id='usingpoky-extend-addpkg-files'>
- <title>Controlling packages content</title>
-
+ <title>Controlling Package Content</title>
<para>
- The variables <glossterm><link
- linkend='var-PACKAGES'>PACKAGES</link></glossterm> and
- <glossterm><link linkend='var-FILES'>FILES</link></glossterm> are used to split an
- application into multiple packages.
+ You can use the variables <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm> and
+ <glossterm><link linkend='var-FILES'>FILES</link></glossterm> to split an application into
+ multiple packages.
</para>
-
<para>
- Below the "libXpm" recipe (libxpm_3.5.7.bb) is used as an example. By
- default the "libXpm" recipe generates one package
- which contains the library
- and also a few binaries. The recipe can be adapted to
- split the binaries into separate packages.
+ Following is an example that uses the "libXpm" recipe (<filename>libxpm_3.5.7.bb</filename>).
+ By default, the "libXpm" recipe generates a single package containing the library, along
+ with a few binaries.
+ You can modify the recipe to split the binaries into separate packages:
</para>
-
<programlisting>
require xorg-lib-common.inc
@@ -211,20 +188,19 @@ PACKAGES =+ "sxpm cxpm"
FILES_cxpm = "${bindir}/cxpm"
FILES_sxpm = "${bindir}/sxpm"
</programlisting>
-
<para>
- In this example we want to ship the "sxpm" and "cxpm" binaries
- in separate packages. Since "bindir" would be packaged into the
- main <glossterm><link linkend='var-PN'>PN</link></glossterm>
- package as standard we prepend the <glossterm><link
- linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so
- additional package names are added to the start of list. The
- extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_*
- variables then contain information to specify which files and
- directories goes into which package. Files included by earlier
- package are skipped by latter packages, and thus main <glossterm>
- <link linkend='var-PN'>PN</link></glossterm> will not include
- above listed files
+ In the previous example we want to ship the "sxpm" and "cxpm" binaries
+ in separate packages.
+ Since "bindir" would be packaged into the main
+ <glossterm><link linkend='var-PN'>PN</link></glossterm>
+ package by default, we prepend the <glossterm><link linkend='var-PACKAGES'>PACKAGES</link>
+ </glossterm> variable so additional package names are added to the start of list.
+ This results in the extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_*
+ variables then containing information defining which files and
+ directories go into which package.
+ Files included by earlier packages are skipped by latter packages.
+ Thus, the main <glossterm><link linkend='var-PN'>PN</link></glossterm> package does not include
+ the above listed files.
</para>
</section>
@@ -232,14 +208,13 @@ FILES_sxpm = "${bindir}/sxpm"
<title>Post Install Scripts</title>
<para>
- To add a post-installation script to a package, add
- a <function>pkg_postinst_PACKAGENAME()</function>
- function to the .bb file
- where PACKAGENAME is the name of the package to attach
- the postinst script to. Normally <glossterm><link
- linkend='var-PN'>PN</link></glossterm> can be used which expands
- to PACKAGENAME automatically. A post-installation function has the
- following structure:
+ To add a post-installation script to a package, add a <function>pkg_postinst_PACKAGENAME()
+ </function> function to the <filename>.bb</filename> file and use
+ <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
+ <filename>postinst</filename> script.
+ Normally <glossterm><link linkend='var-PN'>PN</link></glossterm> can be used, which
+ automatically expands to PACKAGENAME.
+ A post-installation function has the following structure:
</para>
<programlisting>
pkg_postinst_PACKAGENAME () {
@@ -248,21 +223,18 @@ pkg_postinst_PACKAGENAME () {
}
</programlisting>
<para>
- The script defined in the post installation function
- gets called when the rootfs is made. If the script succeeds,
- the package is marked as installed. If the script fails,
- the package is marked as unpacked and the script will be
- executed again on the first boot of the image.
+ The script defined in the post-installation function is called when the rootfs is made.
+ If the script succeeds, the package is marked as installed.
+ If the script fails, the package is marked as unpacked and the script is
+ executed when the image boots again.
</para>
-
<para>
- Sometimes it is necessary that the execution of a post-installation
- script is delayed until the first boot, because the script
- needs to be executed on the device itself. To delay script execution
- until boot time, the post-installation function should have the
- following structure:
+ Sometimes it is necessary for the execution of a post-installation
+ script to be delayed until the first boot.
+ For example, the script might need to be executed on the device itself.
+ To delay script execution until boot time, use the following structure for the
+ post-installation script:
</para>
-
<programlisting>
pkg_postinst_PACKAGENAME () {
#!/bin/sh -e
@@ -273,83 +245,69 @@ else
fi
}
</programlisting>
-
<para>
- The structure above delays execution until first boot
- because the <glossterm><link
- linkend='var-D'>D</link></glossterm> variable points
- to the 'image'
- directory when the rootfs is being made at build time but
+ The previous example delays execution until the image boots again because the
+ <glossterm><link linkend='var-D'>D</link></glossterm> variable points
+ to the 'image' directory when the rootfs is being made at build time but
is unset when executed on the first boot.
</para>
</section>
-
</section>
<section id='usingpoky-extend-customimage'>
<title>Customising Images</title>
-
<para>
- Poky images can be customised to satisfy
- particular requirements. Several methods are detailed below
- along with guidelines of when to use them.
+ You can customize Poky images to satisfy particular requirements.
+ This section describes several methods and provides guidelines for each.
</para>
<section id='usingpoky-extend-customimage-custombb'>
- <title>Customising Images through a custom image .bb files</title>
-
+ <title>Customising Images Using Custom .bb Files</title>
<para>
- One way to get additional software into an image is by creating a
- custom image. The recipe will contain two lines:
+ One way to get additional software into an image is to create a custom image.
+ The following example shows the form for the two lines you need:
</para>
-
<programlisting>
IMAGE_INSTALL = "task-poky-x11-base package1 package2"
inherit poky-image
</programlisting>
-
<para>
By creating a custom image, a developer has total control
- over the contents of the image. It is important to use
- the correct names of packages in the <glossterm><link
- linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable.
- The names must be in
- the OpenEmbedded notation instead of Debian notation, for example
- "glibc-dev" instead of "libc6-dev" etc.
+ over the contents of the image.
+ It is important to use the correct names of packages in the
+ <glossterm><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable.
+ You must use the OpenEmbedded notation and not the Debian notation for the names
+ (e.g. "glibc-dev" instead of "libc6-dev").
</para>
-
<para>
- The other method of creating a new image is by modifying
- an existing image. For example if a developer wants to add
- "strace" into "poky-image-sato" the following recipe can
- be used:
+ The other method for creating a custom image is to modify an existing image.
+ For example, if a developer wants to add "strace" into "poky-image-sato", they can use
+ the following recipe:
</para>
-
<programlisting>
require poky-image-sato.bb
IMAGE_INSTALL += "strace"
</programlisting>
-
</section>
<section id='usingpoky-extend-customimage-customtasks'>
- <title>Customising Images through custom tasks</title>
-
- <para>
- For complex custom images, the best approach is to create a custom
- task package which is then used to build the image (or images). A good
- example of a tasks package is <filename>meta/packages/tasks/task-poky.bb
- </filename>. The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm>
- variable lists the task packages to build (along with the complementary
- -dbg and -dev packages). For each package added,
- <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm> and
- <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm>
- entries can then be added each containing a list of packages the parent
- task package should contain. An example would be:
+ <title>Customising Images Using Custom Tasks</title>
+ <para>
+ For complex custom images, the best approach is to create a custom task package
+ that is used to build the image or images.
+ A good example of a tasks package is <filename>meta/recipes-sato/tasks/task-poky.bb
+ </filename>.
+ The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm>
+ variable lists the task packages to build along with the complementary
+ -dbg and -dev packages.
+ For each package added, you can use
+ <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm>
+ and <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm>
+ entries to provide a list of packages the parent task package should contain.
+ Following is an example:
</para>
-
<para>
<programlisting>
DESCRIPTION = "My Custom Tasks"
@@ -378,11 +336,11 @@ RRECOMMENDS_task-custom-tools = "\
kernel-module-oprofile"
</programlisting>
</para>
-
<para>
- In this example, two task packages are created, task-custom-apps and
- task-custom-tools with the dependencies and recommended package dependencies
- listed. To build an image using these task packages, you would then add
+ In the previous example, two task packages are created with their dependencies and their
+ recommended package dependencies listed: <filename>task-custom-apps</filename>, and
+ <filename>task-custom-tools</filename>.
+ To build an image using these task packages, you need to add
"task-custom-apps" and/or "task-custom-tools" to <glossterm><link
linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms
of image dependencies as described in other areas of this section.
@@ -390,131 +348,133 @@ RRECOMMENDS_task-custom-tools = "\
</section>
<section id='usingpoky-extend-customimage-imagefeatures'>
- <title>Customising Images through custom <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
-
+ <title>Customising Images Using Custom <glossterm>
+ <link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
<para>
- Ultimately users may want to add extra image "features" as used by Poky with the
+ Ultimately users might want to add extra image "features" as used by Poky with the
<glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
- variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename>
- which illustrates how poky achieves this. In summary, the file looks at the contents of the
+ variable.
+ To create these features, the best reference is
+ <filename>meta/classes/poky-image.bbclass</filename>, which shows how poky achieves this.
+ In summary, the file looks at the contents of the
<glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
- variable and then maps this into a set of tasks or packages. Based on this then the
- <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link></glossterm>
- variable is generated automatically. Extra features can be added by
- extending the class or creating a custom class for use with specialised image .bb files.
+ variable and then maps them into a set of tasks or packages.
+ Based on this information the <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link>
+ </glossterm> variable is generated automatically.
+ Users can add extra features by extending the class or creating a custom class for use
+ with specialized image <filename>.bb</filename> files.
</para>
</section>
<section id='usingpoky-extend-customimage-localconf'>
- <title>Customising Images through local.conf</title>
-
+ <title>Customising Images Using local.conf</title>
<para>
- It is possible to customise image contents by abusing
- variables used by distribution maintainers in local.conf.
- This method only allows the addition of packages and
- is not recommended.
+ It is possible to customise image contents by abusing variables used by distribution
+ maintainers in local.conf.
+ This method only allows the addition of packages and is not recommended.
</para>
-
<para>
- To add an "strace" package into the image the following is
- added to local.conf:
+ For example, to add the "strace" package into the image the you would add this to the
+ <filename>local.conf</filename> file:
</para>
-
<programlisting>
DISTRO_EXTRA_RDEPENDS += "strace"
</programlisting>
-
<para>
However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for
- distribution maintainers this method does not make
- adding packages as simple as a custom .bb file. Using
- this method, a few packages will need to be recreated if they have been
- created before and then the image is rebuilt.
+ distribution maintainers, adding packages using this method is not as simple as adding
+ them using a custom <filename>.bb</filename> file.
+ Using the <filename>local.conf</filename> file method could result in some packages
+ requiring recreation.
+ For example, if packages were previously created and the image was rebuilt then the packages
+ would need to be recreated.
</para>
- <programlisting>
-bitbake -c clean task-boot task-base task-poky
-bitbake poky-image-sato
- </programlisting>
-
<para>
Cleaning task-* packages is required because they use the
<glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
- DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to
- build them by hand as Poky images depend on the packages they contain so
- dependencies will be built automatically when building the image. For this reason we don't use the
- "rebuild" task in this case since "rebuild" does not care about
+ DISTRO_EXTRA_RDEPENDS</link></glossterm> variable.
+ You do not have to build them by hand because Poky images depend on the packages they contain.
+ This means dependencies are automatically built when the image builds.
+ For this reason we don't use the "rebuild" task.
+ In this case the "rebuild" task does does not care about
dependencies - it only rebuilds the specified package.
</para>
-
+ <programlisting>
+bitbake -c clean task-boot task-base task-poky
+bitbake poky-image-sato
+ </programlisting>
</section>
</section>
<section id="platdev-newmachine">
- <title>Porting Poky to a new machine</title>
+ <title>Porting Poky to a New Machine</title>
<para>
- Adding a new machine to Poky is a straightforward process and
- this section gives an idea of the changes that are needed. This guide is
- meant to cover adding machines similar to those Poky already supports.
- Adding a totally new architecture might require gcc/glibc changes as
- well as updates to the site information and, whilst well within Poky's
- capabilities, is outside the scope of this section.
+ Adding a new machine to Poky is a straightforward process.
+ This section provides information that gives you an idea of the changes you must make.
+ The information covers adding machines similar to those Poky already supports.
+ Although well within the capabilities of Poky, adding a totally new architecture might require
+ changes to <filename>gcc/glibc</filename> and to the site information.
+ Consequently, the information is beyond the scope of this manual.
</para>
<section id="platdev-newmachine-conffile">
- <title>Adding the machine configuration file</title>
+ <title>Adding the Machine Configuration File</title>
<para>
- A .conf file needs to be added to conf/machine/ with details of the
- device being added. The name of the file determines the name Poky will
- use to reference this machine.
+ To add a machine configuration you need to add a <filename>.conf</filename> file
+ with details of the device being added to <filename>conf/machine/</filename>.
+ The name of the file determines the name Poky uses to reference the new machine.
</para>
-
<para>
The most important variables to set in this file are <glossterm>
<link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm>
(e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'>
PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and
<glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES
- </link></glossterm> (e.g. "kernel26 apm screen wifi"). Other variables
- like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
+ </link></glossterm> (e.g. "kernel26 apm screen wifi").
+ You might also need other variables like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
</link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
<link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
</glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
- IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be
- needed. Full details on what these variables do and the meaning of
- their contents is available through the links. There're lots of existing
- machine .conf files which can be easily leveraged from meta/conf/machine/.
+ IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2").
+ You can find full details on these variables in the reference section.
+ You can leverage many existing machine <filename>.conf</filename> files from
+ <filename>meta/conf/machine/</filename>.
</para>
</section>
<section id="platdev-newmachine-kernel">
- <title>Adding a kernel for the machine</title>
+ <title>Adding a Kernel for the Machine</title>
<para>
- Poky needs to be able to build a kernel for the machine. You need
- to either create a new kernel recipe for this machine or extend an
- existing recipe. There are plenty of kernel examples in the
- meta/recipes-kernel/linux directory which can be used as references.
+ Poky needs to be able to build a kernel for the machine.
+ You need to either create a new kernel recipe for this machine, or extend an
+ existing recipe.
+ You can find several kernel examples in the <filename>meta/recipes-kernel/linux</filename>
+ directory that can be used as references.
</para>
<para>
- If creating a new recipe the "normal" recipe writing rules apply
- for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI
- </link></glossterm> including any patches and setting <glossterm>
- <link linkend='var-S'>S</link></glossterm> to point at the source
- code. You will need to create a configure task which configures the
- unpacked kernel with a defconfig be that through a "make defconfig"
- command or more usually though copying in a suitable defconfig and
- running "make oldconfig". By making use of "inherit kernel" and also
- maybe some of the linux-*.inc files, most other functionality is
- centralised and the the defaults of the class normally work well.
+ If you are creating a new recipe, the "normal" recipe-writing rules apply for setting
+ up a <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
+ This means specifying any necessary patches and setting <glossterm>
+ <link linkend='var-S'>S</link></glossterm> to point at the source code.
+ You need to create a "configure" task that configures the unpacked kernel with a defconfig.
+ You can do this by using a <filename>make defconfig</filename> command or
+ more commonly by copying in a suitable defconfig and and then running
+ <filename>make oldconfig</filename>.
+ By making use of "inherit kernel" and potentially some of the
+ <filename>linux-*.inc</filename> files, most other functionality is
+ centralized and the the defaults of the class normally work well.
</para>
<para>
- If extending an existing kernel it is usually a case of adding a
- suitable defconfig file in a location similar to that used by other
- machine's defconfig files in a given kernel, possibly listing it in
- the SRC_URI and adding the machine to the expression in <glossterm>
- <link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link>
- </glossterm>:
+ If you are extending an existing kernel, it is usually a matter of adding a
+ suitable <filename>defconfig</filename> file.
+ The file needs to be added into a location similar to <filename>defconfig</filename> files
+ used for other machines in a given kernel.
+ A possible way to do this is by listing the file in the
+ <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>
+ and adding the machine to the expression in
+ <glossterm><link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link></glossterm>:
</para>
<programlisting>
COMPATIBLE_MACHINE = '(qemux86|qemumips)'
@@ -522,7 +482,7 @@ COMPATIBLE_MACHINE = '(qemux86|qemumips)'
</section>
<section id="platdev-newmachine-formfactor">
- <title>Adding a formfactor configuration file</title>
+ <title>Adding a Formfactor Configuration File</title>
<para>
A formfactor configuration file provides information about the
target hardware on which Poky is running, and that Poky cannot
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index c2e102ce3..4f75e1a27 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -205,7 +205,7 @@ $ bitbake &lt;target&gt;
</section>
<section id='usingpoky-debugging-taskrunning'>
- <title>Running specific tasks</title>
+ <title>Running Specific Tasks</title>
<para> Any given package consists of a set of tasks.
In most cases the series is: fetch, unpack, patch, configure,
@@ -287,24 +287,20 @@ $ bitbake matchbox-desktop -c
</section>
<section id='usingpoky-debugging-buildfile'>
- <title>Building with no dependencies</title>
-
+ <title>Building with No Dependencies</title>
<para>
- If you really want to build a specific .bb file, you can use
- the form <command>bitbake -b somepath/somefile.bb</command>. Note that this
- will not check the dependencies so this option should only
- be used when you know its dependencies already exist. You
- can specify fragments of the filename and bitbake will see
- if it can find a unique match.
+ If you really want to build a specific <filename>.bb</filename> file, you can use
+ the command form <filename>bitbake -b somepath/somefile.bb</filename>.
+ This command form does not check for dependencies so you should use it
+ only when you know its dependencies already exist.
+ You can also specify fragments of the filename and bitbake checks for a unique match.
</para>
-
</section>
<section id='usingpoky-debugging-variables'>
<title>Variables</title>
-
<para>
- The "-e" option will dump the resulting environment for
+ The "-e" option dumps the resulting environment for
either the configuration (no package specified) or for a
specific package when specified with the "-b" option.
</para>
@@ -312,23 +308,23 @@ $ bitbake matchbox-desktop -c
<section id='usingpoky-debugging-others'>
<title>Other Tips</title>
-
<tip>
- <para>When adding new packages it is worth keeping an eye open for bad
- things creeping into compiler commandlines such as references to local
- system files (<filename>/usr/lib/</filename> or <filename>/usr/include/</filename> etc.).
+ <para>
+ When adding new packages it is worth watching for undesireable items making their way
+ into compiler command lines.
+ For example, you do not want references to local system files like
+ <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
</para>
</tip>
-
<tip>
<para>
If you want to remove the psplash boot splashscreen, add "psplash=false"
- to the kernel commandline and psplash won't load allowing you to see
- the console. It's also possible to switch out of the splashscreen by
- switching virtual console (Fn+Left or Fn+Right on a Zaurus).
+ to the kernel command line.
+ Doing so prevents psplash from loading thus allowing you to see the console.
+ It is also possible to switch out of the splashscreen by
+ switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
</para>
</tip>
-
</section>
</section>