#Introduction

[P4Maven](https://swarm.workshop.perforce.com/files/guest/dantran/p4maven/main) is a
[Maven SCM provider](http://maven.apache.org/scm) using
[P4Java](http://www.perforce.com/perforce/doc.current/manuals/p4java-javadoc)
developed and open sourced by Perforce under BSD license in 1/2011.
In 6/2014, P4Maven was refactor to provide the following improvements:

  * Auto discover existing Perforce client of a given source tree
    User is no longer required to configure the client name via Java system properties.

  * Client are persisted and shared by multiple commands

  * Auto generated clients are destroyed after each JVM session (ie auto cleanup).

  * Full integration with Maven SCM and Release plugin.
    User now can release Maven project with Perforce SCM using one command ( mvn -B release:preare release:perform)

  * Comply with Maven Scm's Technology Compatibility Kit (TCK)

  * Added Lots of Maven Plugin Integration Tests.

Due to large changes to the codebase, this provider and its accompany plugin have a new groupId and aritifactId -
com.perforce.p4maven:p4maven-provider and com.perforce.p4maven:p4maven-mojo respectively.
It also has a more comprehesive URL format.

This provider is not the same provider developed at Apache Maven SCM team, which uses p4 command line to
interact with Perforce server.


#SCM URL

The general format for a Perforce P4Maven SCM URL is

    scm:p4:[protocol:][[username[:password]@]hostname:port:]//depot/path/to/project


#SCM URL Examples

Generic URL to work with multiple sites using Perforce proxy nodes. The host and protocol properties must be configured using global configuration.

    scm:p4://depot/path/to/project

Single Perforce server with no proxy

    scm:p4:host://depot/path/to/project
    scm:p4:ssl:host:3666://depot/path/to/project

Testing only due to exposure of credentials

    scm:p4:ssl:user:password@host:3666://depot/path/to/project

Notes:

  * 'tcp' is implicitly used when protocol field is not given. See Perforce documentation to see a list of
     supported protocols. However, as of this writing P4Maven provider supports only 'tcp' and 'ssl' protocols


# Provider Global Configuration

User can configure provide global configurations using:

  * External ${user.home}/.scm/p4maven-settings.xml

  * External environment variables

  * External Java system properties


The XML configuration has the following format

    <p4maven-settings>
      <key>value</key>
      <key>value</key>
      [...]
    </p4maven-settings>


These settings are always overridable from command line using Java system properties (ie -Dkey=value ) if allow.
They are overridable from system environment only when existing values are empty if allow.


    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | p4maven-settings Key  | ENV Key   | System Property | Type   | Default | Description                              |
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | p4Port                | P4PORT    | P4PORT          |String  | null    | P4PORT info                              |
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | jobs                  | N/A       | P4JOBS    or    |String  | null    | List of Perforce Job ID separated by space
    |                       |           | p4jobs          |        |         | for any submit action like checkin
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | N/A                   | N/A       | P4CLIENT  or    |String  | null    | A client name for SCM operations. If not
    |                       |           | p4client        |        |         | given, it is self discovered or generated.
    |                       |           |                 |        |         | Not predictable when use with multiple SCM paths.
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | charset               | P4CHARSET | P4CHARSET       |String  | null    | Server connection charset
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | N/A                   | N/A       | P4VERBOSE or    |String  | null    | A client name for SCM operations. If not
    |                       |           | p4verbose       |        |         | given, it is self discovered or generated.
    |                       |           |                 |        |         | Not predictable when use with multiple SCM paths.
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | lockTag               | N/A       | N/A             |boolean | true    | Lock the created label at tag action
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | allowTagUpdate        | N/A       | N/A             |boolean | true    | Allow the re-used of existing tag at tag action
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | strictClientDiscovery | N/A       | strictClient    |boolean | false   | Whether the discovered client must have
    |                       |           | Discovery       |        |         | its host field matches with the current host
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+
    | checkStaledConnection | N/A       | N/A             |boolean | false   | Check for staled connection. Should turn
    |                       |           |                 |        |         | on for session longer then login session
    *-----------------------+-----------+-----------------+--------+---------+------------------------------------------+


# Working with Maven SCM and Release Plugins

  * Check out the source tree with a known client.

  * Add this provider to plugin dependency

    <build>
      <defaultGoal>install</defaultGoal>
      <pluginManagement>
        <plugins>
          [...]
          <!-- add this if release plugin will be used to release your project -->
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-release-plugin</artifactId>
            [...]
            <dependencies>
              <dependency>
                <groupId>com.perforce.p4maven</groupId>
                <artifactId>p4maven-provider</artifactId>
                <version>${p4maven.version}</version>
              </dependency>
            </dependencies>
            [...]
          </plugin>

          <!-- add this if scm plugin will be used with your project -->
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-scm-plugin</artifactId>
            [...]
            <dependencies>
              <dependency>
                <groupId>com.perforce.p4maven</groupId>
                <artifactId>p4maven-provider</artifactId>
                <version>${p4maven.version}</version>
              </dependency>
            </dependencies>
            [...]
          </plugin>

          <!-- add this if buildnumber plugin will be used with your project -->
          <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>buildnumber-maven-plugin</artifactId>
            [...]
            <dependencies>
              <dependency>
                <groupId>com.perforce.p4maven</groupId>
                <artifactId>p4maven-provider</artifactId>
                <version>${p4maven.version}</version>
              </dependency>
            </dependencies>
            [...]
          </plugin>

          [...]
        </plugins>
       </pluginManagement>
       [...]
     </build>


  * Configure SCM element in your project top level pom. Here are a couple of examples

    <scm>
      <connection>scm:p4:workshop.perforce.com:1666://guest/dantran/p4maven</connection>
      <developerConnection>scm:p4:workshop.perforce.com:1666://guest/dantran/p4maven</developerConnection>
      <url>https://swarm.workshop.perforce.com/files/guest/dantran/p4maven</url>
    </scm>

    <scm>
      <connection>scm:p4://guest/dantran/p4maven</connection>
      <developerConnection>scm:p4://guest/dantran/p4maven</developerConnection>
      <url>https://swarm.workshop.perforce.com/files/guest/dantran/p4maven</url>
    </scm>


  * The credential can be configured using plugin's specific properties or hide it under your local's settings.xml via server element


    <settings>
      ...
      <servers>
        <server>
          <id>hostname:port</id> <!-- refer to  your $P4PORT -->
          <username>username</username>
          <password>password</password> <!-- should be encrypted using Maven encryption -->
        </server>
      </servers>
    </settings>