path: root/doc/configuration/syncers.html.part.in
diff options
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 /doc/configuration/syncers.html.part.in
parent5a59baf6f8273c97533f03ceaa67d4e0ecca2d0b (diff)
More fetchers, syncers
Diffstat (limited to 'doc/configuration/syncers.html.part.in')
1 files changed, 49 insertions, 0 deletions
diff --git a/doc/configuration/syncers.html.part.in b/doc/configuration/syncers.html.part.in
new file mode 100644
index 000000000..14b24c879
--- /dev/null
+++ b/doc/configuration/syncers.html.part.in
@@ -0,0 +1,49 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+<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
+<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>
+ <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>
+<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>