Automated Deployment of Perforce

Custom installation of Perforce at large Windows sites

Info & Tags

Article #:
68
Created:
04/25/07
Modified:
04/13/12
Tags:
automate, deployment, installation, p4, p4scc, p4v, p4win, third party merge tools

Related Articles

  1. Automated Install of Custom Tools in P4V and P4Win
  2. Third-Party Merge Tools
  3. Replicating Describe Changelist Functionality of P4Win in P4V
  4. Debugging P4V Installer Error on Windows Vista
  5. Automated Deployment Properties

Links

  1. Automated Deployment Properties

TASK

How do I automate deployment of Perforce client programs at large Windows sites?

SOLUTION

For releases prior to 2007.3, automated deployment of client applications was done using a configuration file. Details can be found below.

For releases 2007.3 and later, Perforce installers use command line options passed to the Perforce installer executable. The command line options are used to:

  • Specify property values used during the installation.
  • Instruct the installer to generate a log file.
  • Specify the desired user interface level.
  • Specify which features are installed or removed.
Note: For the purpose of this article, the commands will refer to the P4V installer: p4vinst.exe. These same commands can also be used with the P4SCC installer: p4sccinst.exe.

Specifying property values

Automated installations are customized by calling the installer with a /v" " flag. All configuration properties are placed between the double quotes. Any property values that contain spaces should be surrounded by escaped double quotes (\").

Example: 

p4vinst.exe /v"additional_flags property_name=property_value"

Note: A complete list of property values can be found in the Automated Deployment Properties knowledge base article.

Generating a log file

By default a log file is generated in the user's Temp directory. To produce an installer log file with additional output in a different location, use the "/l" flag (lower case L).

Example: 

p4vinst.exe /v"/l*v+ p4vinst.log"

Note: In this example the "*v" option sets verbose logging, while the "+" appends to the specified log file instead of over-writing it.

For more information about logging options see the Microsoft Msiexec command-line options page.

Specifying the desired user interface level

The /q flags are used to control the user interface level. The following are some of the available flags:

  • /qn - Silent, no user interface.
  • /qb - Basic user interface.
  • /qr - Reduced user interface.
  • /qf - Full UI (default).

First, run the following command from the command line to ensure the installer is working. This command will run the P4V installer with a basic user interface: 

p4vinst.exe /v"/qb"

Note: Even with the /qn flag a small initialization dialog will appear. To hide this dialog and perform a completely silent installation, add the /s flag before the /v flag. For example: 

p4vinst.exe /s /v"/qn"

For more information about user interface options see the Microsoft Msiexec command-line options page.

Specifying which features are installed or removed

You can pass properties to specify which features are installed or removed. The syntax for specifying features is as follows:

ADDLOCAL=<feature>,<feature> {or ALL}
A comma delimited list of features to install, or ALL to indicate all features are to be installed.
REMOVE=<feature>,<feature> {or ALL}
A comma delimited list of features to not install or remove (if installed), or ALL to indicate all features are to be uninstalled.
Examples:

Install all features except P4Admin: 
p4vinst.exe /v"ADDLOCAL=ALL REMOVE=P4ADMIN"
Install only the P4Admin feature: 
p4vinst.exe /v"ADDLOCAL=P4ADMIN"
Uninstall P4Admin: 
p4vinst.exe /v"REMOVE=P4ADMIN"
Uninstall all features: 
p4vinst.exe /v"REMOVE=ALL"

The valid feature names for each installer are:

  • Perforce Visual Client - P4V, P4EXP, P4MERGE, P4ADMIN, P4
  • Perforce Windows Client - P4WIN, P4EXP, P4DIFF, P4WINMRG, P4 
  • Perforce Web - P4WEB, P4
  • Perforce SCC Plug-In - P4SCC, P4 

Note: Some installations may require a reboot upon completion. To prevent this reboot prompt set the REBOOT property as follows: 

p4vinst.exe /v"REBOOT=ReallySuppress"

P4V custom settings

P4V 2009.1 and later can read settings from two XML files to configure initial preference settings and feature availability:

{INSTALL_DIRECTORY}\P4VResources\p4vdefaults.xml

{INSTALL_DIRECTORY}\P4VResources\p4vfeatures.xml

To enable or disable specific P4V features and set initial preferences for automated installs your installation process should create custom XML configuration files at the appropriate location on each client machine. For reference, example configuration files for P4V 2009.1 or later installations are located in:

{INSTALL_DIRECTORY}\P4VResources\examples

Four example files are provided:

  • p4vfeatures.xml: Configures the feature set for P4V (all features enabled).
  • basic_p4vfeatures.xml: Enables a minimum set of features.
  • p4vdefaults.xml: Configures the default settings for performance preferences and initial application appearance.
  • basic_p4vdefaults.xml: Enables a simplified application layout.

The p4vdefaults.xml file contains two blocks:

  • Performance: Defines settings that control the impact of P4V on the Perforce server
  • Layout: Enables you to define the features that are visible when P4V is launched to determine initial appearance.

For further details, consult the example configuration files. If these files are present in the P4VResources directory when P4V is launched, P4V reads the settings to determine which features are visible to the user and to enforce any limits set to minimize impact on the performance of the Perforce server. The settings in these files override P4V's application defaults. After P4V is launched, users can modify any of the settings using the P4V Preferences dialogs.

Note: Changing preference settings does not modify the configuration files. After you edit the configuration files, you must restart P4V for the new settings to take effect.

Batch file example

The commands for invoking the installer and configuring arguments and property settings can be placed into a batch file.

Example: 

@ECHO OFF

REM Example batch files showing silent install of 
REM the Perforce Visual Client (P4V). Install all 
REM features except P4ADMIN and create a p4vfeatures.xml 
REM file that turns off the Connection Wizard.

REM Set the installer executable name
SET INSTALLERCMD=p4vinst.exe

REM Set the arguments we'll pass to msiexec
SET MSIARGS=/qb /l+* .\p4vinst.log^
   INSTDIR=\"%ProgramFiles%\Perforce\"^
   P4USER=%UserName%^
   P4CLIENT=%UserName%-%ComputerName%^
   P4PORT=perforce:1666^
   ADDLOCAL=ALL^
   REMOVE=P4ADMIN

REM Invoke the installer
%INSTALLERCMD% /v"%MSIARGS%"

REM Create a feature XML file in the P4VResources directory 
REM to turn off the P4V Connection Wizard.
SET PREFDIR=%ProgramFiles%\Perforce\P4VResources\
SET P4VFEATS=%PrefDir%p4vfeatures.xml
echo ^<?xml version="1.0" encoding="UTF-8"?^> > "%P4VFeats%"
echo ^<!--perforce-xml-version=1.0--^> >> "%P4VFeats%"
echo ^<FeaturesEnabled varName="FeaturesEnabled"^> >> "%P4VFeats%"
echo ^<Visibilility varName="Functionality"^> >> "%P4VFeats%"
echo ^<ConnectionWizard^>Off^</ConnectionWizard^> >> "%P4VFeats%"
echo ^</Visibilility^> >> "%P4VFeats%"
echo ^</FeaturesEnabled^> >> "%P4VFeats%"

NOTE: Using a batch file is meant purely as an example.  Perforce recommends using an XML utility for reading and writing preferences to these files.

Specifying a Third-Party Merge/Diff Tool

By default P4V uses the P4Merge application when a merge/diff operation is required. However, the default merge application can be modified during installation by appending commands to the installation script, discussed above, which will generate the necessary XML configuration file. In P4V 2010.2 and later this file is called "ApplicationSettings.xml". For P4V 2010.1 and earlier this file was named "appsettings.xml".

This configuration file must be placed in the "%userprofile%\.p4qt" directory, and must define the location and argument order for each third party application.

When correctly configured the P4V "Preferences" dialog will show the correct application and argument within the "Diff" and "Merge" tabs as appropriate.

Example:

Note: This example will overwrite any existing settings file which will delete user setting not necessarily related to third-party merge or diff applications. In a production environment this settings file should be edited by navigating the DOM and editing only the necessary elements. 

:: Example batch script showing additions to the
:: installer script for customizing third party
:: diff/merge tools.
::
REM Set the location of the third party tool's executables.

SET THIRDPARTYDIFFCMD="%ProgramFiles%\Acme\diff.exe"
SET THIRDPARTYMERGECMD="%ProgramFiles%\Acme\merge.exe"

REM Set the location of the 'ApplicationSettings.xml' file
REM - create a '.p4qt' directory if it doesn't exist.

SET APPDIR=%userprofile%\.p4qt\
IF NOT EXIST %APPDIR% MKDIR %APPDIR%
SET P4VAPP="%APPDIR%ApplicationSettings.xml"
 
REM create 'ApplicationSettings.xml' configuration file
REM - overwriting existing file if it already exists

echo.^<?xml version="1.0" encoding="UTF-8"?^> > %P4VAPP%
echo.^<!--perforce-xml-version=1.0--^>  >> %P4VAPP%
echo.^<PropertyList varName="Settings" IsManaged="TRUE"^> >> %P4VAPP%
echo.^<Associations varName="Merge Associations"^> >> %P4VAPP%
echo.^<RunExternal^>true^</RunExternal^> >> %P4VAPP%
echo.^<Association varName="Default Association"^> >> %P4VAPP%
echo.^<Application^>%THIRDPARTYMERGECMD%^</Application^> >> %P4VAPP%
echo.^<Arguments^>%%b %%1 %%2 %%r^</Arguments^> >> %P4VAPP%
echo.^</Association^> >> %P4VAPP%
echo.^</Associations^> >> %P4VAPP%
echo.^<Associations varName="Diff Associations"^> >> %P4VAPP%
echo.^<RunExternal^>true^</RunExternal^> >> %P4VAPP%
echo.^<Association varName="Default Association"^> >> %P4VAPP%
echo.^<Application^>%THIRDPARTYDIFFCMD%^</Application^> >> %P4VAPP%
echo.^<Arguments^>%%1 %%2^</Arguments^> >> %P4VAPP%
echo.^</Association^> >> %P4VAPP%
echo.^</Associations^> >> %P4VAPP%
echo.^<BottomPaneTabSettings varName="bottom_pane_tab_settings"^> >> %P4VAPP%
echo.^<orderedTabs^> >> %P4VAPP%
echo.^<item^>LogWindow^</item^> >> %P4VAPP%
echo.^<item^>DashboardWindow^</item^> >> %P4VAPP%
echo.^</orderedTabs^> >> %P4VAPP%
echo.^<currentTab^>LogWindow^</currentTab^> >> %P4VAPP%
echo.^</BottomPaneTabSettings^> >> %P4VAPP%
echo.^<PropertyList varName="Misc" IsManaged="TRUE"^> >> %P4VAPP%
echo.^<Bool varName="ENABLE_DOS_PATH"^>false^</Bool^> >> %P4VAPP%
echo.^</PropertyList^> >> %P4VAPP%
echo.^</PropertyList^> >> %P4VAPP%

NOTE: Using a batch file is meant purely as an example.  Perforce recommends using an XML utility for reading and writing preferences to these files.

Pre-2007.3 installers

To assist in automating installation of Perforce client programs across multiple desktops for installations prior to P4V version 2007.3, Perforce provides a scripted version of the "Perforce Windows Installer". The scripted version of the installer enables Perforce administrators to standardize options and settings before installation, thereby speeding up the process of deploying Perforce client programs throughout an organization.

The customizable element of the scripted installer is a configuration file named perforce.cfg. The Perforce Administrator edits this file, and places it on a shared network drive along with the expanded contents of the perforce.zip file. Perforce client programs can then be installed by running setup.exe from each desktop. It is important to run setup.exe from the folder in which it resides otherwise it will not be able to find perforce.cfg.

Some sample settings from the perforce.cfg file:

  • Install only the Perforce client programs, and not the Perforce Server: 
    INSTTYPE=ClientOnly
  • Install according to the settings in the configuration file without displaying installation dialogs: 
    INSTMODE=NoPrompt
  • Configure a value for the Perforce Server machine and port number: 
    P4PORT=perforce:1666
  • Configure a value for the the P4Web client browser port: 
    P4WEBPORT=8080

Other settings and additional information are available in the comments included within the perforce.cfg file. As of release 2005.2, the P4Win performance variable naming convention has been modified. These details are also embedded within the perforce.cfg file for reference.

Where to Download

The Perforce Core (Server and Proxy) scripted installer can be downloaded from:

ftp://ftp.perforce.com/perforce/r06.2/bin.ntx86/perforce.zip

The P4Win scripted installer can be downloaded from:

ftp://ftp.perforce.com/perforce/r06.2/bin.ntx86/p4winst.zip

The P4V scripted installer can be downloaded from:

ftp://ftp.perforce.com/perforce/r07.2/bin.ntx86/p4vinst.zip

To use the scripted installer:

  1. Download perforce.zip (or appropriate installer) from the FTP site.

  2. Extract the contents of perforce.zip into a directory on your machine.

  3. In this directory, edit perforce.cfg as required.

  4. Place the unzipped contents of this directory, including your customized perforce.cfg file, in a folder accessible from a Network Drive or into the root folder of a CD.

  5. From the network drive or CD, run setup.exe to install Perforce according to the settings you configured in perforce.cfg onto each desktop.

Note: The method to exclude certain binaries from being installed by the scripted installer is to remove those binaries from the directory where the installer file has been expanded. For example, if you wish to exclude the P4EXP from an install of P4Win, then unzip the p4winst.zip archive and remove the P4Exp.dll from the expanded directory prior to running setup.exe.

If you have any questions about the settings in perforce.cfg, please contact Perforce Support at support@perforce.com.