<html>
<head>
<title>P4Maven</title>
</head>
<body>
<h1>P4Maven User Guide</h1>
<p>by</p>
<ul>
<li>Perforce Support (<a href="mailto:support@perforce.com">support@perforce.com</a>)</li>
</ul>
<hr>
<h2>Contents</h2>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#usecases">Use Cases</a></li>
<li><a href="#details">Details</a></li>
<li><a href="#extensions">Extensions</a></li>
</ul>
<h2><a name="overview">Overview</a></h2>
<p>P4Maven is a Maven SCM Plugin Provider that implements Maven's
generic SCM API for the Perforce SCM system using the Perforce Java API.</p>
<p>Maven SCM supports Maven 2.x plugins and other tools by providing
them with a common API for doing SCM operations. The Maven SCM Plugin
offers vendor-independent access to common SCM commands by offering a
set of command mappings for the configured SCM system. Each command is
implemented as a goal.</p>
<p>P4Maven implements the goals of the Maven SCM Plugin 1.4 and
Maven 2.x. Please see the following link for details:</p>
<ul>
<li><a
href="http://maven.apache.org/scm/maven-scm-plugin/index.html"
target="_top">Maven SCM Plugin</a></li>
</ul>
<p><b>Note:</b> P4Maven is known to work with P4Java 2010.1+
(Perforce Java API), JDK 1.5.0+, Maven SCM Plugin 1.4 and Maven 2.x</p>
<h2><a name="usecases">Use Cases</a></h2>
<ul>
<li>Label a source tree and check out that label to a temp
directory (the release plugin)</li>
<li>Check out to a directory or update that source regularly as
part of a build server (Continuum)</li>
<li>Map commands designed for CVS/SVN onto the semantics provided
by Perforce (the SCM plugin)</li>
</ul>
<h2><a name="details">Details</a></h2>
<p>The main semantic issue faced by the provider is CVS/SVN's
concept of a working copy versus Perforce's concept of a client
workspace specification.</p>
<p>CVS/SVN allow the user to check out any repository location to
any local directory at will and tracks this by keeping metadata in a
CVS/.svn directory. Perforce uses a client workspace concept whereby it
keeps track of the mapping of repository locations to local filesystem
locations within the Perforce server. This creates restrictions on where
users can check out projects.</p>
<p>The following system properties can be set by the user:</p>
<ul>
<li>maven.scm.perforce.clientspec.name - The Perforce client to be
used by the provider. By default the provider creates a Perforce client
with the name "username-hostname-MavenSCM-localpath".</li>
<li>maven.scm.persistcheckout - Tells the provider whether to keep
or delete the Perforce client created by default when the operation is
done. Defaults to true.</li>
<li>maven.scm.locktag - Tells the provider whether to lock the tag
once it has been successfully created. Defaults to true.</li>
<li>maven.scm.jobs - Used by the checkin command to submit changes
with a list of Perforce jobs. The list of jobs is space delimited.</li>
<li>maven.scm.p4.port - The Perforce server and port to be used
(i.e. perforce:1666).</li>
<li>maven.scm.p4.user - The Perforce user.</li>
<li>maven.scm.p4.password - The Perforce user's password.</li>
<li>maven.scm.p4.charset - The Perforce client's character set to
be used to communicate with the Perforce server (i.e. utf8). Note, the
Perforce server must be unicode enabled.</li>
</ul>
<p>P4Maven POM Snippet:</p>
<pre>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0.2</version>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-plugin</artifactId>
<version>1.4</version>
<dependencies>
<!-- P4Maven -->
<dependency>
<groupId>com.perforce</groupId>
<artifactId>p4maven</artifactId>
<version>[2011,2012)</version>
</dependency>
</dependencies>
<configuration>
<connectionType>connection</connectionType>
<username>someuser</username>
<password>somepassword</password>
<includes>**</includes>
</configuration>
</plugin>
<!-- SCM Settings -->
<scm>
<connection>scm:p4:localhost:1666://depot/someproject</connection>
<developerConnection>scm:p4:localhost:1666://depot/someproject</developerConnection>
<url>http://somerepository.com/view.cvs</url>
</scm>
...
</pre>
<p>P4Maven Commandline Snippet:</p>
<pre>
mvn -Dmaven.scm.perforce.clientspec.name=someclient scm:checkout
</pre>
<h2><a name="extensions">Extensions</a></h2>
<p>P4Maven also comes with a set of Mojos that implement additional
Perforce commands as Maven goals.</p>
<ul>
<li>shelve - Store files from a pending changelist into the depot.</li>
<li>unshelve - Restore shelved files from a pending change into a
workspace.</li>
<li>jobs - Display list of jobs.</li>
</ul>
<p>P4Maven Mojo specific system properties can be set by the user:</p>
<ul>
<li>maven.scm.p4.changelist - Specifies the pending changelist to
which files are shelved. If this property is not specified, it will
creates a new changelist, adds files from the user's default
changelist, then shelves those files in the depot.</li>
<li>maven.scm.p4.changelist.description - The description for the
new changelist.</li>
<li>maven.scm.p4.fromchangelist - Specifies the source pending
changelist that contains shelved files.</li>
<li>maven.scm.p4.tochangelist - Specifies the target pending
changelist to which files are unshelved.</li>
</ul>
<p>P4Maven Mojo POM Snippet:</p>
<pre>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0.2</version>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-plugin</artifactId>
<version>1.4</version>
<dependencies>
<!-- P4Maven -->
<dependency>
<groupId>com.perforce</groupId>
<artifactId>p4maven</artifactId>
<version>[2011,2012)</version>
</dependency>
</dependencies>
<configuration>
<connectionType>connection</connectionType>
<username>someuser</username>
<password>somepassword</password>
<includes>**</includes>
</configuration>
</plugin>
<!-- P4Maven Mojo -->
<plugin>
<groupId>com.perforce</groupId>
<artifactId>p4maven-mojo</artifactId>
<version>[2011,2012)</version>
<configuration>
<connectionType>connection</connectionType>
<username>someuser</username>
<password>somepassword</password>
<includes>**</includes>
</configuration>
</plugin>
</plugins>
</build>
<!-- SCM Settings -->
<scm>
<connection>scm:p4:localhost:1666://depot/someproject</connection>
<developerConnection>scm:p4:localhost:1666://depot/someproject</developerConnection>
<url>http://somerepository.com/view.cvs</url>
</scm>
...
</pre>
<p>P4Maven Mojo Commandline Snippet:</p>
Synosis: mvn groupID:artifactID:version:goal
<pre>
mvn com.perforce:p4maven-mojo:2011.1.1-SNAPSHOT:shelve -Dmaven.scm.perforce.clientspec.name=someclient -Dmaven.scm.p4.changelist=17815
</pre>
</body>
</html>