From 4404c690195532d4aed7ace38b55a35efa8fbd60 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 3 Oct 2013 07:14:41 -0700 Subject: 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 413 ++++++++++++--------- documentation/ref-manual/ref-classes.xml | 2 +- 2 files changed, 244 insertions(+), 171 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 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 - - 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: +
+ Using Runtime Package Management + + + 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. -- cgit v1.2.3-54-g00ecf