dev-manual: Updated Package Feed Creation sections

Fixes [YOCTO #1882]

Edited the sections in the "Working with Packages" section
beginning with the "Build Considerations" section with text
received from Daniela Placencia.

(From yocto-docs rev: 1ebd6a805699fc962a43a8f744194ab6e65b733c)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 187 insertions, 91 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a634ef16c7..24a7bdc28a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7528,27 +7528,48 @@
                 <title>Build Considerations</title>
 
                 <para>
-                    This section describes build considerations that you need
-                    to be aware of in order to provide support for runtime
+                    This section describes build considerations of which you
+                    need to be aware in order to provide support for runtime
                     package management.
                 </para>
 
                 <para>
-                    When BitBake generates packages it needs to know
+                    When BitBake generates packages, it needs to know
                     what format or formats to use.
                     In your configuration, you use the
                     <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
-                    variable to specify the format.
-                    <note>
-                        You can choose to have more than one format but you must
-                        provide at least one.
-                    </note>
+                    variable to specify the format:
+                    <orderedlist>
+                        <listitem><para>
+                            Open the <filename>local.conf</filename> file
+                            inside your
+                            <link linkend='build-directory'>Build Directory</link>
+                            (e.g. <filename>~/poky/build/conf/local.conf</filename>).
+                            </para></listitem>
+                        <listitem><para>
+                            Select the desired package format as follows:
+                            <literallayout class='monospaced'>
+     PACKAGE_CLASSES ?= “package_<replaceable>packageformat</replaceable>”
+                            </literallayout>
+                            where <replaceable>packageformat</replaceable>
+                            can be "ipk", "rpm", and "deb", which are the
+                            supported package formats.
+                            <note>
+                                Because the Yocto Project supports three
+                                different package formats, you can set the
+                                variable with more than one argument.
+                                However, the OpenEmbedded build system only
+                                uses the first argument when creating an image
+                                or Software Development Kit (SDK).
+                            </note>
+                            </para></listitem>
+                    </orderedlist>
                 </para>
 
                 <para>
                     If you would like your image to start off with a basic
-                    package database of the packages in your current build
-                    as well as have the relevant tools available on the
+                    package database containing the packages in your current
+                    build as well as to have the relevant tools available on the
                     target for runtime package management, you can include
                     "package-management" in the
                     <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
@@ -7583,9 +7604,9 @@
                     <literallayout class='monospaced'>
     $ bitbake <replaceable>some-package</replaceable> package-index
                     </literallayout>
-                    This is because BitBake does not properly schedule the
-                    <filename>package-index</filename> target fully after any
-                    other target has completed.
+                    The reason for this restriction is because BitBake does not
+                    properly schedule the <filename>package-index</filename>
+                    target fully after any other target has completed.
                     Thus, be sure to run the package update step separately.
                 </para>
 
@@ -7601,9 +7622,10 @@
 
                 <para>
                     When your build is complete, your packages reside in the
-                    <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename>
+                    <filename>${TMPDIR}/deploy/<replaceable>packageformat</replaceable></filename>
                     directory.
-                    For example, if <filename>${TMPDIR}</filename>
+                    For example, if
+                    <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink><filename>}</filename>
                     is <filename>tmp</filename> and your selected package type
                     is IPK, then your IPK packages are available in
                     <filename>tmp/deploy/ipk</filename>.
@@ -7614,10 +7636,9 @@
                 <title>Host or Server Machine Setup</title>
 
                 <para>
-                    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
+                    Although other protocols are possible, a server using HTTP
+                    typically serves packages.
+                    If you want to use HTTP, then set up and configure a
                     web server, such as Apache 2 or lighttpd, on the machine
                     serving the packages.
                 </para>
@@ -7640,7 +7661,7 @@
                                 Add the directory to your Apache
                                 configuration, which you can find at
                                 <filename>/etc/httpd/conf/httpd.conf</filename>.
-                                Use commands similar to these on the
+                                Use commands similar to the following on the
                                 development system.
                                 These example commands assume a top-level
                                 <link linkend='source-directory'>Source Directory</link>
@@ -7651,13 +7672,14 @@
                                 as IPK, use "ipk" in the pathnames:
                                 <literallayout class='monospaced'>
      &lt;VirtualHost *:80&gt;
-       ....
+       ...
          Alias /rpm ~/poky/build/tmp/deploy/rpm
          &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
            Options +Indexes
          &lt;/Directory&gt;
      &lt;/VirtualHost&gt;
-                                </literallayout></para></listitem>
+                                </literallayout>
+                                </para></listitem>
                             <listitem><para>
                                 Reload the Apache configuration as described
                                 in this step.
@@ -7678,7 +7700,8 @@
                                 For OpenSUSE, use the following:
                                 <literallayout class='monospaced'>
      # /etc/init.d/apache2 reload
-                                </literallayout></para></listitem>
+                                </literallayout>
+                                </para></listitem>
                             <listitem><para>
                                 If you are using Security-Enhanced Linux
                                 (SELinux), you need to label the files as
@@ -7688,26 +7711,24 @@
                                 This example assumes RPM package types:
                                 <literallayout class='monospaced'>
      # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
-                                </literallayout></para></listitem>
+                                </literallayout>
+                                </para></listitem>
                         </orderedlist>
                     </para>
                 </section>
 
                 <section id='package-server-lighttpd'>
-                    <title>Serving Packages via lighttpd</title>
+                    <title>Serving Packages Through lighttpd</title>
 
                     <para>
                         If you are using lighttpd, all you need
                         to do is to provide a link from your
-                        <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename>
+                        <filename>${TMPDIR}/deploy/<replaceable>packageformat</replaceable></filename>
                         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:
                         <filename>/etc/lighttpd/lighttpd.conf</filename>.
-                    </para>
-
-                    <para>
                         For example, if you are using IPK, lighttpd's
                         document-root is set to
                         <filename>/var/www/lighttpd</filename>, and you had
@@ -7729,6 +7750,38 @@
                         </literallayout>
                     </para>
                 </section>
+
+                <section id='package-server-python-simplehttpserver'>
+                    <title>Serving Packages Through Python SimpleHTTPServer</title>
+
+                    <para>
+                        It is possible to serve packages hosted by a build
+                        machine through an HTTP server created with a simple
+                        Python command.
+                    </para>
+
+                    <para>
+                        The first thing you do is to create a directory that
+                        contains the packages to host.
+                        Be sure you have root privileges and place the directory
+                        inside <filename>var/www/</filename>
+                        (e.g. <filename>/var/www/my_repo/</filename>).
+                        To ensure the directory contains the packages you want
+                        to serve, you need to create a symlink from the
+                        package feed area to the directory that hosts the
+                        packages you want to provide:
+                        <literallayout class='monospaced'>
+     my_repo # ln -s ~{TMPDIR}/deploy/<replaceable>packageformat</replaceable> ./
+                        </literallayout>
+                        You can start the server by running the following
+                        command from the recently created directory:
+                        <literallayout class='monospaced'>
+     # python -m SimpleHTTPServer
+
+     Serving HTTP on 0.0.0 port 8000 ...
+                        </literallayout>
+                    </para>
+                </section>
             </section>
 
             <section id='runtime-package-management-target'>
@@ -7744,35 +7797,35 @@
                     <title>Using RPM</title>
 
                     <para>
-                        The application for performing runtime package
-                        management of RPM packages on the target is called
-                        <filename>smart</filename>.
+                        The <filename>smart</filename> application performs
+                        runtime package management of RPM packages.
+                        This application is aware of every package database
+                        you want to use.
+                        You must perform an initial setup for
+                        <filename>smart</filename> on the target machine.
                     </para>
 
                     <para>
-                        On the target machine, you need to inform
-                        <filename>smart</filename> of every package database
-                        you want to use.
-                        As an example, suppose your target device can use the
-                        following three package databases from a server named
-                        <filename>server.name</filename>:
+                        As an example, assume the target is able to use the
+                        following package databases:
                         <filename>all</filename>, <filename>i586</filename>,
-                        and <filename>qemux86</filename>.
-                        Given this example, issue the following commands on the
-                        target:
+                        and <filename>qemux86</filename> from a server named
+                        <filename>my.server</filename>.
+                        You must inform <filename>smart</filename> of the
+                        availability of these databases by issuing the
+                        following commands on the target:
                         <literallayout class='monospaced'>
-     # 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 i585 type=rpm-md baseurl=http://my.server/rpm/i586
+     # smart channel --add qemux86 type=rpm-md baseurl=http://my.server/rpm/qemux86
+     # smart channel --add all type=rpm-md baseurl=http://my.server/rpm/all
                         </literallayout>
-                        Also from the target machine, fetch the repository
-                        information using this command:
+                        From the target machine, fetch the repository:
                         <literallayout class='monospaced'>
      # smart update
                         </literallayout>
-                        You can now use the <filename>smart query</filename>
-                        and <filename>smart install</filename> commands to
-                        find and install packages from the repositories.
+                        After everything is set up, <filename>smart</filename>
+                        is able to find, install, and upgrade packages from
+                        the specified repository.
                     </para>
                 </section>
 
@@ -7780,61 +7833,104 @@
                     <title>Using IPK</title>
 
                     <para>
-                        The application for performing runtime package
-                        management of IPK packages on the target is called
-                        <filename>opkg</filename>.
+                        The <filename>opkg</filename> application performs
+                        runtime package management of IPK packages.
+                        This application is aware of every package database
+                        you want to use.
+                        You must perform an initial setup for
+                        <filename>opkg</filename> on the target machine.
                     </para>
 
                     <para>
-                        In order to inform <filename>opkg</filename> of the
-                        package databases you want to use, simply create one
-                        or more <filename>*.conf</filename> files in the
-                        <filename>/etc/opkg</filename> directory on the target.
-                        The <filename>opkg</filename> application uses them
-                        to find its available package databases.
-                        As an example, suppose you configured your HTTP server
-                        on your machine named
-                        <filename>www.mysite.com</filename> to serve files
-                        from a <filename>BOARD-dir</filename> directory under
-                        its document-root.
-                        In this case, you might create a configuration
-                        file on the target called
-                        <filename>/etc/opkg/base-feeds.conf</filename> that
-                        contains:
+                        The <filename>opkg</filename> application uses
+                        configuration files to find available package
+                        databases.
+                        Thus, you need to create a configuration file inside
+                        the <filename>/etc/opkg/</filename> direction, which
+                        informs <filename>opkg</filename> of any repository
+                        you want to use.
+                    </para>
+
+                    <para>
+                        For example, assume the following:
+                        <itemizedlist>
+                            <listitem><para>
+                                An HTTP server named
+                                <filename>my.server</filename> exists on your
+                                build machine.
+                                </para></listitem>
+                            <listitem><para>
+                                The server is serving packages from a directory
+                                named <filename>ipk/</filename>.
+                                </para></listitem>
+                            <listitem><para>
+                                The target machine is able to use the
+                                <filename>i586</filename>,
+                                <filename>all</filename>, and
+                                <filename>qemux86</filename> package
+                                databases.
+                                </para></listitem>
+                        </itemizedlist>
+                        On the target, create a configuration file
+                        (e.g. <filename>my_repo.conf</filename>) inside the
+                        <filename>/etc/opkg/</filename> directory containing
+                        the following:
+                        <literallayout class='monospaced'>
+     src/gz all http://my.server/ipk/all
+     src/gz i586 http://my.server/ipk/i586
+     src/gz qemux86 http://my.server/ipk/qemux86
+                        </literallayout>
+                        Next, instruct <filename>opkg</filename> to fetch
+                        the repository information:
                         <literallayout class='monospaced'>
-     src/gz all http://www.mysite.com/BOARD-dir/all
-     src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
-     src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone
+     #opkg update
                         </literallayout>
+                        The <filename>opkg</filename> application is now able
+                        to find, install, and upgrade packages from the
+                        specified repository.
                     </para>
+                </section>
+
+                <section id='runtime-package-management-target-deb'>
+                    <title>Using DEB</title>
 
                     <para>
-                        As a way of making it easier to generate and make
-                        these IPK configuration files available on your
-                        target, simply define
-                        <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink>
-                        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, your server's IP address is 192.168.7.1, and
-                        your databases are located in a directory called
-                        <filename>BOARD-dir</filename> underneath your HTTP
-                        server's document-root, you need to set
-                        <filename>FEED_DEPLOYDIR_BASE_URI</filename> to
-                        <filename>http://192.168.7.1/BOARD-dir</filename> and
-                        a set of configuration files will be generated for you
-                        in your target to work with this feed.
+                        The <filename>apt</filename> application performs
+                        runtime package management of DEB packages.
+                        This application uses a source list file to find
+                        available package databases.
+                        The application is aware of every package database
+                        you want to use.
+                        You must perform an initial setup for
+                        <filename>opkg</filename> on the target machine.
                     </para>
 
                     <para>
-                        On the target machine, fetch (or refresh) the
-                        repository information using this command:
+                        To inform <filename>apt</filename> of the repository
+                        you want to use, you might create a list file (e.g.
+                        <filename>my_repo.list</filename>) inside the
+                        <filename>/etc/apt/sources.list.d/</filename>
+                        directory.
+                        As an example, suppose you are serving packages from a
+                        <filename>deb/</filename> directory containing the
+                        <filename>i586</filename>,
+                        <filename>all</filename>, and
+                        <filename>qemux86</filename> databases through an
+                        HTTP server named <filename>my.server</filename>.
+                        The list file should contain:
+                        <literallayout class='monospaced'>
+     deb http://my.server/deb/all ./
+     deb http://my.server/deb/i586 ./
+     deb http://my.server/deb/qemux86 ./
+                        </literallayout>
+                        Next, instruct the <filename>apt</filename>
+                        application to fetch the repository information:
                         <literallayout class='monospaced'>
-     # opkg update
+     #apt-get update
                         </literallayout>
-                        You can now use the <filename>opkg list</filename> and
-                        <filename>opkg install</filename> commands to find and
-                        install packages from the repositories.
+                        After this step, <filename>apt</filename> is able
+                        to find, install, and upgrade packages from the
+                        specified repository.
                     </para>
                 </section>
             </section>