 --------------
 Maven Perforce SCM provider
 --------------
 Mike Perham
 --------------
 01 December 2006
 --------------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

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 traceability.  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.

 * <<<maven.scm.locktag>>> - Controls whether the provider will lock the tag once it has been successfully created.  This is useful for the release plugin since the tag should be frozen based on a one-time release.  Defaults to true since none of the above usecases require a floating label.

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.