summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml471
1 files changed, 321 insertions, 150 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index fe34e8ecd8..7b4d638dfa 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3605,61 +3605,179 @@
3605 </section> 3605 </section>
3606 </section> 3606 </section>
3607 3607
3608 <section id='setting-up-runtime-package-management'> 3608 <section id='runtime-package-management'>
3609 <title>Setting Up Runtime Package Management</title> 3609 <title>Runtime Package Management</title>
3610 3610 <para>
3611 <para> 3611 Regardless of anything else, during a build bitbake will
3612 For supported package formats, it is possible to set 3612 transform a recipe into one or more packages. For example,
3613 up a repository that is a host-based package feed from which 3613 the <filename>bash</filename> recipe currently produces the
3614 you can install packages on the target system during runtime. 3614 following packages: <filename>bash-dbg bash-staticdev bash-dev
3615 Doing so is optional and depends on the following: 3615 bash-doc bash-locale bash</filename>. Not all generated
3616 packages will be included in an image.
3617 </para><para>
3618 In several situations you might want to have the ability to
3619 update, add, remove, query, etc the packages on a target
3620 device at runtime (i.e. without having to generate a new
3621 image). Examples of such situations include:
3616 <itemizedlist> 3622 <itemizedlist>
3617 <listitem><para> 3623 <listitem><para>
3618 You take specific steps to set up the feed. 3624 You want to provide in-the-field updates to deployed
3619 </para></listitem> 3625 devices (e.g. for security updates).
3626 </para></listitem>
3620 <listitem><para> 3627 <listitem><para>
3621 When you build your image, you select to use the 3628 You want to have a fast turn-around development cycle
3622 appropriate package manager by setting the 3629 for one or more applications which run on your device.
3623 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> 3630 </para></listitem>
3624 variable.
3625 </para></listitem>
3626 <listitem><para> 3631 <listitem><para>
3627 You have a web server, such as Apache 2, 3632 You want to temporarily install the "debug" packages
3628 installed and configured on the development host. 3633 of various applications on your device so that
3629 </para></listitem> 3634 debugging can be greatly improved (access to symbols,
3635 source debugging, etc).
3636 </para></listitem>
3630 <listitem><para> 3637 <listitem><para>
3631 You enable package management on the target by 3638 You want to deploy a more minimal package selection of
3632 listing "package-management" in the 3639 your device but allow in-the-field updates to add a
3633 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> 3640 larger selection for customization.
3634 variable. 3641 </para></listitem>
3635 </para></listitem>
3636 </itemizedlist> 3642 </itemizedlist>
3637 </para> 3643 </para><para>
3644 In all these situations you have something similar to a more
3645 traditional Linux distribution in that in-field devices
3646 are able to grab pre-compiled packages from a server for
3647 installation/update. This is what is termed "runtime package
3648 management". In order to use runtime package management you
3649 need a host/server machine which serves up the pre-compiled
3650 packages plus the required meta data, and you need package
3651 manipulation tools on the target. Note that the build machine
3652 is a likely candidate to act as the server, but the build
3653 machine doesn't necessarily have to be the package server;
3654 the build machine could push its artifacts to another (e.g.
3655 Internet-facing) machine which acts as the server.
3656 </para><para>
3657 A simple build which targets just one device will produce
3658 more than one package database. In other words, the packages
3659 produced by a build will be separated out into a couple of
3660 different package groupings based on criteria such as the
3661 target's CPU architecture, the target board, or the C library
3662 used on the target. For example, a build targetting the
3663 <filename>qemuarm</filename> device will produce the following
3664 3 package databases: <filename>all</filename>,
3665 <filename>armv5te</filename>, and
3666 <filename>qemuarm</filename>. If I wanted my
3667 <filename>qemuarm</filename> device to be aware of all the
3668 packages which were available to it, I would need to point it
3669 to each of these databases individually. In a similar way, a
3670 traditional Linux distribution usually is configured to be
3671 aware of a number of software repositories from which it
3672 will retrieve packages.
3673 </para><para><note>
3674 Using runtime package management is completely optional and
3675 not required for a successful build or deployment in any way.
3676 But if you want to make use of runtime package management
3677 you'll need to do a couple things above and beyond the basics.
3678 </note></para>
3679
3680 <section id='runtime-package-management-build'>
3681 <title>Build Considerations</title>
3682 <para>
3683 In order to provide support for runtime package management
3684 there are some build considerations of which to be aware.
3685 </para><para>
3686 When bitbake generates packages it needs to know in
3687 which format(s) you want the packages to be generated.
3688 In your configuration this is handled by the
3689 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
3690 variable. Note that you can choose to have more than one,
3691 but at least one is required.
3692 </para><para>
3693 If you would like your image to start off with a basic
3694 package database of the packages in your current build
3695 as well as having the relevant tools available on the
3696 target for runtime package management, you can include
3697 "package-management" in the
3698 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
3699 variable. Including "package-management" in this
3700 configuration variable ensures that when the image
3701 is assembled for your target it will include
3702 the currently-known package databases as well as
3703 the target-specific tools required for runtime
3704 package management to be performed on the target.
3705 Note, however, this isn't strictly necessary.
3706 You could start your image off without any databases
3707 but only include the required on-target package
3708 tool(s) (for example you would include "opkg" in your
3709 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
3710 variable if you are using the IPK package format). You can
3711 then initialize your target's package database(s) later,
3712 once your image is up and running.
3713 </para><para>
3714 Whenever you perform any sort of build step which can
3715 potentially generate a package or modify an existing
3716 package, it is always a good idea to re-generate the
3717 package index with:
3718 <literallayout class='monospaced'>
3719 $ bitbake package-index
3720 </literallayout>
3721 Note that it is not sufficient to simply do:
3722 <literallayout class='monospaced'>
3723 $ bitbake &lt;some-package&gt; package-index
3724 </literallayout>
3725 since bitbake won't properly schedule the
3726 <filename>package-index</filename> target fully after any
3727 other target has completed. Therefore, be sure to run the
3728 package update step separately.
3729 </para><para>
3730 As described below in the
3731 <link linkend='runtime-package-management-target-ipk'>Using IPK</link>
3732 section, if you are using IPK as your package format, you
3733 can make use of the
3734 <filename>distro-feed-configs</filename> recipe provided
3735 by <filename>meta-oe</filename> in order to configure your
3736 target to use your IPK databases.
3737 </para><para>
3738 When your build is complete your packages will show up in
3739 the
3740 <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
3741 directory. For example, if <filename>${TMPDIR}</filename>
3742 is <filename>tmp</filename> and your selected package type
3743 is IPK, then your IPK packages will be available in
3744 <filename>tmp/deploy/ipk</filename>.
3745 </para>
3746 </section>
3638 3747
3639 <para> 3748 <section id='runtime-package-management-server'>
3640 The following list provides steps for setting up the optional 3749 <title>Host or Server Machine Setup</title>
3641 repository regardless of the package format. 3750 <para>
3642 Once you work through these generic steps, see the 3751 Typically packages are served from a server via HTTP, but
3643 "<link linkend='runtime-package-management-deb-rpm'>Using RPM</link>" 3752 other protocols are possible. If we assume you want to
3644 section or the 3753 use HTTP, then you would need to setup and configure a
3645 "<link linkend='runtime-package-management-ipk'>Using IPK</link>" 3754 web server, such as Apache 2 or lighttpd, on the machine
3646 section for remaining steps specific to the package type. 3755 serving the packages. As mentioned above, the build
3647 <note> 3756 machine can act as the package server; in the following
3648 The example assumes you are using the Apache 2 server: 3757 server machine setups it is assumed the build machine is
3649 </note> 3758 also the server.
3650 <orderedlist> 3759 </para>
3651 <listitem><para> 3760
3652 Add the directory to your Apache configuration, which 3761 <section id='package-server-apache'>
3653 you can find at 3762 <title>Serving Packages via Apache 2</title>
3654 <filename>/etc/httpd/conf/httpd.conf</filename>. 3763 <para>
3655 Use commands similar to these on the development system. 3764 This example assumes you are using the Apache 2
3656 These example commands assume a top-level 3765 server:
3657 <link linkend='source-directory'>Source Directory</link> 3766 <orderedlist>
3658 named <filename>poky</filename> in your home directory. 3767 <listitem><para>
3659 The example also assumes an RPM package type. 3768 Add the directory to your Apache
3660 If you are using a different package type, such as 3769 configuration, which you can find at
3661 IPK, use "ipk" in the pathnames: 3770 <filename>/etc/httpd/conf/httpd.conf</filename>.
3662 <literallayout class='monospaced'> 3771 Use commands similar to these on the
3772 development system. These example
3773 commands assume a top-level
3774 <link linkend='source-directory'>Source Directory</link>
3775 named <filename>poky</filename> in your home
3776 directory. The example also assumes an RPM
3777 package type. If you are using a different
3778 package type, such as IPK, use "ipk" in the
3779 pathnames:
3780 <literallayout class='monospaced'>
3663 &lt;VirtualHost *:80&gt; 3781 &lt;VirtualHost *:80&gt;
3664 .... 3782 ....
3665 Alias /rpm ~/poky/build/tmp/deploy/rpm 3783 Alias /rpm ~/poky/build/tmp/deploy/rpm
@@ -3667,119 +3785,172 @@
3667 Options +Indexes 3785 Options +Indexes
3668 &lt;/Directory&gt; 3786 &lt;/Directory&gt;
3669 &lt;/VirtualHost&gt; 3787 &lt;/VirtualHost&gt;
3788 </literallayout>
3789 </para></listitem>
3790 <listitem><para>
3791 Reload the Apache configuration as follows.
3792 For all commands, be sure you have root
3793 privileges.
3794 </para><para>
3795 If your development system is using Fedora or
3796 CentOS, use the following:
3797 <literallayout class='monospaced'>
3798 # service httpd reload
3799 </literallayout>
3800 For Ubuntu and Debian, use the following:
3801 <literallayout class='monospaced'>
3802 # /etc/init.d/apache2 reload
3803 </literallayout>
3804 For OpenSUSE, use the following:
3805 <literallayout class='monospaced'>
3806 # /etc/init.d/apache2 reload
3807 </literallayout>
3808 </para></listitem>
3809 <listitem><para>
3810 If you are using Security-Enhanced Linux
3811 (SELinux), you need to label the files as
3812 being accessible through Apache. Use the
3813 following command from the development host
3814 (this example assumes RPM package types):
3815 <literallayout class='monospaced'>
3816 # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
3817 </literallayout>
3818 </para></listitem>
3819 </orderedlist>
3820 </para>
3821 </section>
3822
3823 <section id='package-server-lighttpd'>
3824 <title>Serving Packages via lighttpd</title>
3825 <para>
3826 If you are using lighttpd all you need
3827 to do is to provide a link from your
3828 ${TMPDIR}/deploy/&lt;package-format&gt; directory to
3829 lighttpd's document-root. You can determine the
3830 specifics of your lighttpd installation by looking
3831 through its configuration file which is usually found
3832 at: <filename>/etc/lighttpd/lighttpd.conf</filename>.
3833 </para><para>
3834 For example, if you are using IPK, if
3835 lighttpd's document-root is set to
3836 <filename>/var/www/lighttpd</filename>, and if you had
3837 packages for a target named "BOARD"
3838 then you might create a link from your build location
3839 to lighttpd's document-root as follows:
3840 <literallayout class='monospaced'>
3841 # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
3670 </literallayout> 3842 </literallayout>
3671 </para></listitem> 3843 </para><para>
3672 <listitem><para> 3844 At this point you need to start the lighttpd server.
3673 Reload the Apache configuration as follows. 3845 The way in which you start the server will vary by
3674 For all commands, be sure you have root privileges. 3846 distribution, but one basic way to start it by hand
3675 </para> 3847 would be:
3676 <para>
3677 If your development system is using Fedora or
3678 CentOS, use the following:
3679 <literallayout class='monospaced'> 3848 <literallayout class='monospaced'>
3680 service httpd reload 3849 # lighttpd -f /etc/lighttpd/lighttpd.conf
3681 </literallayout> 3850 </literallayout>
3682 For Ubuntu and Debian, use the following: 3851 </para>
3852 </section>
3853 </section>
3854
3855 <section id='runtime-package-management-target'>
3856 <title>Target Setup</title>
3857
3858 <section id='runtime-package-management-target-rpm'>
3859 <title>Using RPM</title>
3860 <para>
3861 The application for performing runtime package
3862 management of RPM packages on the target is called
3863 <filename>smart</filename>.
3864 </para><para>
3865 On the target machine, you need to inform
3866 <filename>smart</filename> of every package database
3867 you wish to use. As an example, suppose your target
3868 device can use the following 3 package databases from
3869 a server named <filename>server.name</filename>:
3870 <filename>all</filename>, <filename>i586</filename>,
3871 and <filename>qemux86</filename>. Given this example,
3872 issue the following commands on the target:
3683 <literallayout class='monospaced'> 3873 <literallayout class='monospaced'>
3684 /etc/init.d/apache2 reload 3874 # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
3875 # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
3876 # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
3685 </literallayout> 3877 </literallayout>
3686 For OpenSUSE, use the following: 3878 Also from the target machine, fetch the repository
3879 information using this command:
3687 <literallayout class='monospaced'> 3880 <literallayout class='monospaced'>
3688 /etc/init.d/apache2 reload 3881 # smart update
3689 </literallayout> 3882 </literallayout>
3690 </para></listitem> 3883 You can now use the <filename>smart query</filename>
3691 <listitem><para> 3884 and <filename>smart install</filename> commands to
3692 Re-generate the package index: 3885 find and install packages from the repositories.
3886 </para>
3887 </section>
3888
3889 <section id='runtime-package-management-target-ipk'>
3890 <title>Using IPK</title>
3891 <para>
3892 The application for performing runtime package
3893 management of IPK packages on the target is called
3894 <filename>opkg</filename>.
3895 </para><para>
3896 In order to inform <filename>opkg</filename> of the
3897 package databases you wish to use, simply create one
3898 or more <filename>*.conf</filename> files in the
3899 <filename>/etc/opkg</filename> directory on the target
3900 and <filename>opkg</filename> will use them to find
3901 its available package databases. As an example if you
3902 configured your HTTP server on your machine named
3903 <filename>www.mysite.com</filename> to serve files
3904 from a <filename>BOARD-dir</filename> directory under
3905 its document-root you might create a configuration
3906 file on the target called
3907 <filename>/etc/opkg/base-feeds.conf</filename> which
3908 contains:
3693 <literallayout class='monospaced'> 3909 <literallayout class='monospaced'>
3694 bitbake package-index 3910 src/gz all http://www.mysite.com/BOARD-dir/all
3911 src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
3912 src/gz beagleboard http://www.mysite.com/BOARD-dir/beagleboard
3695 </literallayout> 3913 </literallayout>
3696 </para></listitem> 3914 </para>
3697 <listitem><para> 3915 <note>
3698 If you are using Security-Enhanced Linux (SELinux), 3916 As a way of making it easier to generate and make
3699 you need to label the files as being accessible 3917 these IPK configuration files available on your
3700 through Apache. 3918 target, the <filename>meta-oe</filename> layer
3701 Use the following command from the development host. 3919 provides a recipe called
3702 Again, the example assumes RPM package types: 3920 <filename>distro-feed-configs</filename> (which
3921 provides a package by the same name). When you
3922 include this package into your image, it will
3923 automatically generate and include a set of
3924 <filename>*.conf</filename> files in the image's
3925 <filename>/etc/opkg</filename> directory which will
3926 provide your target's opkg tool with any and all
3927 package databases your build will generate. The only
3928 catch is that this recipe can't possibly imagine your
3929 server's DNS name/IP address, so somewhere in your
3930 configuration you need to set a variable called
3931 <filename>DISTRO_FEED_URI</filename> which will point
3932 to your server and the location within the
3933 document-root which contains the databases. For
3934 example: if you are serving your packages over HTTP,
3935 your server's IP address is 192.168.7.1, and your
3936 databases are located in a directory called
3937 <filename>BOARD-dir</filename> underneath your HTTP
3938 server's document-root then set
3939 <filename>DISTRO_FEED_URI</filename> to
3940 <filename>http://192.168.7.1/BOARD-dir</filename>.
3941 </note>
3942 <para>
3943 On the target machine, fetch (or refresh) the
3944 repository information using this command:
3703 <literallayout class='monospaced'> 3945 <literallayout class='monospaced'>
3704 chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm 3946 # opkg update
3705 </literallayout> 3947 </literallayout>
3706 </para></listitem> 3948 You can now use the <filename>opkg list</filename> and
3707 </orderedlist> 3949 <filename>opkg install</filename> commands to find and
3708 </para> 3950 install packages from the repositories.
3709 3951 </para><para>
3710 <section id='runtime-package-management-deb-rpm'> 3952 </para>
3711 <title>Using RPM</title> 3953 </section>
3712
3713 <para>
3714 Following are RPM-specific steps needed for setting up the
3715 optional repository.
3716 Perform these steps after working through the common steps
3717 at the start of this section:
3718 <orderedlist>
3719 <listitem><para>
3720 On the target machine, add the repository to Smart
3721 for every package architecture.
3722 To see the list of package architectures, list
3723 the contents of the
3724 setting-up-runtime-package-management <filename>tmp/deploy/rpm</filename> directory
3725 on the host.</para>
3726 <para>
3727 As an example, suppose you list the contents of the
3728 directory and discover three architectures:
3729 <filename>all</filename>, <filename>i586</filename>,
3730 and <filename>qemux86</filename>.
3731 Given this example, use the following commands:
3732 <literallayout class='monospaced'>
3733 smart channel &dash;&dash;add all type=rpm-md baseurl=http://server.name/rpm/all
3734 smart channel &dash;&dash;add i585 type=rpm-md baseurl=http://server.name/rpm/i586
3735 smart channel &dash;&dash;add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
3736 </literallayout>
3737 </para></listitem>
3738 <listitem><para>
3739 Also from the target machine, fetch the repository
3740 information using this command:
3741 <literallayout class='monospaced'>
3742 smart update
3743 </literallayout>
3744 </para></listitem>
3745 </orderedlist>
3746 You can now use the <filename>smart query</filename>
3747 and <filename>smart install</filename> commands to find
3748 and install packages from the repositories.
3749 </para>
3750 </section>
3751
3752 <section id='runtime-package-management-ipk'>
3753 <title>Using IPK</title>
3754
3755 <para>
3756 Following are IPK-specific steps needed for setting up the
3757 optional repository.
3758 Perform these steps after working through the common steps
3759 at the start of this section:
3760 <orderedlist>
3761 <listitem><para>Install packages onto an
3762 existing running system by first sharing the
3763 <filename>tmp/deploy/ipk/</filename> directory
3764 through a web server and then by changing
3765 <filename>/etc/opkg/base-feeds.conf</filename>
3766 to point at the shared server.
3767 Following is an example:
3768 <literallayout class='monospaced'>
3769 src/gz all http://www.mysite.com/somedir/deploy/ipk/all
3770 src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
3771 src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
3772 </literallayout></para></listitem>
3773 <listitem><para>From the target machine, fetch the
3774 repository information using this command:
3775 <literallayout class='monospaced'>
3776 opkg update
3777 </literallayout></para></listitem>
3778 </orderedlist>
3779 You can now use the <filename>opkg list</filename> and
3780 <filename>opkg install</filename> commands to find and
3781 install packages from the repositories.
3782 </para>
3783 </section> 3954 </section>
3784 </section> 3955 </section>
3785 3956
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-10-25 06:53:40 +0000