Perforce and Windows
This chapter describes certain information of specific interest to administrators who set up and maintain Perforce servers on Windows.
Note
Unless otherwise specified, the material presented here applies equally to Windows XP, Vista, and 7.
Using the Perforce installer
The Perforce installer program, perforce.exe
,
gives you the option to install or upgrade the Perforce Server,
Perforce Proxy, or the Perforce Command-Line Client.
Separate installers are provided for other Perforce applications such as P4V.
If you have Administrator privileges, it is usually best to install Perforce as a service. If you don't, install it as a server.
Upgrade notes
The Perforce installer also automatically upgrades all types of Perforce servers (or services), even versions prior to 97.3. The upgrade process is extremely conservative; if anything fails at any step in the upgrade process, the installer stops the upgrade, and you are still able to use your old server (or service).
Scripted deployment and unattended installation
The Perforce installer supports scripted installation, enabling you to accelerate a deployment of Perforce across a large number of desktops.
Scripted installations are controlled by a configuration file that
comes with the scriptable version of the Perforce installer. You
can edit this file to preconfigure Perforce environment variables
(such as P4PORT
) for your environment, to
automatically select Perforce applications in use at your site, and
more.
To learn more about how to automate a deployment of Perforce, see "Automated Deployment of Perforce" in the Perforce knowledge base:
http://answers.perforce.com/articles/KB_Article/Automated-Deployment-of-Perforce
Perforce technical support personnel are available to answer any questions or concerns you have about automating your Perforce deployment.
Windows services vs. Windows servers
To run any task as a Windows server, a user
account must be logged in, because shortcuts in a user's
Startup
folder cannot be run until that user
logs in. A Windows service, on the other hand,
is invoked automatically at boot time and runs regardless of whether
or not a user is logged in to the machine.
Throughout most of the documentation set, the terms
Perforce service or p4d are
used to refer to "the process that manages the database and responds
to requests from Perforce applications". Under Windows, this can lead
to ambiguity; this process can run as either a service
(p4s.exe
, which runs as a thread) or as a server
(p4d.exe
, which runs as a regular process). From
a Windows administrator's point of view, these are important
distinctions. Consequently, the terminology used in this chapter uses
the more precise definitions.
The Perforce service (p4s.exe) and the Perforce server (p4d.exe) executables are copies of each other; they are identical apart from their filenames. When run, they use the first three characters of the name with which they were invoked (that is, either p4s or p4d) to determine their behavior. For example, invoking copies named p4smyserver.exe or p4dmyservice.exe invokes a service and a server, respectively.
By default, the installer configures Perforce as a Windows service.
Starting and stopping the Perforce service
If Perforce was installed as a service, a user with Administrator privileges can start and stop it using the
applet under the . You can also stop the Perforce service from the command line with the command:p4 admin stop
Starting and stopping the Perforce server
The server executable, p4d.exe, is normally
found in your P4ROOT
directory. To start the server,
first make sure your current P4ROOT
,
P4PORT
, P4LOG
, and
P4JOURNAL
settings are correct; then run:
%P4ROOT%\p4d
To start a server with settings different from those set by
P4ROOT
, P4PORT
, P4LOG
,
or P4JOURNAL
, use p4d
command-line flags. For example:
c:\test\p4d -r c:\test -p 1999 -L c:\test\log -J c:\test\journal
starts a Perforce server process with a root directory of
c:\test
, listening to port
1999
, logging errors to
c:\test\log
, and with a journal file of
c:\test\journal
. The p4d
command-line flags are case-sensitive.
To stop the Perforce server, use the command:
p4 admin stop
Installing the Perforce service on a network drive
By default, the Perforce service runs under the local
System
account. Because the
System
account has no network access, a real
userid and password are required in order to make the Perforce
service work if the metadata and depot files are stored on a
network drive.
If you are installing your server root on a network drive, the
Perforce installer (perforce.exe) requests a
valid combination of userid and password at the time of
installation. This user must have administrator privileges. (The
service, when running, runs under this user name, rather than
System
)
Although the Perforce service runs reliably using a network drive as the server root, there is still a marked performance penalty due to increased network traffic and slower file access. Consequently, Perforce recommends that the depot files and Perforce database reside on a drive local to the machine on which the Perforce service is running.
Multiple Perforce services under Windows
By default, the Perforce installer for Windows installs a single Perforce server as a single service. If you want to host more than one Perforce installation on the same machine (for instance, one for production and one for testing), you can either manually start Perforce servers from the command line, or use the Perforce-supplied utility svcinst.exe, to configure additional Perforce services.
Warning!
Setting up multiple services to increase the number of users you support without purchasing more user licenses is a violation of the terms of your Perforce End User License Agreement.
Understanding the precedence of environment variables in determining Perforce configuration is useful when configuring multiple Perforce services on the same machine. Before you begin, read and understand “Windows configuration parameter precedence”.
To set up a second Perforce service:
-
Create a new directory for the Perforce service.
-
Copy the server executable, service executable, and your license file into this directory.
-
Create the new Perforce service using the svcinst.exe utility, as described in the example below. (The svcinst.exe utility comes with the Perforce installer, and can be found in your Perforce server root.)
-
Set up the environment variables and start the new service.
We recommend that you install your first Perforce service using the
Perforce installer. This first service is called
Perforce
and its server root directory contains
files that are required by any other Perforce services you create on
the machine.
Example 29. Adding a second Perforce service.
You want to create a second Perforce service with a root in
C:\p4root2
and a service name of
Perforce2
. The svcinst
executable is in the server root of the first Perforce installation
you installed in C:\perforce
.
Verify that your p4d.exe executable is at Release 99.1/10994 or greater:
p4d -V
(If you are running an older release, you must first download a more recent release from http://www.perforce.com and upgrade your server before continuing.)
Create a P4ROOT
directory for the new service:
mkdir c:\p4root2
Copy the server executables, both p4d.exe (the server) and p4s.exe (the service), and your license file into the new directory:
copy c:\perforce\p4d.exe c:\p4root2
copy c:\perforce\p4d.exe c:\p4root2\p4s.exe
copy c:\perforce\license c:\p4root2\license
Use Perforce's svcinst.exe (the service
installer) to create the "Perforce2
" service:
svcinst create -n Perforce2 -e c:\p4root2\p4s.exe -a
After you create the Perforce2
service, set the
service parameters for the Perforce2
service:
p4 set -S Perforce2 P4ROOT=c:\p4root2
p4 set -S Perforce2 P4PORT=1667
p4 set -S Perforce2 P4LOG=log2
p4 set -S Perforce2 P4JOURNAL=journal2
Finally, use the Perforce service installer to start the
Perforce2
service:
svcinst start -n Perforce2.
The second service is now running, and both services will start automatically the next time you reboot.
Windows configuration parameter precedence
Under Windows, Perforce configuration parameters can be set in many different ways. When a Perforce application (such as p4 or P4V), or a Perforce server program (p4d) starts up, it reads its configuration parameters according to the following precedence:
-
For Perforce applications or a Perforce server (p4d), command-line flags have the highest precedence.
-
For a Perforce server (p4d), persistent configurables set with p4 configure.
-
The
P4CONFIG
file, ifP4CONFIG
is set -
User environment variables
-
System environment variables
-
The Windows user registry (or OS X user preferences) (set by p4 set)
-
The Windows system registry (or OS X system preferences) (set by p4 set -s)
When a Perforce service (p4s) starts up, it reads its configuration parameters from the environment according to the following precedence:
-
Persistent configurables set with p4 configure have the highest precedence.
-
Windows service parameters (set by p4 set -S
servicename
). -
System environment variables
-
The Windows system registry (or OS X user preferences) (set by p4 set -s)
User environment variables can be set with any of the following:
-
The MS-DOS set command
-
The AUTOEXEC.BAT file
-
The
tab under the dialog box in the Control Panel
System environment variables can be set with:
-
The
tab under the dialog box in the Control Panel
Resolving Windows-related instabilities
Many large sites run Perforce servers on Windows without incident. There are also sites in which a Perforce service or server installation appears to be unstable; the server dies mysteriously, the service can't be started, and in extreme cases, the system crashes. In most of these cases, this is an indication of recent changes to the machine or a corrupted operating system.
Though not all Perforce failures are caused by OS-level problems, a number of symptoms can indicate the OS is at fault. Examples include: the system crashing, the Perforce server exiting without any error in its log and without Windows indicating that the server crashed, or the Perforce service not starting properly.
In some cases, installing third-party software after installing a service pack can overwrite critical files installed by the service pack; reinstalling your most-recently installed service pack can often correct these problems. If you've installed another application after your last service pack, and server stability appears affected since the installation, consider reinstalling the service pack.
Users having trouble with P4EDITOR or P4DIFF
Your Windows users might experience difficulties using the Perforce
Command-Line Client (p4.exe) if they use the
P4EDITOR
or P4DIFF
environment
variables.
The reason for this is that Perforce applications sometimes use the DOS shell (cmd.exe) to start programs such as user-specified editors or diff utilities. Unfortunately, when a Windows command is run (such as a GUI-based editor like notepad.exe) from the shell, the shell doesn't always wait for the command to complete before terminating. When this happens, the Perforce client then mistakenly behaves as if the command has finished and attempts to continue processing, often deleting the temporary files that the editor or diff utility had been using, leading to error messages about temporary files not being found, or other strange behavior.
You can get around this problem in two ways:
-
Unset the environment variable
SHELL
. Perforce applications under Windows use cmd.exe only whenSHELL
is set; otherwise they callspawn()
and wait for the Windows programs to complete. -
Set the
P4EDITOR
orP4DIFF
variable to the name of a batch file whose contents are the command:start /wait
program
%1 %2where
program
is the name of the editor or diff utility you want to invoke. The/wait
flag instructs the system to wait for the editor or diff utility to terminate, enabling the Perforce application to behave properly.Some Windows editors (most notably, Wordpad) do not exhibit proper behavior, even when instructed to wait. There is presently no workaround for such programs.