P4Maven User Guide

by

• Perforce Support ([email protected])

Contents

• Overview
• Use Cases
• Details
• Extensions

Overview

P4Maven is a Maven SCM Plugin Provider that implements Maven's generic SCM API for the Perforce SCM system using the Perforce Java API.

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.

P4Maven implements the goals of the Maven SCM Plugin 1.4 and Maven 2.x. Please see the following link for details:

• Maven SCM Plugin

Note: 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

Use Cases

• Label a source tree and check out that label to a temp directory (the release plugin)
• Check out to a directory or update that source regularly as part of a build server (Continuum)
• Map commands designed for CVS/SVN onto the 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 client workspace specification.

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.

The following system properties can be set by the user:

• 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".
• 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.
• maven.scm.locktag - Tells the provider whether to lock the tag once it has been successfully created. Defaults to true.
• maven.scm.jobs - Used by the checkin command to submit changes with a list of Perforce jobs. The list of jobs is space delimited.
• maven.scm.p4.port - The Perforce server and port to be used (i.e. perforce:1666).
• maven.scm.p4.user - The Perforce user.
• maven.scm.p4.password - The Perforce user's password.
• 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.

P4Maven POM Snippet:

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

P4Maven Commandline Snippet:

mvn -Dmaven.scm.perforce.clientspec.name=someclient scm:checkout

Extensions

P4Maven also comes with a set of Mojos that implement additional Perforce commands as Maven goals.

• shelve - Store files from a pending changelist into the depot.
• unshelve - Restore shelved files from a pending change into a workspace.
• jobs - Display list of jobs.

P4Maven Mojo specific system properties can be set by the user:

• 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.
• maven.scm.p4.changelist.description - The description for the new changelist.
• maven.scm.p4.fromchangelist - Specifies the source pending changelist that contains shelved files.
• maven.scm.p4.tochangelist - Specifies the target pending changelist to which files are unshelved.

P4Maven Mojo POM Snippet:

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

P4Maven Mojo Commandline Snippet:

mvn com.perforce:p4maven-mojo:2011.1.1-SNAPSHOT:shelve -Dmaven.scm.perforce.clientspec.name=someclient -Dmaven.scm.p4.changelist=17815