* Make portdbapi.aux_get() automatically pull pre-generated metadata

  directly from the metadata/cache/ directory when metadata-transfer
  is not enabled in FEATURES. This makes all cache modules behave
  similar to existing metadata_overlay module, except when
  FEATURES="metadata-transfer" has been explicitly enabled.

* Remove metadata-transfer from FEATURES in make.globals so that it's
  no longer enabled by default. Users will be happy about this since
  the "Updating Portage cache" part of emerge --sync can be more time
  consuming than the rsync run itself. It's also nicer when when using
  PORTDIR over nfs or bind mounted in a chroot since there's no need
  to run emerge --metadata.

* Update FEATURES="metadata-transfer" docs to warn users of the rsync
  tree to modify eclases in PORTDIR_OVERLAY if necessary instead of
  doing it directly in the rsync tree.

* Relevant updates to /etc/portage/modules docs.

svn path=/main/trunk/; revision=9930

2 files changed, 19 insertions, 12 deletions

diff --git a/man/make.conf.5 b/man/make.conf.5
index a8476458b..46013fc5c 100644
--- a/man/make.conf.5
+++ b/man/make.conf.5
@@ -215,6 +215,16 @@ when \fImirror\fR is also in the \fBebuild\fR(5) \fBRESTRICT\fR variable.
 .TP
 .B metadata\-transfer
 Automatically perform a metadata transfer when `emerge \-\-sync` is run.
+In versions of portage greater than 2.1.5, this feature is disabled by
+default. When metadata\-transfer is disabled, metadata cache from the
+${PORTDIR}/metadata/cache/ directory will be used directly (if available)
+and eclasses in ${PORTDIR}/eclass/ must not be modified except by
+`emerge \-\-sync` operations since the cache validation mechanism
+will not recognize eclass modifications. Normally, this issue only
+pertains to users of the rsync tree since the cvs tree does not contain
+a metadata/cache/ directory. Users of the rsync tree who want to modify
+eclasses should use \fBPORTDIR_OVERLAY\fR in order for the cache
+validation mechanism to work correctly.
 .TP
 .B mirror
 Fetch everything in \fBSRC_URI\fR regardless of \fBUSE\fR settings,
diff --git a/man/portage.5 b/man/portage.5
index 0599c5e09..792491b8e 100644
--- a/man/portage.5
+++ b/man/portage.5
@@ -384,18 +384,15 @@ override.
 
 .I Example:
 .nf
-portdbapi.auxdbmodule = portage.cache.metadata_overlay.database
-.fi
-
-The metadata_overlay cache module makes it possible to disable
-FEATURES="metadata-transfer" in \fBmake.conf\fR(5).  When the user initially
-enables metadata_overlay in /etc/portage/modules, all of the cache files
-contained in /var/cache/edb/dep/${PORTDIR} must be manually removed in order
-to avoid unecessary cache regeneration.  In addition, users of the
-metadata_overlay module must never modify eclasses in ${PORTDIR} because
-portage will not be able to detect that cache regeneration is necessary.  If
-the user would like to modify eclasses, it is safe to use metadata_overlay
-together with PORTDIR_OVERLAY in \fBmake.conf\fR.
+portdbapi.auxdbmodule = portage.cache.sqlite.database
+.fi
+
+After changing the portdbapi.auxdbmodule setting, it may be necessary to
+transfer or regenerate metadata cache. Users of the rsync tree need to
+run `emerge \-\-metadata` if they have enabled FEATURES="metadata-transfer"
+in \fBmake.conf\fR(5). In order to regenerate metadata for repositories
+listed in \fBPORTDIR_OVERLAY\fR or a cvs tree, run `emerge \-\-regen`
+(see \fBemerge\fR(1)).
 .TP
 .BR package.keywords
 Per\-package KEYWORDS.  Useful for mixing unstable packages in with a normally