aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-22 00:48:03 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-22 00:48:03 +0000
commit1d0eac945f63f29095f21e582ea61c9f5b45778d (patch)
tree2108784ef59ac9a0da335211926f63ade781f96a
parent5a59baf6f8273c97533f03ceaa67d4e0ecca2d0b (diff)
downloadpaludis-1d0eac945f63f29095f21e582ea61c9f5b45778d.tar.gz
paludis-1d0eac945f63f29095f21e582ea61c9f5b45778d.tar.xz
More fetchers, syncers
-rw-r--r--doc/configuration/fetchers.html.part.in31
-rw-r--r--doc/configuration/syncers.html.part.in49
2 files changed, 80 insertions, 0 deletions
diff --git a/doc/configuration/fetchers.html.part.in b/doc/configuration/fetchers.html.part.in
new file mode 100644
index 0000000..6946d1e
--- /dev/null
+++ b/doc/configuration/fetchers.html.part.in
@@ -0,0 +1,31 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>Fetchers</h1>
+
+<h2>Overview</h2>
+
+<p>Paludis makes use of scripts called 'fetchers' to do most downloading. Fetchers can be added for additional protocols
+(for example, if you need to use a third party ebuild where upstream distributes its sources via Gopher), and built-in
+fetchers can be replaced (for example, if you want to use something other than <code>wget</code> to fetch via http).</p>
+
+<h2>Standard Fetchers</h2>
+
+<p>Paludis ships with the following fetcher protocols:</p>
+
+<ul>
+###FETCHERS###
+</ul>
+
+<h2>User Defined Fetchers</h2>
+
+<p>To write your own fetcher for protocol <code>proto</code>, create an executable script named <code>doproto</code> (the
+<code>do</code> prefix is essential) and place it in <code>SHAREDIR/paludis/fetchers/</code>, where <code>SHAREDIR</code>
+is probably <code>/usr/share</code>. This directory has priority over the usual Paludis fetcher locations, so it can be
+used to override existing fetchers as well as creating new ones.</p>
+
+<p>A fetcher is called with two parameters, the source URI and the destination filename. It indicates success or failure
+via its exit status.</p>
+
+<p>For examples, consult the built-in ferchers, which can be found in <code>LIBEXECDIR/paludis/fetchers/</code>.</p>
+
+
diff --git a/doc/configuration/syncers.html.part.in b/doc/configuration/syncers.html.part.in
new file mode 100644
index 0000000..14b24c8
--- /dev/null
+++ b/doc/configuration/syncers.html.part.in
@@ -0,0 +1,49 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>Syncers</h1>
+
+<h2>Overview</h2>
+
+<p>Paludis makes use of scripts called 'syncers' to perform certain sync actions (e.g. handling <code>paludis
+ --sync</code> for ebuild format repositories). Some syncers support additional options that can be set via the
+<code>sync_options</code> repository configuration key. Syncers can be added for additional protocols (for example, if
+you need to use a repository that uses a weird version control system), and built-in syncers can be replaced (for
+example, if you want to use a non-standard program).</p>
+
+<p><strong>The syncer protocol used by Paludis is not always identical to the one used by the syncing program.</strong>
+In particular, several syncing programs support URIs in the form <code>http://</code>, and Paludis would not be able to
+tell whether such a URI should be synced by, say, Subversion, Git or Darcs. Instead, you must use
+<code>svn+http://</code> and so on.</p>
+
+<h2>Standard Syncers</h2>
+
+<p>Paludis ships with the following sync protocols (you can use <code>paludis --list-sync-protocols</code> to get the
+list yourself). Note that many of these syncers depend upon external programs that are not listed as dependencies for
+Paludis.</p>
+
+<pre>
+###SYNCERS###
+</pre>
+
+<h2>User Defined Syncers</h2>
+
+<p>To write your own syncer for protocol <code>proto</code>, create an executable script named <code>doproto</code> (the
+<code>do</code> prefix is essential) and place it in <code>SHAREDIR/paludis/syncers/</code>, where <code>SHAREDIR</code>
+is probably <code>/usr/share</code>. This directory has priority over the usual Paludis syncer locations, so it can be
+used to override existing syncers as well as creating new ones.</p>
+
+<p>A syncer script can be called in two ways:</p>
+
+<ul>
+ <li>With <code>--help</code> as an argument. When this happens, it must output a useful help message and then exit
+ without syncing anything.</li>
+ <li>With two arguments, the first being the local directory and the second being the remote sync URL. If
+ <code>sync_options</code> is used, its contents are also passed as arguments. Success or failure is indicated via
+ exit status.</li>
+</ul>
+
+<p>Many syncers use <code>source "${PALUDIS_EBUILD_DIR}/echo_functions.bash"</code> early on to get access to
+<code>ewarn</code> and friends.</p>
+
+<p>For examples, consult the built-in syncers, which can be found in <code>LIBEXECDIR/paludis/syncers/</code>.</p>
+