[pkgsrc/trunk]: pkgsrc Add new metadata: PREV_PKGPATH and SUPERSEDES.

[reed <reed%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/d2cb90603d73
branches:  trunk
changeset: 392533:d2cb90603d73
user:      reed <reed%pkgsrc.org@localhost>
date:      Sat May 02 16:14:37 2009 +0000

description:
Add new metadata: PREV_PKGPATH and SUPERSEDES.
These will be available from pkg_summary(5) database.
To be used to find previous packages when a package is moved
or renamed. (Even though that is not recommended.)

Documented in pkgsrc Guide and in the pkg_summary(5) manual page.

Upcoming commit will have some packages modified to add them.

diffstat:

 doc/guide/files/submit.xml                   |  43 +++++++++++++++++++++++++++-
 mk/flavor/pkg/metadata.mk                    |   8 ++++-
 pkgtools/pkg_install/files/info/show.c       |   6 ++-
 pkgtools/pkg_install/files/lib/pkg_summary.5 |  14 +++++++-
 pkgtools/pkg_install/files/lib/version.h     |   4 +-
 5 files changed, 67 insertions(+), 8 deletions(-)

diffs (175 lines):

diff -r 85a9c1defcd0 -r d2cb90603d73 doc/guide/files/submit.xml
--- a/doc/guide/files/submit.xml        Sat May 02 15:03:47 2009 +0000
+++ b/doc/guide/files/submit.xml        Sat May 02 16:14:37 2009 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: submit.xml,v 1.19 2007/08/15 06:33:46 rillig Exp $ -->
+<!-- $NetBSD: submit.xml,v 1.20 2009/05/02 16:14:37 reed Exp $ -->
 
 <chapter id="submit"> <?dbhtml filename="submit.html"?>
 <title>Submitting and Committing</title>
@@ -149,9 +149,37 @@
   stability is to be preferred above new and possibly untested features.</para>
 </sect1>
 
+<sect1 id="renaming-package">
+<title>Renaming a package in pkgsrc</title>
+
+<para>Renaming packages is not recommended.</para>
+
+
+<para>When renaming packages, be sure to fix any references to old name
+  in other Makefiles, options, buildlink files, etc.</para>
+
+<para>Also When renaming a package, please define
+  <varname>SUPERSEDES</varname> to the package name and dewey version
+  pattern(s) of the previous package name.
+  This may be repeated for multiple renames.
+  The new package would be an exact replacement.
+</para>
+
+<para>Note that <quote>successor</quote> in the
+  CHANGES-<replaceable>YYYY</replaceable> file doesn't necessarily
+  mean that it <emphasis>supersedes</emphasis>, as that successor may
+  not be an exact replacement but is a suggestion for the replaced
+  functionality.</para>
+
+</sect1>
+
 <sect1 id="moving-package">
 <title>Moving a package in pkgsrc</title>
 
+<para>It is preferred that packages are not renamed or moved, but if needed
+  please follow these steps.
+</para>
+
 <orderedlist>
 <listitem><para>Make a copy of the directory somewhere else.</para></listitem>
 
@@ -166,6 +194,19 @@
 instead of <quote>../../category/package</quote>.</para>
 </listitem>
 
+<listitem><para>In the modified package's Makefile, consider setting
+<varname>PREV_PKGPATH</varname> to the previous category/package
+pathname.  The <varname>PREV_PKGPATH</varname> can be used by tools
+for doing an update using pkgsrc building; for example, it can
+search the &man.pkg.summary.5; database for <varname>PREV_PKGPATH</varname>
+(if no <varname>SUPERSEDES</varname>) and then use the corresponding
+new <varname>PKGPATH</varname> for that moved package.  Note that
+it may have multiple matches, so the tool should also check on the
+<varname>PKGBASE</varname> too.  The <varname>PREV_PKGPATH</varname>
+probably has no value unless <varname>SUPERSEDES</varname> is not
+set, i.e.  <varname>PKGBASE</varname> stays the same.  </para>
+</listitem>
+
 <listitem><para><command>cvs import</command> the modified package in the new
 place.</para></listitem>
 
diff -r 85a9c1defcd0 -r d2cb90603d73 mk/flavor/pkg/metadata.mk
--- a/mk/flavor/pkg/metadata.mk Sat May 02 15:03:47 2009 +0000
+++ b/mk/flavor/pkg/metadata.mk Sat May 02 16:14:37 2009 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: metadata.mk,v 1.30 2008/05/21 20:39:52 abs Exp $
+# $NetBSD: metadata.mk,v 1.31 2009/05/02 16:14:37 reed Exp $
 
 ######################################################################
 ### The targets below are all PRIVATE.
@@ -47,6 +47,12 @@
 .if defined(OWNER)
        ${RUN}${ECHO} "OWNER=${OWNER}" >> ${.TARGET}.tmp
 .endif 
+.if defined(PREV_PKGPATH)
+       ${RUN}${ECHO} "PREV_PKGPATH=${PREV_PKGPATH}" >> ${.TARGET}.tmp
+.endif
+.if defined(SUPERSEDES)
+       ${RUN}${ECHO} "SUPERSEDES=${SUPERSEDES}" >> ${.TARGET}.tmp
+.endif
        ${RUN}${ECHO} "BUILD_DATE=${_BUILD_DATE_cmd:sh}" >> ${.TARGET}.tmp
        ${RUN}${ECHO} "BUILD_HOST=${_BUILD_HOST_cmd:sh}" >> ${.TARGET}.tmp
 .if !empty(CHECK_SHLIBS_SUPPORTED:M[yY][eE][sS])
diff -r 85a9c1defcd0 -r d2cb90603d73 pkgtools/pkg_install/files/info/show.c
--- a/pkgtools/pkg_install/files/info/show.c    Sat May 02 15:03:47 2009 +0000
+++ b/pkgtools/pkg_install/files/info/show.c    Sat May 02 16:14:37 2009 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: show.c,v 1.28 2009/04/24 14:00:25 joerg Exp $  */
+/*     $NetBSD: show.c,v 1.29 2009/05/02 16:14:37 reed Exp $   */
 
 #if HAVE_CONFIG_H
 #include "config.h"
@@ -7,7 +7,7 @@
 #if HAVE_SYS_CDEFS_H
 #include <sys/cdefs.h>
 #endif
-__RCSID("$NetBSD: show.c,v 1.28 2009/04/24 14:00:25 joerg Exp $");
+__RCSID("$NetBSD: show.c,v 1.29 2009/05/02 16:14:37 reed Exp $");
 
 /*
  * FreeBSD install - a package for the installation and maintainance
@@ -334,6 +334,8 @@
                "HOMEPAGE",
                "PKGTOOLS_VERSION",
                "BUILD_DATE",
+               "PREV_PKGPATH",
+               "SUPERSEDES",
                NULL
        };
        
diff -r 85a9c1defcd0 -r d2cb90603d73 pkgtools/pkg_install/files/lib/pkg_summary.5
--- a/pkgtools/pkg_install/files/lib/pkg_summary.5      Sat May 02 15:03:47 2009 +0000
+++ b/pkgtools/pkg_install/files/lib/pkg_summary.5      Sat May 02 16:14:37 2009 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pkg_summary.5,v 1.8 2009/02/08 23:12:05 wiz Exp $
+.\"    $NetBSD: pkg_summary.5,v 1.9 2009/05/02 16:14:37 reed Exp $
 .\"
 .\" Copyright (c) 2006 The NetBSD Foundation
 .\"
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd August 29, 2007
+.Dd April 11, 2009
 .Dt PKG_SUMMARY 5
 .Os
 .Sh NAME
@@ -94,6 +94,12 @@
 (required) The path of the package directory within pkgsrc.
 .It Ev PKGTOOLS_VERSION
 (required) The version of the package tools used to create the package.
+.It Ev PREV_PKGPATH
+(optional) The previous path of the package directory within pkgsrc when
+a package was moved.
+(See
+.Ev SUPERSEDES
+below for a renamed package.)
 .It Ev PROVIDES
 (optional) A list of shared libraries provided by the package,
 including major version number, one per line.
@@ -104,6 +110,10 @@
 If missing, this package does not require shared libraries.
 .It Ev SIZE_PKG
 (required) The size of the package when installed, in bytes.
+.It Ev SUPERSEDES
+(optional) A list of dewey patterns of previous packages this
+package replaces, one per line.
+This is used for package renaming.
 .El
 .Pp
 The
diff -r 85a9c1defcd0 -r d2cb90603d73 pkgtools/pkg_install/files/lib/version.h
--- a/pkgtools/pkg_install/files/lib/version.h  Sat May 02 15:03:47 2009 +0000
+++ b/pkgtools/pkg_install/files/lib/version.h  Sat May 02 16:14:37 2009 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: version.h,v 1.125 2009/04/25 21:31:14 joerg Exp $      */
+/*     $NetBSD: version.h,v 1.126 2009/05/02 16:14:37 reed Exp $       */
 
 /*
  * Copyright (c) 2001 Thomas Klausner.  All rights reserved.
@@ -27,6 +27,6 @@
 #ifndef _INST_LIB_VERSION_H_
 #define _INST_LIB_VERSION_H_
 
-#define PKGTOOLS_VERSION "20090425"
+#define PKGTOOLS_VERSION "20090502"
 
 #endif /* _INST_LIB_VERSION_H_ */