[oe-commits] org.oe.documentation usermanual.xml: Describe OE feed support facilities, FEED_URIS and FEED_DEPLOYDIR_BASE_URI.

[pfalcon commit]

usermanual.xml: Describe OE feed support facilities, FEED_URIS and FEED_DEPLOYDIR_BASE_URI.

Author: pfalcon at openembedded.org
Branch: org.openembedded.documentation
Revision: 338f5fc9c32e401a6033a90c9d909663dc527857
ViewMTN: http://monotone.openembedded.org/revision/info/338f5fc9c32e401a6033a90c9d909663dc527857
Files:
1
usermanual/usermanual.xml
Diffs:

#
# mt diff -rabef3810e6bc9f11fd4035b728b6930d55a84edb -r338f5fc9c32e401a6033a90c9d909663dc527857
#
# 
# 
# patch "usermanual/usermanual.xml"
#  from [2e60849f6d0acdd1926fd2be6fce075dd85da316]
#    to [ff16b9d6696e4f622e32121c803362ec111c32f8]
# 
============================================================
--- usermanual/usermanual.xml	2e60849f6d0acdd1926fd2be6fce075dd85da316
+++ usermanual/usermanual.xml	ff16b9d6696e4f622e32121c803362ec111c32f8
@@ -253,6 +253,76 @@ they will be added automatically.</para>
             <title>Overrides <anchor id="overrides" /></title>
             <para>This section is a stub, help us by expanding it</para>
         </section>
+
+        <section>
+            <title>Package Feed Support <anchor id="feeds" /></title>
+            <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 on HTTP of FTP server,
+holding packages and package descriptor file, named <command>Packages</command> or <command>Packages.gz</command>
+if compressed.
+	    </para>
+	    <para>OpenEmbedded has support to pre-configure feeds within generated images, so once images are
+installed on devices, users 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 a feed(s) set up and available via specific URL, you can
+add them to the image using FEED_URIS variable:
+<screen>
+FEED_URIS = "\
+        feed1##http://some-server.org/feed \
+        feed2##http://some-server.org/feed-another"
+</screen>
+FEED_URIS contains list of feed descriptors, separated by spaces, per OE conventions. Each descriptor
+consists of feed tag and feed URL, joined with "##". Feed tag 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 dir 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 structure however has OE-internal
+structure and subject to change at any time. So, 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 deploy dir usage. 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 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 will 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, when you will build an image, it will automatically contain feed configs
+for the deploy directory (as of time of writing, deploy directory was internally structured with
+per-arch subdirectories; so, there are generated several feed configs, one for each subdirectory).
+	    </para>
+	    
+        </section>
+
+        </section>
     </chapter>
 
     <chapter>