------
 Introduction
 ------
 Dan Tran
 ------
 20014-06-10
 ------


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


Introduction

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

    * Auto discover the existing Perforce client that manages the checked out Maven 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.

    []

  Note:

    * Due to large changes to the codebase, this provider and its associate plugin's Maven coordinate has a new groupId - com.perforce.p4maven.
      It also has a more comprehesive URL format.

    * This provider is not the same provided develop 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
-------


	Examples

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

    This is best fit for mutiple sites using Perforce Proxy servers. The host and protocol properties are pickup form P4PORT environment or Java system properties

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

	This is for single perforce server with no proxy.

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

	This is for testing only due to its exposure of credentials


  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 writting P4Maven provider supports only 'tcp' and 'ssl' protocols

    * 1666 is the default port when not given

    * When host properties are not provided, P4PORT environment variable will be used

    * When P4PORT system property is set, it overrides host info provided under the URL and P4PORT environment

	[]



* Provider Configuration

  This provider also has a list of global settings which can be configured using its glocal configuration file at $\{user.home}/.scm/p4maven-settings.xml.
  The format of this settings is

-------------------------------

  <p4maven-settings>
    <key>value</key>
  </p4maven-settings>

-------------------------------

  These setttings are overridable from command line using Java system properties (ie -Dkey=value )

*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+
| System Property | ENV Key           | p4maven-settings Key | Type    | Default | Description                              |
*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+
| P4PORT          | P4PORT            | p4port               |String   |         | P4PORT info                              |
*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+
| P4JOBS          | N/A               | jobs                 |String   |         | List of Perfoce Job ID separated by space for any submit action like checkin
*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+
| P4CLIENT        | N/A               | N/A                  |String   |         | A client name to be used as part of inital checkout action.
|                 |                   |                      |         |         | Unpredictable result when it is set and use multitple checkouts under same JVM
|                 |                   |                      |         |         | For other action, the client is discover or generated
*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+
| P4CHARSET       | P4CHARSET         | charset              |String   |         | Server connection charset
*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+
| P4LOCKTAG       | N/A               | lockTag              |boolean  | true    | Lock the created label at tag action
*-----------------+-------------------+----------------------+---------+---------+------------------------------------------+


* Working with Maven SCM and Release Plugins

    [[]] Check out the source tree with a known client. <<Ensure the host field is set at client configuration so that P4Maven can discover the 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>
            </dependencythis>
          </dependencies>
          [...]
        </plugin>
        [...]
      </plugins>
     </pluginManagement>
     [...]
   </build>

-----------------------------------------------------------------------


   [[]] Configure SCM element in your project top level pom


     * The following example show how to configure \<scm\> element with host configurations.

---------------------------------

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

--------------------------------

     []

     * The following example show how to configure \<scm\> element without host configurations which must be set either from
       environment variable or Java system property "P4PORT".
       This configuration is suitable for multi sites, with each site has its own P4PORT mirror to a central Perforce server.

---------------------------------

  <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
      {{{http://maven.apache.org/scm/maven-scm-plugin/examples/bootstrapping-with-pom.html}local's settings.xml}}