sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

ref-manual, dev-manual: Edits to runtime package management section. 

These changes modify the patch sent by Trevor that essentially
re-wrote this section.  My edits were for consistency only and
style of the book.  No technical information or flow was altered.

I did rename the section to be active to match the other package
related sections.  This caused the link in the ref-manual in the
classes chapter to have to be updated.

(From yocto-docs rev: eb2f950786574b1e90adc673ef00f52a70db9be6)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-10-03 07:14:41 -07:00 committed by Richard Purdie
parent b5ad5ba24b
commit 4404c69019
2 changed files with 243 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

411
documentation/dev-manual/dev-manual-common-tasks.xml
View File

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

2
documentation/ref-manual/ref-classes.xml
View File

@ -342,7 +342,7 @@
install packages from the feed while you are running the image install packages from the feed while you are running the image
on the target (i.e. runtime installation of packages). on the target (i.e. runtime installation of packages).
For more information, see the For more information, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#runtime-package-management'>Runtime Package Management</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
section in the Yocto Project Development Manual. section in the Yocto Project Development Manual.
</para> </para>