diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 7b4d638dfa..1f49cb24f4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3064,7 +3064,7 @@
Handling optional module packaging
- Setting up Runtime Package Management
+ Using Runtime Package Management
Setting up and running package test
(ptest)
@@ -3605,161 +3605,208 @@
-
- Runtime Package Management
+
+ Using Runtime Package Management
+
- Regardless of anything else, during a build bitbake will
- transform a recipe into one or more packages. For example,
- the bash recipe currently produces the
- following packages: bash-dbg bash-staticdev bash-dev
- bash-doc bash-locale bash. Not all generated
- packages will be included in an image.
-
- In several situations you might want to have the ability to
- update, add, remove, query, etc the packages on a target
- device at runtime (i.e. without having to generate a new
- image). Examples of such situations include:
+ During a build, BitBake always transforms a recipe into one or
+ more packages.
+ For example, BitBake takes the bash recipe
+ and currently produces the bash-dbg,
+ bash-staticdev,
+ bash-dev, bash-doc,
+ bash-locale, and
+ bash packages.
+ Not all generated packages are included in an image.
+
+
+
+ In several situations, you might need to update, add, remove,
+ or query the packages on a target device at runtime
+ (i.e. without having to generate a new image).
+ Examples of such situations include:
You want to provide in-the-field updates to deployed
- devices (e.g. for security updates).
-
+ devices (e.g. security updates).
+
You want to have a fast turn-around development cycle
- for one or more applications which run on your device.
-
+ for one or more applications that run on your device.
+
You want to temporarily install the "debug" packages
of various applications on your device so that
- debugging can be greatly improved (access to symbols,
- source debugging, etc).
-
+ debugging can be greatly improved by allowing
+ access to symbols and source debugging.
+
You want to deploy a more minimal package selection of
your device but allow in-the-field updates to add a
larger selection for customization.
-
+
-
- In all these situations you have something similar to a more
+
+
+
+ In all these situations, you have something similar to a more
traditional Linux distribution in that in-field devices
- are able to grab pre-compiled packages from a server for
- installation/update. This is what is termed "runtime package
- management". In order to use runtime package management you
- need a host/server machine which serves up the pre-compiled
- packages plus the required meta data, and you need package
- manipulation tools on the target. Note that the build machine
- is a likely candidate to act as the server, but the build
- machine doesn't necessarily have to be the package server;
- the build machine could push its artifacts to another (e.g.
- Internet-facing) machine which acts as the server.
-
- A simple build which targets just one device will produce
- more than one package database. In other words, the packages
- produced by a build will be separated out into a couple of
- different package groupings based on criteria such as the
- target's CPU architecture, the target board, or the C library
- used on the target. For example, a build targetting the
- qemuarm device will produce the following
- 3 package databases: all,
- armv5te, and
- qemuarm. If I wanted my
- qemuarm device to be aware of all the
- packages which were available to it, I would need to point it
- to each of these databases individually. In a similar way, a
- traditional Linux distribution usually is configured to be
- aware of a number of software repositories from which it
- will retrieve packages.
-
+ are able to receive pre-compiled packages from a server for
+ installation or update.
+ Being able to install these packages on a running,
+ in-field device is what is termed "runtime package
+ management".
+
+
+
+ In order to use runtime package management, you
+ need a host/server machine that serves up the pre-compiled
+ packages plus the required metadata.
+ You also need package manipulation tools on the target.
+ The build machine is a likely candidate to act as the server.
+ However, that machine does not necessarily have to be the
+ package server.
+ The build machine could push its artifacts to another machine
+ that acts as the server (e.g. Internet-facing).
+
+
+
+ A simple build that targets just one device produces
+ more than one package database.
+ In other words, the packages produced by a build are separated
+ out into a couple of different package groupings based on
+ criteria such as the target's CPU architecture, the target
+ board, or the C library used on the target.
+ For example, a build targeting the qemuarm
+ device produces the following three package databases:
+ all, armv5te, and
+ qemuarm.
+ If you wanted your qemuarm device to be
+ aware of all the packages that were available to it,
+ you would need to point it to each of these databases
+ individually.
+ In a similar way, a traditional Linux distribution usually is
+ configured to be aware of a number of software repositories
+ from which it retrieves packages.
+
+
+
Using runtime package management is completely optional and
- not required for a successful build or deployment in any way.
- But if you want to make use of runtime package management
- you'll need to do a couple things above and beyond the basics.
-
+ not required for a successful build or deployment in any
+ way.
+ But if you want to make use of runtime package management,
+ you need to do a couple things above and beyond the basics.
+ The remainder of this section describes what you need to do.
+
Build Considerations
+
- In order to provide support for runtime package management
- there are some build considerations of which to be aware.
-
- When bitbake generates packages it needs to know in
- which format(s) you want the packages to be generated.
- In your configuration this is handled by the
+ This section describes build considerations that you need
+ to be aware of in order to provide support for runtime
+ package management.
+
+
+
+ When BitBake generates packages it needs to know
+ what format(s) to use.
+ In your configuration, you use the
PACKAGE_CLASSES
- variable. Note that you can choose to have more than one,
- but at least one is required.
-
+ variable to specify the format.
+
+ You can choose to have more than one format but you must
+ provide at least one.
+
+
+
+
If you would like your image to start off with a basic
package database of the packages in your current build
- as well as having the relevant tools available on the
+ as well as have the relevant tools available on the
target for runtime package management, you can include
"package-management" in the
IMAGE_FEATURES
- variable. Including "package-management" in this
+ variable.
+ Including "package-management" in this
configuration variable ensures that when the image
- is assembled for your target it will include
+ is assembled for your target, the image includes
the currently-known package databases as well as
the target-specific tools required for runtime
package management to be performed on the target.
- Note, however, this isn't strictly necessary.
+ However, this is not strictly necessary.
You could start your image off without any databases
but only include the required on-target package
- tool(s) (for example you would include "opkg" in your
+ tool(s).
+ As an example, you could include "opkg" in your
IMAGE_INSTALL
- variable if you are using the IPK package format). You can
- then initialize your target's package database(s) later,
- once your image is up and running.
-
- Whenever you perform any sort of build step which can
+ variable if you are using the IPK package format.
+ You can then initialize your target's package database(s)
+ later once your image is up and running.
+
+
+
+ Whenever you perform any sort of build step that can
potentially generate a package or modify an existing
package, it is always a good idea to re-generate the
package index with:
$ bitbake package-index
- Note that it is not sufficient to simply do:
+ Realize that it is not sufficient to simply do the
+ following:
$ bitbake <some-package> package-index
- since bitbake won't properly schedule the
+ This is because BitBake does not properly schedule the
package-index target fully after any
- other target has completed. Therefore, be sure to run the
- package update step separately.
-
+ other target has completed.
+ Thus, be sure to run the package update step separately.
+
+
+
As described below in the
- Using IPK
+ "Using IPK"
section, if you are using IPK as your package format, you
can make use of the
distro-feed-configs recipe provided
by meta-oe in order to configure your
target to use your IPK databases.
-
- When your build is complete your packages will show up in
- the
+
+
+
+ When your build is complete, your packages reside in the
${TMPDIR}/deploy/<package-format>
- directory. For example, if ${TMPDIR}
+ directory.
+ For example, if ${TMPDIR}
is tmp and your selected package type
- is IPK, then your IPK packages will be available in
+ is IPK, then your IPK packages are available in
tmp/deploy/ipk.
Host or Server Machine Setup
+
- Typically packages are served from a server via HTTP, but
- other protocols are possible. If we assume you want to
- use HTTP, then you would need to setup and configure a
+ Typically, packages are served from a server using
+ HTTP.
+ However, other protocols are possible.
+ If you want to use HTTP, then setup and configure a
web server, such as Apache 2 or lighttpd, on the machine
- serving the packages. As mentioned above, the build
- machine can act as the package server; in the following
- server machine setups it is assumed the build machine is
- also the server.
+ serving the packages.
+
+
+
+ As previously mentioned, the build machine can act as the
+ package server.
+ In the following sections that describe server machine
+ setups, the build machine is assumed to also be the server.
Serving Packages via Apache 2
+
This example assumes you are using the Apache 2
server:
@@ -3769,14 +3816,14 @@
configuration, which you can find at
/etc/httpd/conf/httpd.conf.
Use commands similar to these on the
- development system. These example
- commands assume a top-level
+ development system.
+ These example commands assume a top-level
Source Directory
named poky in your home
- directory. The example also assumes an RPM
- package type. If you are using a different
- package type, such as IPK, use "ipk" in the
- pathnames:
+ directory.
+ The example also assumes an RPM package type.
+ If you are using a different package type, such
+ as IPK, use "ipk" in the pathnames:
<VirtualHost *:80>
....
@@ -3785,68 +3832,75 @@
Options +Indexes
</Directory>
</VirtualHost>
-
-
+
- Reload the Apache configuration as follows.
+ Reload the Apache configuration as described
+ in this step.
For all commands, be sure you have root
privileges.
-
+
+
+
If your development system is using Fedora or
CentOS, use the following:
- # service httpd reload
+ $ service httpd reload
For Ubuntu and Debian, use the following:
- # /etc/init.d/apache2 reload
+ $ /etc/init.d/apache2 reload
For OpenSUSE, use the following:
- # /etc/init.d/apache2 reload
-
-
+ $ /etc/init.d/apache2 reload
+
If you are using Security-Enhanced Linux
(SELinux), you need to label the files as
- being accessible through Apache. Use the
- following command from the development host
- (this example assumes RPM package types):
+ being accessible through Apache.
+ Use the following command from the development
+ host.
+ This example assumes RPM package types:
- # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
-
-
+ $ chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
+
Serving Packages via lighttpd
+
- If you are using lighttpd all you need
+ If you are using lighttpd, all you need
to do is to provide a link from your
- ${TMPDIR}/deploy/<package-format> directory to
- lighttpd's document-root. You can determine the
- specifics of your lighttpd installation by looking
- through its configuration file which is usually found
- at: /etc/lighttpd/lighttpd.conf.
-
- For example, if you are using IPK, if
- lighttpd's document-root is set to
- /var/www/lighttpd, and if you had
- packages for a target named "BOARD"
+ ${TMPDIR}/deploy/<package-format>
+ directory to lighttpd's document-root.
+ You can determine the specifics of your lighttpd
+ installation by looking through its configuration file,
+ which is usually found at:
+ /etc/lighttpd/lighttpd.conf.
+
+
+
+ For example, if you are using IPK, lighttpd's
+ document-root is set to
+ /var/www/lighttpd, and you had
+ packages for a target named "BOARD",
then you might create a link from your build location
to lighttpd's document-root as follows:
- # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
+ $ ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
-
- At this point you need to start the lighttpd server.
- The way in which you start the server will vary by
- distribution, but one basic way to start it by hand
- would be:
+
+
+
+ At this point, you need to start the lighttpd server.
+ The method used to start the server varies by
+ distribution.
+ However, one basic method that starts it by hand is:
- # lighttpd -f /etc/lighttpd/lighttpd.conf
+ $ lighttpd -f /etc/lighttpd/lighttpd.conf
@@ -3855,30 +3909,41 @@
Target Setup
+
+ Setting up the target differs depending on the
+ package management system.
+ This section provides information for RPM and IPK.
+
+
Using RPM
+
The application for performing runtime package
management of RPM packages on the target is called
smart.
-
+
+
+
On the target machine, you need to inform
smart of every package database
- you wish to use. As an example, suppose your target
- device can use the following 3 package databases from
- a server named server.name:
+ you want to use.
+ As an example, suppose your target device can use the
+ following three package databases from a server named
+ server.name:
all, i586,
- and qemux86. Given this example,
- issue the following commands on the target:
+ and qemux86.
+ Given this example, issue the following commands on the
+ target:
- # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
- # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
- # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
+ $ smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
+ $ smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
+ $ smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
Also from the target machine, fetch the repository
information using this command:
- # smart update
+ $ smart update
You can now use the smart query
and smart install commands to
@@ -3888,23 +3953,28 @@
Using IPK
+
The application for performing runtime package
management of IPK packages on the target is called
opkg.
-
+
+
+
In order to inform opkg of the
- package databases you wish to use, simply create one
+ package databases you want to use, simply create one
or more *.conf files in the
- /etc/opkg directory on the target
- and opkg will use them to find
- its available package databases. As an example if you
- configured your HTTP server on your machine named
+ /etc/opkg directory on the target.
+ The opkg application uses them
+ to find its available package databases.
+ As an example, suppose you configured your HTTP server
+ on your machine named
www.mysite.com to serve files
from a BOARD-dir directory under
- its document-root you might create a configuration
+ its document-root.
+ In this case, you might create a configuration
file on the target called
- /etc/opkg/base-feeds.conf which
+ /etc/opkg/base-feeds.conf that
contains:
src/gz all http://www.mysite.com/BOARD-dir/all
@@ -3912,43 +3982,46 @@
src/gz beagleboard http://www.mysite.com/BOARD-dir/beagleboard
-
+
+
As a way of making it easier to generate and make
these IPK configuration files available on your
target, the meta-oe layer
provides a recipe called
- distro-feed-configs (which
- provides a package by the same name). When you
- include this package into your image, it will
+ distro-feed-configs, which
+ provides a package by the same name.
+ When you include this package into your image, it will
automatically generate and include a set of
*.conf files in the image's
- /etc/opkg directory which will
- provide your target's opkg tool with any and all
- package databases your build will generate. The only
- catch is that this recipe can't possibly imagine your
- server's DNS name/IP address, so somewhere in your
- configuration you need to set a variable called
- DISTRO_FEED_URI which will point
+ /etc/opkg directory that will
+ provide your target's opkg
+ tool with any and all package databases your build will
+ generate.
+ The only catch is that this recipe cannot possibly
+ imagine your server's DNS name/IP address.
+ Consequently, somewhere in your configuration you need
+ to set a variable called
+ DISTRO_FEED_URI to point
to your server and the location within the
- document-root which contains the databases. For
- example: if you are serving your packages over HTTP,
+ document-root that contains the databases.
+ For example: if you are serving your packages over HTTP,
your server's IP address is 192.168.7.1, and your
databases are located in a directory called
BOARD-dir underneath your HTTP
- server's document-root then set
+ server's document-root, you need to set
DISTRO_FEED_URI to
http://192.168.7.1/BOARD-dir.
-
+
+
On the target machine, fetch (or refresh) the
repository information using this command:
- # opkg update
+ $ opkg update
- You can now use the opkg list and
- opkg install commands to find and
+ You can now use the opkg list and
+ opkg install commands to find and
install packages from the repositories.
-
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index e394122abe..27edfde33d 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -342,7 +342,7 @@
install packages from the feed while you are running the image
on the target (i.e. runtime installation of packages).
For more information, see the
- "Runtime Package Management"
+ "Using Runtime Package Management"
section in the Yocto Project Development Manual.