ebuild-writing/functions/src_unpack/vcs-sources/text.xml


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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

<?xml version="1.0" encoding="UTF-8"?>
<guide self="ebuild-writing/functions/src_unpack/vcs-sources/">
<chapter>
<title>Version Control System (VCS) sources</title>
<body>

<p>
Rather than working with a source tarball, it is possible to use upstream
source code repositories directly. This can be useful when there is a need to
test unreleased snapshots on a regular basis. A number of eclasses exists for
this purpose; see their documentation for a list of available functions and
variables.
</p>

<ul>
  <li><uri link="::eclass-reference/cvs.eclass/"/></li>
  <li><uri link="::eclass-reference/darcs.eclass/"/></li>
  <li><uri link="::eclass-reference/git-r3.eclass/"/></li>
  <li><uri link="::eclass-reference/mercurial.eclass/"/></li>
  <li><uri link="::eclass-reference/subversion.eclass/"/></li>
</ul>

<note>
VCS ebuilds must be with empty <c>KEYWORDS</c> but <e>not</e> package.masked
(except if the mask is for an independent reason). Usually the <c>KEYWORDS</c>
line should be omitted altogether. This applies to "live" ebuilds (<c>-9999</c>)
and to ebuilds that extract a static revision but still use a version control
system for fetching.
</note>

</body>

<section>
<title>Disadvantages of VCS sources</title>
<body>

<p>
Note that VCS ebuilds should <b>not</b> generally be added to the tree for the
following reasons:
</p>

<ul>
  <li>
    Upstream VCS servers tend to be far less reliable than our mirroring
    system.
  </li>
  <li>
    VCS ebuilds create a very heavy server load <d/> not only are repositories
    not mirrored, but fetching sources from them is considerably more work for
    a server than simply serving up a file via HTTP or FTP.
  </li>
  <li>
    Local copies of a repository are several times larger than a tarball of the
    same sources, and tend to grow over time because they include the history.
  </li>
  <li>
    Many users who are behind strict firewalls cannot use protocols like CVS.
  </li>
</ul>

<p>
It is safer (and better for the user) to make a snapshot instead. For example,
<c>app-editors/emacs</c> snapshots are made using:
</p>

<pre>
$ git archive --prefix=emacs/ HEAD | xz &gt; emacs-${PV}.tar.xz
</pre>

</body>
</section>

<section>
<title>Disadvantages of VCS live sources</title>
<body>

<p>
VCS ebuilds that work against the latest head (or tip) rather than a specific
date or revision are even worse candidates for tree inclusion:
</p>

<ul>
  <li>
    You can never be sure whether upstream's source will actually build at any
    given point; which will most likely cause QA issues.
  </li>
  <li>
    It is extremely difficult to track down bugs when you cannot install the
    same version of a package as the reporter.
  </li>
  <li>
    Many upstream package maintainers tend to get upset if people aren't using
    a specific released version.
  </li>
</ul>

</body>
</section>
</chapter>
</guide>