p4sync: P4Sync

The simplest way to populate your Jenkins workspace from Perforce is by using the p4sync: P4 Sync DSL (Domain Specific Language) using the Snippet Generator.

Example p4sync: P4Sync configuration

Example script

The form above generates the following script snippet:

p4sync( 
    charset: 'none',
    credential: 'Local Perforce 20231',
    format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
    populate: autoClean(
        delete: true,
        modtime: false,
        parallel: [enable: false, minbytes: '1024', minfiles: '1', threads: '4'],
        pin: '',
        quiet: true,
        replace: true,
        tidy: false),
    source: streamSource('//streams-depot/StreamA'
    )
)

Reduce the script snippet size to make it more readable

You can reduce the script size and make it easier to read by removing any options that are set to the default value.

Example: script snippet with default values removed:

p4sync(
    credential: 'Local Perforce 20231',  
    format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
    populate: autoClean(),
    source: streamSource('//streams-depot/StreamA'
    )
)

Paste the script snippet into a basic script

Example: the script snippet above has been pasted into a basic script:

pipeline {
    agent any
    stages {
        stage('Sync') {
			steps() {
				// sync files from //streams-depot/StreamA...
				p4sync( 
					credential: 'Local Perforce 20231',
					format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
					populate: autoClean(),
					source: streamSource('//streams-depot/StreamA'
					) 
				)
			}
        }
    }
}

Configure a P4Sync script

1. To configure the pipeline to use p4sysnc: P4Sync, select p4sysnc: P4Sync from the Sample Step dropdown of the snippet generator.

2. Select the credentials for the job from the Perforce credentials dropdown.

Character Set

Character Set: sets the character set used by Jenkins when syncing files from the Perforce Helix Core Server. This should be set to none unless the workspace is connected to a Unicode enabled Helix Core Server.

Workspace Name Format

Workspace name: Jenkins slave nodes must each use a unique Perforce workspace. The format string configures the workspace name by substituting the specified variables. At least one variable must be used, but it is recommended that, as a minimum, the following variables are used:

jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}

For more information about variables, see Variable Expansion

Populate options

Perforce populates the workspace with the file revisions needed for the build, the options are:

• Automatic Cleanup and Sync: Use when the Perforce Helix Core Server controls the files in the workspace. This is an efficient option that cleans and syncs file revisions in the workspace. Extra (non versioned files) are removed, missing and modified files are re-added. This option is best for clean builds. For details about the Automatic Cleanup and Sync options, see Automatic Cleanup and Sync.
• Flush Workspace: Use when files in the workspace are not added by the Perforce Helix Core Server. No file Sync or cleanup is attempted and no files are removed, but the workspace "have list" is updated. This is effectively the same as using the p4 sync -k command. For details about the Flush Workspace options, see Flush Workspace.
• Forced Clean and Sync: Not recommended because this option is very inefficient. Use if you do not trust the content of your workspace. Removes all of the files in the workspace root, including the build history, and then force syncs the required files. For details about the Forced Clean and Sync options, see Forced Clean and Sync.
• Graph Force Clean and Sync: Perforce Git Connector required. Use for Perforce Graph and Hybrid only. Removes all of the files in the workspace root, including the build history, and then force syncs the required files. For details about the Graph Force Clean and Sync options, see Graph Force Clean and Sync.
• Preview Check Only: No file sync or cleanup is attempted, and the Workspace "have list" is not updated. This is effectively the same as using the p4 sync -n command. For details about the Preview Check Only options, see Preview Check Only.
• Sync Only: Use if you have a hand-crafted build environment that you don't want to lose any files from. No cleanup is attempted and the sync will update all files (as CLOBBER is set) to the required revisions. This option is best for incremental builds and is mostly used for Pipeline builds. For details about the Sync Only options, see Sync Only.

Parallel sync

Parallel sync enables concurrent transfer of files between Jenkins and the Helix Core Server. Parallel sync can greatly reduce the amount of time it takes to update a workspace, especially when connecting across a high latency network. Parallel sync must be enabled on the Helix Core Server (2014.1 or later). For more information on parallel sync, see Using parallel processing for submits and syncs in  Helix Core Server Administrator Guide. Parallel sync is disabled by default, to enable parallel sync:

1. Click Advanced.
2. Select Enabled.
3. The parallel sync settings will depend on the capabilities of the Jenkins build machine and the Helix Core Server:
   • Threads: Set the number of threads available for parallel sync.
   • Minimum Files: If the number of files being sync'ed is less than this value, parallel sync is not used.
   • Minimum Bytes: If the total size of files being sync'ed is less than this value, parallel sync is not used.

Workspace Source

You only need to provide one codeline, use one of the following options:

• Depot Source(s) to refer to a classic depot location in PerforceHelix Core Server.
• Stream Codeline for streams paths
• Template Workspace if you have defined the path in another Workspaces View.
• Graph Source(s) to refer to a Graph depot location.

Generate Pipeline Script

To generate the pipeline script, click Generate Pipeline Script. The script is generated in the text box below the button.

Copy the generated script and paste it into the Script box on the Jenkins Pipeline Script page.