ebuild-writing/functions/src_unpack/vcs-sources: New file.

cvs-sources and svn-sources contain duplicate information, and it also applies to other VCSs. Combine them in a single chapter. Signed-off-by: Ulrich Müller <ulm@gentoo.org>
author: Ulrich Müller <ulm@gentoo.org> 2020-02-22 20:05:56 +0100
committer: Ulrich Müller <ulm@gentoo.org> 2020-02-22 20:13:37 +0100
commit: 7141404e5ff9fad19e7297b078d6852ff19f7b10 (patch)
tree: ce32bb9c1b347bfc385007229f62287af3148c52
parent: Sync example phase functions from PMS. (diff)
download: devmanual-7141404e5ff9fad19e7297b078d6852ff19f7b10.tar.gz
devmanual-7141404e5ff9fad19e7297b078d6852ff19f7b10.tar.bz2
devmanual-7141404e5ff9fad19e7297b078d6852ff19f7b10.zip
7 files changed, 287 insertions, 311 deletions
diff --git a/appendices/contributors/text.xml b/appendices/contributors/text.xml
index 628346d..580c5fd 100644
--- a/appendices/contributors/text.xml
+++ b/appendices/contributors/text.xml
@@ -23,7 +23,7 @@ This page lists the contributions to the Gentoo Development Guide:
 </author>
 <author name="Tom Martin" email="slarti@gentoo.org">
   <uri link="::appendices/editor-configuration/emacs"/>,
-  <uri link="::ebuild-writing/functions/src_unpack/svn-sources"/>,
+  <uri link="::ebuild-writing/functions/src_unpack/vcs-sources/#Using Subversion Sources"/>,
   <uri link="::general-concepts/use-flags/#Conflicting USE Flags"/>
 </author>
 <author name="Paul Varner" email="fuzzyray@gentoo.org">
diff --git a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml b/ebuild-writing/functions/src_unpack/cvs-sources/text.xml
deleted file mode 100644
index 6f00270..0000000
--- a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml
+++ /dev/null
@@ -1,190 +0,0 @@
-<?xml version="1.0"?>
-<guide self="ebuild-writing/functions/src_unpack/cvs-sources/">
-<chapter>
-<title>CVS Sources</title>
-
-<body>
-<p>
-Rather than working with a source tarball, it is possible to use
-upstream's CVS server directly. This can be useful when there is a
-need to test unreleased snapshots on a regular basis.
-</p>
-</body>
-
-<section>
-<title>Disadvantages of CVS Sources</title>
-<body>
-
-<p>
-Note that CVS ebuilds should <b>not</b> generally be added to the tree
-for the following reasons:
-</p>
-
-<ul>
-  <li>
-  Upstream CVS servers tend to be far less reliable than our mirroring
-  system.
-  </li>
-  <li>
-  CVS ebuilds create a very heavy server load <d/> not only is CVS not
-  mirrored, but allowing a CVS checkout is considerably more work for
-  a server than simply serving up a file via HTTP or FTP.
-  </li>
-  <li>
-  Many users who are behind strict firewalls cannot use CVS.
-  </li>
-</ul>
-
-<p>
-It is safer to make a snapshot instead. For example, vim snapshots are made using:
-</p>
-
-<pre>
-$ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim
-</pre>
-</body>
-</section>
-
-<section>
-<title>Disadvantages of CVS Live Sources</title>
-<body>
-
-<p>
-CVS ebuilds which work against CVS <c>HEAD</c> 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 CVS 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>
-
-<section>
-<title>Using CVS Sources</title>
-<body>
-
-<note>
-CVS ebuilds must be either with empty <c>KEYWORDS</c> or
-package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are
-strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and
-to ebuilds that extract a static revision but still use CVS for
-fetching.
-</note>
-
-<p>
-To use a CVS source, <c>cvs.eclass</c> must be inherited, and then a
-number of variables must be set. The following variables are often
-useful:
-</p>
-
-<table>
-  <tr>
-    <th>Variable</th>
-    <th>Purpose</th>
-    <th>Example</th>
-  </tr>
-  <tr>
-    <ti><c>ECVS_SERVER</c></ti>
-    <ti>Server and path</ti>
-    <ti><c>"cvs.sourceforge.net:/cvsroot/vim"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ECVS_MODULE</c></ti>
-    <ti>Module</ti>
-    <ti><c>"vim"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ECVS_BRANCH</c></ti>
-    <ti>Branch</ti>
-    <ti><c>"HEAD"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ECVS_AUTH</c></ti>
-    <ti>Auth method</ti>
-    <ti><c>"ext"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ECVS_USER</c></ti>
-    <ti>Username</ti>
-    <ti><c>"anoncvs"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ECVS_PASS</c></ti>
-    <ti>Password</ti>
-    <ti><c>""</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ECVS_TOP_DIR</c></ti>
-    <ti>Unpack location</ti>
-    <ti><c>"${DISTDIR}/cvs-src/${ECVS_MODULE}"</c></ti>
-  </tr>
-</table>
-
-<p>
-See the eclass itself for the full range of options. To perform the
-actual checkout, use the <c>cvs_src_unpack</c> function.
-</p>
-
-<p>
-Here's a simple example, based upon the CVS options in vim.eclass:
-</p>
-
-<codesample lang="ebuild">
-inherit cvs
-
-SRC_URI=""
-
-src_unpack() {
-	ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim"
-	ECVS_USER="anonymous"
-	ECVS_PASS=""
-	ECVS_AUTH="pserver"
-	if [[ $(get_major_version ) -ge 7 ]] ; then
-		ECVS_MODULE="vim7"
-	else
-		ECVS_MODULE="vim"
-	fi
-	ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}"
-	cvs_src_unpack
-}
-</codesample>
-
-<p>
-Here's another approach, based upon the <c>emacs-cvs</c> ebuild, which
-relies upon the default <c>src_unpack</c> provided in the eclass; this
-approach is simpler but less flexible:
-</p>
-
-<codesample lang="ebuild">
-inherit cvs
-
-ECVS_AUTH="ext"
-CVS_RSH="ssh"
-ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs"
-ECVS_MODULE="emacs"
-ECVS_BRANCH="emacs-unicode-2"
-ECVS_USER="anoncvs"
-ECVS_PASS=""
-ECVS_CVS_OPTIONS="-dP"
-
-# ...and so on. No src_unpack() is specified.
-</codesample>
-
-</body>
-</section>
-
-</chapter>
-</guide>
diff --git a/ebuild-writing/functions/src_unpack/svn-sources/text.xml b/ebuild-writing/functions/src_unpack/svn-sources/text.xml
deleted file mode 100644
index 5e0b2a8..0000000
--- a/ebuild-writing/functions/src_unpack/svn-sources/text.xml
+++ /dev/null
@@ -1,116 +0,0 @@
-<?xml version="1.0"?>
-<guide self="ebuild-writing/functions/src_unpack/svn-sources/">
-<chapter>
-<title>Subversion Sources</title>
-
-<body>
-<p>
-As with CVS, an eclass exists for working directly with upstream
-Subversion repositories. See <uri link="::eclass-reference/subversion.eclass/"/>
-for a full list of functions and variables. Also see
-the <uri link="::ebuild-writing/functions/src_unpack/cvs-sources"/> 
-section.
-</p>
-</body>
-
-<section>
-<title>Disadvantages of Subversion Sources</title>
-<body>
-
-<p>
-Note that Subversion ebuilds should <b>not</b> generally be added to
-the tree for much the same reasons that live CVS ebuilds should not (see
-<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>).
-Indeed, there should be even less impetus to add a live Subversion ebuild than a live CVS ebuild, as
-Subversion checkouts are roughly a factor of five larger than an
-equivalent CVS checkout.
-</p>
-
-<p>
-It is safer (and better for the user) to make a snapshot instead. For
-example, <c>gentoo-syntax</c> snapshots could be made using:
-</p>
-
-<pre>
-$ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax
-</pre>
-</body>
-</section>
-
-<section>
-<title>Using Subversion Sources</title>
-<body>
-
-<note>
-Subversion ebuilds must be either with empty <c>KEYWORDS</c> or
-package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are
-strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and
-to ebuilds that extract a static revision but still use Subversion for
-fetching.
-</note>
-
-<p>
-To use a Subversion source, <c>subversion.eclass</c> must be
-inherited, and then at least <c>ESVN_REPO_URI</c> must be set. The
-following variables are also noteworthy:
-</p>
-
-<table>
-  <tr>
-    <th>Variable</th>
-    <th>Purpose</th>
-    <th>Example</th>
-  </tr>
-  <tr>
-    <ti><c>ESVN_REPO_URI</c></ti>
-    <ti>Server and path (http, https, svn)</ti>
-    <ti><c>"svn://svn.example.com/foobar/trunk"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ESVN_STORE_DIR</c></ti>
-    <ti>Unpack location</ti>
-    <ti><c>ESVN_STORE_DIR="${DISTDIR}/svn-src"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ESVN_PROJECT</c></ti>
-    <ti>Project name of ebuild</ti>
-    <ti><c>ESVN_PROJECT="${PN/-svn}"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ESVN_BOOTSTRAP</c></ti>
-    <ti>Bootstrap command or script</ti>
-    <ti><c>ESVN_BOOTSTRAP="autogen.sh"</c></ti>
-  </tr>
-  <tr>
-    <ti><c>ESVN_PATCHES</c></ti>
-    <ti>Patches to apply during bootstrap</ti>
-    <ti><c>ESVN_PATCHES="${FILESDIR}/*.patch"</c></ti>
-  </tr>
-</table>
-
-<p>
-See the eclass itself and <uri link="::eclass-reference/subversion.eclass/"/>
-for the full range of options. To perform the actual checkout, use
-the <c>subversion_src_unpack</c> function, which calls
-both <c>subversion_svn_fetch</c> and <c>subversion_bootstrap</c>
-itself.
-</p>
-
-<p>
-Here is a simple example, based upon the Subversion options in
-<c>litu-svn-20040902.ebuild</c>; this approach is sufficient for most
-Subversion ebuilds:
-</p>
-
-<codesample lang="ebuild">
-inherit subversion
-
-ESVN_REPO_URI="https://tao.uab.es/ion/svn/libtu/trunk"
-ESVN_PROJECT="libtu-snapshot"
-</codesample>
-
-</body>
-</section>
-
-</chapter>
-</guide>
diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml
index 862a41e..9c5f777 100644
--- a/ebuild-writing/functions/src_unpack/text.xml
+++ b/ebuild-writing/functions/src_unpack/text.xml
@@ -125,8 +125,7 @@ The following subsections cover different topics which often occur when writing
 
 </chapter>
 
-<include href="cvs-sources/"/>
-<include href="svn-sources/"/>
+<include href="vcs-sources/"/>
 <include href="rpm-sources/"/>
 <include href="other-formats/"/>
 </guide>
diff --git a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml
new file mode 100644
index 0000000..094ec49
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml
@@ -0,0 +1,283 @@
+<?xml version="1.0"?>
+<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/bzr.eclass/"/></li>
+  <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 either with empty <c>KEYWORDS</c> or package.masked
+(but <e>not</e> both). Empty <c>KEYWORDS</c> are strongly preferred.
+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>
+
+<section>
+<title>Using CVS Sources</title>
+<body>
+
+<p>
+To use a CVS source, <c>cvs.eclass</c> must be inherited, and then a number of
+variables must be set. The following variables are often useful:
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <ti><c>ECVS_SERVER</c></ti>
+    <ti>Server and path</ti>
+    <ti><c>"cvs.sourceforge.net:/cvsroot/vim"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ECVS_MODULE</c></ti>
+    <ti>Module</ti>
+    <ti><c>"vim"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ECVS_BRANCH</c></ti>
+    <ti>Branch</ti>
+    <ti><c>"HEAD"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ECVS_AUTH</c></ti>
+    <ti>Auth method</ti>
+    <ti><c>"ext"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ECVS_USER</c></ti>
+    <ti>Username</ti>
+    <ti><c>"anoncvs"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ECVS_PASS</c></ti>
+    <ti>Password</ti>
+    <ti><c>""</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ECVS_TOP_DIR</c></ti>
+    <ti>Unpack location</ti>
+    <ti><c>"${DISTDIR}/cvs-src/${ECVS_MODULE}"</c></ti>
+  </tr>
+</table>
+
+<p>
+See the eclass itself for the full range of options. To perform the actual
+checkout, use the <c>cvs_src_unpack</c> function.
+</p>
+
+<p>
+Here's a simple example, based upon the CVS options in vim.eclass:
+</p>
+
+<codesample lang="ebuild">
+inherit cvs
+
+SRC_URI=""
+
+src_unpack() {
+	ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim"
+	ECVS_USER="anonymous"
+	ECVS_PASS=""
+	ECVS_AUTH="pserver"
+	if [[ $(get_major_version ) -ge 7 ]] ; then
+		ECVS_MODULE="vim7"
+	else
+		ECVS_MODULE="vim"
+	fi
+	ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}"
+	cvs_src_unpack
+}
+</codesample>
+
+<p>
+Here's another approach, based upon the <c>emacs-cvs</c> ebuild, which relies
+upon the default <c>src_unpack</c> provided in the eclass; this approach is
+simpler but less flexible:
+</p>
+
+<codesample lang="ebuild">
+inherit cvs
+
+ECVS_AUTH="ext"
+CVS_RSH="ssh"
+ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs"
+ECVS_MODULE="emacs"
+ECVS_BRANCH="emacs-unicode-2"
+ECVS_USER="anoncvs"
+ECVS_PASS=""
+ECVS_CVS_OPTIONS="-dP"
+
+# ...and so on. No src_unpack() is specified.
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Using Git Sources</title>
+<body>
+
+<todo>
+Write this section.
+</todo>
+
+</body>
+</section>
+
+<section>
+<title>Using Subversion Sources</title>
+<body>
+
+<p>
+To use a Subversion source, <c>subversion.eclass</c> must be inherited, and
+then at least <c>ESVN_REPO_URI</c> must be set. The following variables are
+also noteworthy:
+</p>
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Purpose</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <ti><c>ESVN_REPO_URI</c></ti>
+    <ti>Server and path (http, https, svn)</ti>
+    <ti><c>"svn://svn.example.com/foobar/trunk"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ESVN_STORE_DIR</c></ti>
+    <ti>Unpack location</ti>
+    <ti><c>ESVN_STORE_DIR="${DISTDIR}/svn-src"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ESVN_PROJECT</c></ti>
+    <ti>Project name of ebuild</ti>
+    <ti><c>ESVN_PROJECT="${PN/-svn}"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ESVN_BOOTSTRAP</c></ti>
+    <ti>Bootstrap command or script</ti>
+    <ti><c>ESVN_BOOTSTRAP="autogen.sh"</c></ti>
+  </tr>
+  <tr>
+    <ti><c>ESVN_PATCHES</c></ti>
+    <ti>Patches to apply during bootstrap</ti>
+    <ti><c>ESVN_PATCHES="${FILESDIR}/*.patch"</c></ti>
+  </tr>
+</table>
+
+<p>
+See the eclass itself and <uri link="::eclass-reference/subversion.eclass/"/>
+for the full range of options. To perform the actual checkout, use
+the <c>subversion_src_unpack</c> function, which calls
+both <c>subversion_svn_fetch</c> and <c>subversion_bootstrap</c>
+itself.
+</p>
+
+<p>
+Here is a simple example, based upon the Subversion options in
+<c>litu-svn-20040902.ebuild</c>; this approach is sufficient for most
+Subversion ebuilds:
+</p>
+
+<codesample lang="ebuild">
+inherit subversion
+
+ESVN_REPO_URI="https://tao.uab.es/ion/svn/libtu/trunk"
+ESVN_PROJECT="libtu-snapshot"
+</codesample>
+
+</body>
+</section>
+</chapter>
+</guide>
diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml
index 3899aca..a3e11d1 100644
--- a/ebuild-writing/functions/text.xml
+++ b/ebuild-writing/functions/text.xml
@@ -55,7 +55,7 @@ need (unless you're using live ebuilds).  Network access outside of
 this would not be cached locally (e.g. in <c>${DISTDIR}</c>, see
 <uri link="::ebuild-writing/variables#Predefined Read-Only Variables"/>),
 which makes it hard to have reproducible builds (see
-<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>).
+<uri link="::ebuild-writing/functions/src_unpack/vcs-sources/#Disadvantages of VCS Sources"/>).
 Avoid network access in any phase by using local files, extending
 <c>SRC_URI</c> (see
 <uri link="::ebuild-writing/variables#Ebuild-defined Variables"/>), etc.
diff --git a/keywording/text.xml b/keywording/text.xml
index fd8f155..92e71e2 100644
--- a/keywording/text.xml
+++ b/keywording/text.xml
@@ -93,7 +93,7 @@ Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds.
 
 <note>
 Usually, "live" ebuilds
-(see <uri link="::ebuild-writing/functions/src_unpack/cvs-sources"/>)
+(see <uri link="::ebuild-writing/functions/src_unpack/vcs-sources/"/>)
 do not specify a <c>KEYWORDS</c> variable, or assign the empty string to it.
 </note>
 </body>
author	Ulrich Müller <ulm@gentoo.org>	2020-02-22 20:05:56 +0100
committer	Ulrich Müller <ulm@gentoo.org>	2020-02-22 20:13:37 +0100
commit	7141404e5ff9fad19e7297b078d6852ff19f7b10 (patch)
tree	ce32bb9c1b347bfc385007229f62287af3148c52
parent	Sync example phase functions from PMS. (diff)
download	devmanual-7141404e5ff9fad19e7297b078d6852ff19f7b10.tar.gz devmanual-7141404e5ff9fad19e7297b078d6852ff19f7b10.tar.bz2 devmanual-7141404e5ff9fad19e7297b078d6852ff19f7b10.zip