------ 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. [] Notes: * 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 ------- Examples ------- scm:p4://depot/path/to/project ------- This is best fit for mutiple sites using Perforce proxy nodes. The host and protocol properties must be configured using global configuration. -------- 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 [] * 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 setttings are always overridable from command line using Java system properties (ie -Dkey=value ) if allow. They are overridable from system environmnet 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 |String | null | List of Perfoce Job ID separated by space for any submit action like checkin *-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+ | N/A | N/A | P4CLIENT |String | null | A client name to be used as part of A initial checkout action. Donot run with this settings when your have mulitple checkouts | | | | | | Unpredictable result when it is set and use multitple checkouts under same JVM | | | | | | For other action, the client name is discover or generated *-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+ | charset | P4CHARSET | P4CHARSET |String | null | Server connection charset *-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+ | 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 | N/A |boolean | false | Wether the discovered client must have its host field matches with the current host *-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+ * 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}}
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#12 | 11406 | dantran | Remote Maven site, place important user and dev doc at root level instead | ||
#11 | 10095 | dantran |
more cannonical path handling during client discovery. Update user doc on how to use hide SCM credential using local's settings.xml |
||
#10 | 9705 | dantran |
- add apache snapshot repo for maven-scm-test-1.10-SNAPSHOT - add settings'checkStaledConnection for optimization purpose |
||
#9 | 9681 | dantran | add site report | ||
#8 | 9632 | dantran |
- use groupId:artifactId:version to test release automation - Implment p4maven-settings.xml's p4Port field |
||
#7 | 9621 | dantran | add strictClientDiscovery external setting | ||
#6 | 9597 | dantran |
- minor cleanup - doc update |
||
#5 | 9580 | dantran | explain URL examples | ||
#4 | 9561 | dantran |
- it/release now can be used to test after release:perform - only deploy site during release:perform - more dev and user doc |
||
#3 | 9548 | dantran |
- pickup P4PORT form env and system properties to support multi site using proxy - add development doc - check for error after each action |
||
#2 | 9524 | dantran | switch default tck's depot from //depot to //scmtck to be very specific since user may have a //depot in production | ||
#1 | 9519 | dantran | folder rename to match with its artifactId | ||
//guest/dantran/p4maven/com.perforce.maven/src/site/apt/index.apt | |||||
#2 | 9513 | dantran | add provider doc, deploy site:jar, support external charset config | ||
#1 | 9498 | dantran |
- Setup Maven site for documetation - Implement ~/m2/p4maven-settings.xml to store external config overridable by system properties. All global settings now can be retrieved va P4Utils |