Author: mperham
Date: Fri Dec 1 20:18:50 2006
New Revision: 481503
URL: http://svn.apache.org/viewvc?view=rev&rev=481503
Log:
Add site documentation describing the Perforce provider and how it works
Added:
maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/
maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/
maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
Added:
maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt?view=auto&rev=481503
==============================================================================
---
maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
(added)
+++
maven/scm/trunk/maven-scm-providers/maven-scm-provider-perforce/src/site/apt/index.apt
Fri Dec 1 20:18:50 2006
@@ -0,0 +1,44 @@
+ --------------
+ Maven Perforce SCM provider
+ --------------
+ Mike Perham
+ --------------
+ 01 December 2006
+ --------------
+
+Maven Perforce SCM provider
+
+ The Perforce provider acts as a "driver" between Maven's generic SCM API and
the Perforce SCM system.
+
+Use Cases
+
+ The provider must handle a number of different usecases:
+
+ * Check out to a directory or update that source regularly as part of a build
server (Continuum)
+
+ * Label a source tree and check out that label to a temp directory (the
release plugin)
+
+ * Map a number of commands designed for CVS/SVN onto the (frequently) very
different semantics provided by Perforce (the scm plugin)
+
+Details
+
+ The main semantic issue faced by the provider is CVS/SVN's concept of a
working copy versus Perforce's concept of a clientspec. CVS/SVN allow the user
to checkout any repository location to any local directory at will and tracks
this by keeping metadata in a CVS/.svn directory. Perforce instead uses a
"clientspec" to track any number of repository locations and how they map onto
the local filesystem.
+
+ Consider the complications required just to check out source to a directory.
The provider cannot assume that it can modify the current or default clientspec
so it needs to create a clientspec. But since clientspecs are persistent it
needs to know if it should delete the clientspec (the release plugin) or keep
the clientspec around so it can be used to refresh the source tree in the
future (build server).
+
+ The provider uses a few system properties to control how it operates.
+
+ * <<<maven.scm.perforce.clientspec.name>>> - Allows you to override the
default name created by the provider. By default the provider creates a
clientspec with the name "<username>-<hostname>-MavenSCM-<localpath>" to ensure
uniqueness and tracability. If you want to use a pre-existing clientspec or
conform to a corporate naming standard, you can just pass the name here and the
provider will use it instead. This property is most useful for scenarios where
you want the clientspec to be retained, as with Continuum.
+
+ * <<<maven.scm.persistcheckout>>> - Controls whether the Perforce provider
will delete
+ the clientspec once the operation is done. In the case where we just want to
check out a source tree to a temporary directory (like with the release
plugin), we want this to be false since there is no reason to keep the
clientspec around. On the other hand, when used with Continuum, you want to
remember the checkout so that repeated syncs take a minimum of time. The
default is false.
+
+Troubleshooting
+
+ * Under the covers, the provider just executes the <<<p4>>> command.
<<<p4>>> must be in your path.
+
+ * Make sure <<<p4 info>>> returns your correct information.
+
+ * The provider does not login for you. You must run <<<p4 login>>> before
any Maven SCM commands will work. If you need automated SCM operations (e.g.
you are using Continuum on a build server), it is recommended that you use a
special Perforce user whose login does not time out.
+
+ * Ensure that your module has a valid SCM element and the depot path is
correct.
