aboutsummaryrefslogtreecommitdiff
path: root/doc/configuration/syncers.html.part.in
blob: aeaec11f1a1c65b57261b2986ffb0cbc0677679b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<!-- 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 e 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>cave print-sync-protocols</code> and <code>cave
    sync-protocol-options</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). Syncers may be located in any of the following directories:

<ul>
    <li><code><em>confdir</em>/syncers/</code>, where
    <code><em>confdir</em></code> is the directory in which <code>use.conf</code>
    et al. reside.</li>

    <li><code><em>DATADIR</em>/paludis/syncers/</code>. On most
    systems, <code><em>DATADIR</em></code> is <code>/usr/share</code>.</li>

    <li><code><em>LIBEXECDIR</em>/paludis/syncers/</code>. On most
    systems, <code><em>LIBEXECDIR</em></code> is <code>/usr/libexec</code>.</li>
</ul>

<p>Paludis places its own syncers in
<code><em>LIBEXECDIR</em>/syncers/<em>doproto</em></code>. This directory is
not for end user use.</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>