[oe-commits] org.oe.documentation Re-merge elaborated description of FEED_URIS and FEED_DEPLOYDIR_BASE_URI.

[pfalcon commit]

Re-merge elaborated description of FEED_URIS and FEED_DEPLOYDIR_BASE_URI.

Author: pfalcon at openembedded.org
Branch: org.openembedded.documentation
Revision: 2dfbc192ed68d75080bbfe59b2514098f7e5bfc7
ViewMTN: http://monotone.openembedded.org/revision/info/2dfbc192ed68d75080bbfe59b2514098f7e5bfc7
Files:
1
usermanual/reference/class_image.xml
Diffs:

#
# mt diff -r05ae862ddb5f2bf796be4254a0804207d2ff9a96 -r2dfbc192ed68d75080bbfe59b2514098f7e5bfc7
#
# 
# 
# patch "usermanual/reference/class_image.xml"
#  from [9f70be2bfeda405f006dc804a6db6c9107e02a4b]
#    to [e1fe4007e4d41b2198a3671342711c339632f943]
# 
============================================================
--- usermanual/reference/class_image.xml	9f70be2bfeda405f006dc804a6db6c9107e02a4b
+++ usermanual/reference/class_image.xml	e1fe4007e4d41b2198a3671342711c339632f943
@@ -56,8 +56,8 @@
     </listitem>
 
     <listitem>
-      <para>Configures the ipkg feed information in the root filesystem for
-      the <command>FEED_URIS</command>;</para>
+      <para>Configures the ipkg feed information in the root filesystem 
+      (using <command>FEED_URIS</command> and <command>FEED_DEPLOYDIR_BASE_URI</command>);</para>
     </listitem>
 
     <listitem>
@@ -190,6 +190,20 @@
         <para>Default: <command>""</command></para>
       </listitem>
     </varlistentry>
+
+    <varlistentry>
+      <term>FEED_DEPLOYDIR_BASE_URI</term>
+
+      <listitem>
+        <para>If set, configures local testing feeds using OE package deploy dir
+	contents. The value is URL, corresponding to the ipk deploy dir.</para>
+
+        <para>Example: <command>FEED_DEPLOYDIR_BASE_URI =
+        "http://192.168.2.200/bogofeed/"</command></para>
+
+        <para>Default: <command>""</command></para>
+      </listitem>
+    </varlistentry>
   </variablelist>
 
   <section>
@@ -274,18 +288,71 @@ IMAGE_DEVICE_TABLES = "files/device_tabl
   </section>
 
   <section>
-    <title>Package feeds (feed_uris)</title>
+    <title>Package feeds</title>
 
-    <para>Package feeds are used by the ipkg command to determine where to
-    retrieve updates and new packages from.</para>
+    <para>"Package feed", or feed for short, is a term used by <command>ipkg</command> 
+    package manager, commonly used in embedded systems, to name a package repository 
+    holding packages. Structurally, a feed is a directory - local, or on HTTP of FTP server, -
+    holding packages and package descriptor file, named <command>Packages</command> or 
+    <command>Packages.gz</command> if compressed. Multiple feeds are supported.</para>
 
-    <para>Multiple feeds are supported. Each feed provides a feed name and the
-    URL which will contain the packages. The following example shows the
-    addition of two feeds, one called <emphasis>base</emphasis> and one called
-    <emphasis>updates</emphasis>:</para>
+    <para>OpenEmbedded has support to pre-configure feeds within generated images, 
+    so once image is installed on a device, user can immediately install new software, 
+    without the need to manually edit config files. There are several ways to pre-configure 
+    feed support, described below.</para>
+    
+    <section>
+        <title>Method 1: Using existing feed</title>
+            <para>If you already have the feed(s) set up and available via specific URL, they
+	    can be added to the image using FEED_URIS variable:
+<screen>FEED_URIS = " \
+        base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \
+        updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen>
 
-    <para><screen>FEED_URIS += " \
-        base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \
-        updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen></para>
+	    FEED_URIS contains list of feed descriptors, separated by spaces, per 
+	    OE conventions. Each descriptor consists of feed name and feed URL, 
+	    joined with "##". Feed name is an identifier used by ipkg to distinguish
+	    among the feeds. It can be arbitrary, just useful to the users to understood 
+	    which feed is used for one or another action.</para>
+    </section>
+
+    <section>
+        <title>Method 2: Using OE deploy directory as a feed (development only)</title>
+        <para>OE internally maintains a feed-like collection of directories to create
+	images from packages. This package deployment directory however has structure internal to OE
+	and subject to change without notice. Thus, using it as feed directly is not recommended
+	(distributions which ignored this recommendation are known to have their feeds broken when
+	OE upgraded its internal mechanisms).</para>
+        <para>However, using deploy directory as feed directly may be beneficial during
+	development and testing, as it allows developers to easily install newly built packages
+	without many manual actions. To facilitate this, OE offers a way to prepare feed configs
+	for using deploy dir as such. To start with this, you first need to configure local 
+	HTTP server to export a package deployment directory via HTTP.
+	Suppose you will export it via URL "http://192.168.2.200/bogofeed" (where 192.168.2.200 is the address
+	which will be reachable from the device). Add the following to your local.conf:
+<screen>
+FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed"
+</screen>
+	Now you need to setup local HTTP server to actually export that directory. For Apache it can be:
+<screen>
+<![CDATA[ 
+Alias /bogofeed ${DEPLOY_DIR} 
+ 
+<Directory ${DEPLOY_DIR}>
+    Options Indexes FollowSymLinks
+    Order deny,allow
+    Allow from 192.168.2.0/24
+</Directory>
+]]>
+</screen>
+	Replace ${DEPLOY_DIR} with the full path of deploy directory (last components of its path will be
+	<command>deploy/ipk</command>).</para>
+        <para>Now, every image built will automatically contain feed configs
+	for the deploy directory (as of time of writing, deploy directory is internally structured with
+	per-arch subdirectories; so, there several feed configs are being generated, one for each subdirectory).
+        </para>
+
+    </section>
+
   </section>
 </section>