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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<?xml version="1.0"?>
<guide self="general-concepts/mirrors/">
<chapter>
<title>Mirrors</title>
<section>
<title>Automatic Mirroring</title>
<body>
<p>
Packages will automatically have their <c>SRC_URI</c> components mirrored onto
Gentoo mirrors, including those hosted on the official Gentoo
Infrastructure (i.e. developer space at <c>dev.gentoo.org</c>). When
fetching, package manager checks
Gentoo mirrors first before trying the original upstream location.
</p>
<p>
This is generally desired behaviour <d/> upstream mirrors are prone to being
rearranged, tidied out or having files modified.
</p>
</body>
<subsection>
<title>Restricting Automatic Mirroring</title>
<body>
<p>
Three <c>RESTRICT</c> keywords can be used to control the mirroring process.
</p>
<p>
The <c>RESTRICT="mirror"</c> setting should be used if we cannot legally mirror
certain files; files will still be downloaded from the original locations.
</p>
<p>
The <c>RESTRICT="primaryuri"</c> setting causes Portage to try
original locations <e>first</e>, and then fall back to mirrors if necessary.
This should not be used in new ebuilds.
</p>
<p>
There is also <c>RESTRICT="fetch"</c>, which prevents Portage from trying to
fetch anything manually. The <uri link="::ebuild-writing/functions/pkg_nofetch">
pkg_nofetch</uri> function will be called if any <c>SRC_URI</c> components cannot be
found. This should only be used if a license requires it.
</p>
</body>
</subsection>
<subsection>
<title>Replacing Automatically Mirrored Files</title>
<body>
<p>
On rare occasions you may need to replace a file that is already mirrored.
This is usually the case when upstream remakes a release package. If this
is necessary, please use <c>SRC_URI</c> arrow to rename the file. For example:
</p>
<codesample lang="ebuild">
# upstream updated the distfile in place, so suffix it with _YYYYMMDD
SRC_URI="https://example.com/badupstream/${P}.tar.gz -> ${P}_20191016.tar.gz"
</codesample>
<p>
Since Gentoo mirrors operate using local distfile names, they will automatically
fetch and start distributing the new version.
</p>
<p>
Please note that if upstream made any changes affecting the built
package, you need to also bump the ebuild's revision. Finally,
remember to remove the ebuilds that are associated with the old
distfile, or regenerate their checksums in <c>Manifest</c>, if there
are any. This is necessary because these ebuilds will cause checksum
mismatch errors as the checksum recorded in the Manifest file no
longer matches the computed checksum of the fetched distfile.
</p>
<p>
More general information about the internals of mirroring can be found on <uri
link="https://wiki.gentoo.org/wiki/Project:Infrastructure/Mirrors/Distfile_Mirroring_System">
Infrastructure project's Distfile Mirroring System page</uri>.
</p>
</body>
</subsection>
<subsection>
<title>Suitable Download Hosts</title>
<body>
<p>
If you have to host a source file (patch or tarball) yourself, as long as it
can be freely distributed (by license and legality), you're suggested to use
your developer's space at <c>dev.gentoo.org</c>. Since external overlays may
depend on your patches/tarballs, using the dev space at <c>dev.gentoo.org</c>
keeps the distfiles at a stable and reliable infrastructure. If you retire,
other developers can take over your distfiles and place them into their own
devspace.
</p>
<p>
Previous policy was to use <c>mirror://gentoo</c> directly, but this is now deprecated, as that
wouldn't allow to have long-term availability and traceability of the source files, which might be a
requirement of the license.
</p>
<p>
When you upload the file to <c>dev.gentoo.org:~/public_html</c>, you must ensure that it, and its
parent directories, are world-readable. An example <c>SRC_URI</c> referencing
a distfile mirrored this way is as follows:
</p>
<codesample lang="ebuild">
SRC_URI="https://dev.gentoo.org/~myname/distfiles/${P}.tar.gz"
</codesample>
<p>
where <c>myname</c> refers to the username of the developer.
</p>
</body>
</subsection>
</section>
<section>
<title>Gentoo Mirrors</title>
<body>
<p>
To manually upload a file to <c>mirror://gentoo</c>, <c>scp</c> it to
<c>dev.gentoo.org:/space/distfiles-local</c>. The file should appear
on the mirrors within four hours (note that this is <e>less
frequent</e> than <uri link="::general-concepts/git-to-rsync"/>).
If the upstream download location for a package uses a non-standard TCP port
(anything other than 21, 80 or 443), you <e>must</e> manually mirror the files. Not
doing so can cause all kinds of problems with strict firewalls.
</p>
</body>
</section>
<section>
<title>Mirroring Process</title>
<body>
<figure short="Mirroring Process" link="diagram.png"
caption="Diagram showing the mirroring process." />
</body>
</section>
<section>
<title>Third-party mirrors</title>
<body>
<p>
Usage of third-party mirrors and the <c>mirror://</c>
pseudo-protocol is described in the
<uri link="::ebuild-writing/variables/#Third-party mirrors"><c>SRC_URI</c>
variable documentation</uri>.
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb