Re: [gentoo-dev] subversion.eclass

[Doug Klima <cardoe@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 1796 bytes --]

Doug Klima wrote:
> Bo Ørsted Andresen wrote:
>> For quite a while the KDE herd has had a modified version of 
>> subversion.eclass in the kde overlay. During that time we have added 
>> the following features to the eclass which we would like to put back 
>> in gentoo-x86 soon. Since the changes are fairly extensive we decided 
>> to send it to this list for review first.
>>
>> 1) ESVN_REVISION (before this people had to use ESVN_OPTIONS for this 
>> purpose).
>> 2) ESVN_OFFLINE which disables svn up.
>> 3) ESVN_UP_FREQ which uses GNU find to determine if the specified 
>> number of hours has passed and only do svn up if it has. This is 
>> currently used in the kde4svn-meta eclass for split kde ebuilds that 
>> use the same checkout of each module.
>> 4) ESCM_LOGDIR for logging which revisions packages get installed 
>> with. See [1]. Users need to explicitly enable this feature to use it.
>>
>> Other than this the eclass has been documented for use with 
>> eclass-manpages.
>>
>> [1] http://thread.gmane.org/gmane.linux.gentoo.devel/54233
>>
>>   
> ok. Well zlin and I have been talking lately and we've hammered out 
> his proposed changes and mine. I'm attaching a patch for the first set 
> of changes I have proposed.
>
> Attached is a patch for the following:
> - use $ECLASS
> - adding rsync to deps
> - fixing some quoting
> - remove multiple subshell calls and problematic to upper usage (bug 
> #s escape me right now)
> - provide some more information about the working copy that will be 
> used in the future.
> - supporting svn switch
>
> The most important being the svn switch functionality.
>
> Please review for commit.
And the eclass-manpages documentation broken out into it's own patch.

Please review for commit.

[-- Attachment #2: subversion-manpage-02.patch --]
[-- Type: text/x-patch, Size: 5818 bytes --]

--- subversion.eclass	2008-02-19 14:35:10.000000000 -0500
+++ subversion-2.eclass	2008-02-19 16:34:15.000000000 -0500
@@ -2,18 +2,18 @@
 # Distributed under the terms of the GNU General Public License v2
 # $Header: /var/cvsroot/gentoo-x86/eclass/subversion.eclass,v 1.45 2008/02/17 07:59:06 hattya Exp $
 
-## --------------------------------------------------------------------------- #
-# Author: Akinori Hattori <hattya@gentoo.org>
+# @ECLASS: subversion.eclass
+# @MAINTAINER:
+# Akinori Hattori <hattya@gentoo.org>
+# Doug Klima <cardoe@gentoo.org>
+#
+# Original Author: Akinori Hattori <hattya@gentoo.org>
+# @BLURB: The subversion eclass is used to fetch sources from subversion repos
+# @DESCRIPTION:
+# The subversion eclass provides functions to fetch (checkout, update, and
+# switch), patch and bootstrap sources from subversion repositories.
 #
-# The subversion eclass is written to fetch the software sources from
-# subversion repositories like the cvs eclass.
-#
-#
-# Description:
-#   If you use this eclass, the ${S} is ${WORKDIR}/${P}.
-#   It is necessary to define the ESVN_REPO_URI variable at least.
-#
-## --------------------------------------------------------------------------- #
+# You must define ESVN_REPO_URI before inheriting this eclass.
 
 inherit eutils
 
@@ -23,39 +23,47 @@
 
 DESCRIPTION="Based on the ${ECLASS} eclass"
 
-## -- add subversion in DEPEND
+## -- add subversion and rsync in DEPEND
 #
 DEPEND="dev-util/subversion
 	net-misc/rsync"
 
-## -- ESVN_STORE_DIR:  subversion sources store directory
-#
+# @ECLASS-VARIABLE: ESVN_STORE_DIR
+# @DESCRIPTION:
+# subversion sources store directory. Users may overright this by defining this
+# variable in /etc/make.conf
 [ -z "${ESVN_STORE_DIR}" ] && ESVN_STORE_DIR="${PORTAGE_ACTUAL_DISTDIR:-${DISTDIR}}/svn-src"
 
 
-## -- ESVN_FETCH_CMD:  subversion fetch command
+# @ECLASS-VARIABLE: ESVN_FETCH_CMD
+# @DESCRIPTION:
+# subversion checkout command
 #
 ESVN_FETCH_CMD="svn checkout"
 
-## -- ESVN_UPDATE_CMD:  subversion update command
-#
+# @ECLASS-VARIABLE: ESVN_UPDATE_CMD
+# @DESCRIPTION:
+# subversion update command
 ESVN_UPDATE_CMD="svn update"
 
-## -- ESVN_SWITCH_CMD: subversion switch command
-#
+# @ECLASS-VARIABLE: ESVN_SWITCH_CMD
+# @DESCRIPTION:
+# subversion switch command
 ESVN_SWITCH_CMD="svn switch"
 
 
-## -- ESVN_OPTIONS:
-#
-# the options passed to checkout or update.
-#
+# @ECLASS-VARIABLE: ESVN_OPTIONS
+# @DESCRIPTION:
+# the options passed to checkout, update or switch.
+# Not meant for -r REV, see ESVN_REPO_URI
 : ${ESVN_OPTIONS:=}
 
 
-## -- ESVN_REPO_URI:  repository uri
+# @ECLASS-VARIABLE: ESVN_REPO_URI
+# @DESCRIPTION:
+# repository uri
 #
-# e.g. http://foo/trunk, svn://bar/trunk
+# e.g. http://foo/trunk, svn://bar/trunk, svn://bar/branch/foo@1234
 #
 # supported protocols:
 #   http://
@@ -63,10 +71,14 @@
 #   svn://
 #   svn+ssh://
 #
+# to peg to a specific revision, append @REV to the repo's uri
+#
 : ${ESVN_REPO_URI:=}
 
 
-## -- ESVN_PROJECT:  project name of your ebuild (= name space)
+# @ECLASS-VARIABLE: ESVN_PROJECT
+# @DESCRIPTION:
+# project name of your ebuild (= name space)
 #
 # subversion eclass will check out the subversion repository like:
 #
@@ -89,15 +101,15 @@
 : ${ESVN_PROJECT:=${PN/-svn}}
 
 
-## -- ESVN_BOOTSTRAP:
-#
+# @ECLASS-VARIABLE: ESVN_BOOTSTRAP
+# @DESCRIPTION:
 # bootstrap script or command like autogen.sh or etc..
 #
 : ${ESVN_BOOTSTRAP:=}
 
 
-## -- ESVN_PATCHES:
-#
+# @ECLASS-VARIABLE: ESVN_PATCHES
+# @DESCRIPTION:
 # subversion eclass can apply pathces in subversion_bootstrap().
 # you can use regexp in this variable like *.diff or *.patch or etc.
 # NOTE: patches will be applied before ESVN_BOOTSTRAP is processed.
@@ -110,8 +122,8 @@
 : ${ESVN_PATCHES:=}
 
 
-## -- ESVN_RESTRICT:
-#
+# @ECLASS-VARIABLE: ESVN_RESTRICT
+# @DESCRIPTION:
 # this should be a space delimited list of subversion eclass features to
 # restrict.
 #   export)
@@ -120,10 +132,14 @@
 : ${ESVN_RESTRICT:=}
 
 
-## -- subversion_fetch() ----------------------------------------------------- #
+# @FUNCTION: subversion_fetch
+# @USAGE: [repo_uri] [destination]
+# @DESCRIPTION:
+# Function to fetch sources from subversion via svn checkout, svn update, or
+# svn switch, depending on if have a working copy in $ESVN_STORE_DIR
 #
-# @param $1 - a repository URI. default is the ESVN_REPO_URI.
-# @param $2 - a check out path in S.
+# repo_uri 		- a repository URI. default is the ESVN_REPO_URI.
+# destination 	- a check out path in S.
 #
 function subversion_fetch() {
 
@@ -222,8 +238,9 @@
 }
 
 
-## -- subversion_bootstrap() ------------------------------------------------ #
-#
+# @ECLASS-VARIABLE: subversion_bootstrap
+# @DESCRIPTION:
+# Apply patches from $ESVN_PATCHES and run $ESVN_BOOTSTRAP as specified
 function subversion_bootstrap() {
 
 	if has "export" ${ESVN_RESTRICT}; then
@@ -275,8 +292,9 @@
 }
 
 
-## -- subversion_src_unpack() ------------------------------------------------ #
-#
+# @FUNCTION: subversion_src_unpack
+# @DESCRIPTION:
+# default src-Unpack. fetches and bootstraps
 function subversion_src_unpack() {
 
 	subversion_fetch     || die "${ESVN}: unknown problem occurred in subversion_fetch."
@@ -285,18 +303,13 @@
 }
 
 
-## -- subversion_wc_info() --------------------------------------------------- #
-#
+# @FUNCTION: subversion_wc_info
+# @USAGE: [repo_uri]
+# @DESCRIPTION:
 # the working copy information on the specified repository URI are set to
 # ESVN_WC_* variables.
-#
-# the available variables:
-#   ESVN_WC_URL
-#   ESVN_WC_REVISION
-#   ESVN_WC_PATH
-#
-# @param $1 - repository URI. default is ESVN_REPO_URI.
-#
+# @RETURN: ESVN_WC_URL, ESVN_WC_ROOT, ESVN_WC_UUID, ESVN_WC_REVISION, and
+# ESVN_WC_PATH
 function subversion_wc_info() {
 
 	local repo_uri="$(subversion__get_repository_uri "${1}")"