Configuring the Server
The Perforce service is highly configurable and this is accomplished through the setting of server, client, and proxy configurables. Available configurables number in the hundreds, and it is probably best to set them as you continue to work with the server. This chapter limits itself to describing the configurables you might initially want to configure before you begin working with the server.
The following areas are covered:
-
Enabling distributed versioning
-
Using p4 typemap to determine a file's type and to implement site-wide exclusive locking
-
Defining additional depots
-
Managing client requests
-
Managing case sensitivity and Unicode installations
-
Configuring logging
-
Configuring P4V settings
For complete information about using the p4 configure command and all available server, client, and proxy configurables, see P4 Command Reference and p4 help configurables.
Enabling distributed versioning
If you need to enable the transfer of files between a user's local repository and the
shared repository, you must set the following configurables:
server.allowfetch
and server.allowpush
.
Defining filetypes with p4 typemap
Perforce uses the filesys.binaryscan
configurable to determine how
many bytes to examine when determining if a file is of type text
or
binary
. By default, filesys.binaryscan
is 65536; if
the high bit is clear in the first 65536 bytes, Perforce assumes it to be
text
; otherwise, it is assumed to be binary
. Files
compressed in the .zip
format (including .jar
files)
are also automatically detected and assigned the type ubinary
.
Although this default behavior can be overridden by the use of the -t
flag, it's easy for users to overlook this
consideration, particularly in cases where files' types are usually (but not always) detected
correctly. Certain file formats, such as RTF (Rich Text Format) and Adobe PDF (Portable
Document Format), can start with a series of comment fields or other textual data. If these
comments are sufficiently long, such files can be erroneously detected by Perforce as being of
type filetype
text
.
The p4 typemap command solves this problem by enabling system
administrators to set up a table that links Perforce file types with filename specifications.
If an entry in the typemap table matches a file being added, it overrides the file type that
would otherwise be assigned by the Perforce application. For example, to treat all PDF and RTF
files as binary
, use p4 typemap to modify the typemap
table as follows:
Typemap: binary //....pdf binary //....rtf
The first three periods ("...
") in the specification are a Perforce
wildcard specifying that all files beneath the root directory are to be included in the
mapping. The fourth period and the file extension specify that the specification applies to
files ending in .pdf
(or .rtf
).
The following table lists recommended Perforce file types and modifiers for common file extensions.
File type |
Perforce file type |
Description |
---|---|---|
|
|
Active server page file |
|
|
Video for Windows file |
|
|
Windows bitmap file |
|
|
Btrieve database file |
|
|
Conference link file |
|
|
Cascading style sheet file |
|
|
Microsoft Word document |
|
|
Microsoft Word template |
|
|
Export file (Microsoft Visual C++) |
|
|
GIF graphic file |
|
|
Gzip compressed file |
|
|
HTML file |
|
|
HTML file |
|
|
Icon file |
|
|
Active Server include file |
|
|
Initial application settings file |
|
|
JPEG graphic file |
|
|
JavaScript language source code file |
|
|
Library file (several programming languages) |
|
|
Log file |
|
|
MPEG video file |
|
|
Adobe PDF file |
|
|
Sybase Power Designer file |
|
|
Microsoft PowerPoint file |
|
|
Unity3D file |
|
|
Microsoft Excel file |
Use the following p4 typemap table to map all of the file extensions to the Perforce file types recommended in the preceding table.
# Perforce File Type Mapping Specifications. # # TypeMap: a list of filetype mappings; one per line. # Each line has two elements: # Filetype: The filetype to use on 'p4 add'. # Path: File pattern which will use this filetype. # See 'p4 help typemap' for more information. TypeMap: text //....asp binary+F //....avi binary //....bmp binary //....btr text //....cnf text //....css binary //....doc binary //....dot binary+w //....exp binary+F //....gif binary+F //....gz text //....htm text //....html binary //....ico text //....inc text+w //....ini binary //....jpg text //....js binary+w //....lib text+w //....log binary+F //....mpg binary //....pdf text+w //....pdm binary //....ppt binary //....xls
If a file type requires the use of more than one file type modifier, specify the
modifiers consecutively. For example, binary+lFS10
refers to a
binary
file with exclusive-open (l
), stored in full
(F
) rather than compressed, and for which only the most recent ten revisions
are stored (S10
).
For more information, see the p4 typemap page in the P4 Command Reference.
Implementing site-wide exclusive locking with p4 typemap
By default, Perforce supports concurrent development, but environments in which only one
person is expected to have a file open for edit at a time can implement site-wide exclusive
locking by using the +l
(exclusive open) modifier as a partial filetype. If
you use the following typemap, the +l
modifier is automatically applied to
all newly added files in the depot:
Typemap: +l //depot/...
If you use this typemap, any files your users add to the depot after you update your
typemap automatically have the +l
modifier applied, and may only be opened
for edit by one user at a time. The typemap table applies only to new additions to the depot;
after you update the typemap table for site-wide exclusive open, files previously submitted
without +l
must be opened for edit with p4 edit -t+l
filename
and resubmitted. Similarly, users with files
already open for edit must update their filetypes with p4 reopen -t+l
filename
.
Defining depots
By default, the standard depot Depot
is created in the server when the
server starts up. Depending on your user's needs, you can change its name and you can create
additional depots to serve your needs:
-
Additional standard depots allow you to organize user's work in relevant categories.
-
Stream depots are dedicated to the organization and management of streams.
-
Remote depots are used to facilitate the sharing of code.
-
A spec depot is used to track changes to user-edited forms such as workspace specifications, jobs, branch mappings, and so on.
-
Archive depots are used to offline storage of infrequently needed content.
-
Unload depots are used to offline storage of infrequently needed metadata.
Please see “Working with Depots” for more information.
Managing client requests
The following sections describe configuration options that relate to handling client requests.
Using P4PORT to control access to the server
Under most circumstances, your Perforce server's P4PORT
setting consists
of a port number. Users must know the IP address (or be able to resolve it from a hostname)
of the Perforce server in order to connect to it.
The value of P4PORT
however, can also include an IP address or hostname
that resolves to an IP address. You can set P4PORT
to configure the following
possibilities:
-
P4PORT
=portnumber
In this case, the server listens on the specified port for every ip address associated with this host.
-
P4PORT
=ipaddress
|hostname
:portnumber
In this case, the server listens on the specified port for the specified ip address or host name, and it ignores requests to any other ip address.
-
P4PORT
=localhost
:portnumber
In this case, the server listens on the specified port for requests that originate from users on this host. This forces the Perforce server to ignore all non-local connection requests.
P4PORT
might also specify a protocol (protocol
: address
: port
), which further
restricts possible connections to those using the specified protocol. For complete
information, see the description of the P4PORT
variable in the
P4
Command Reference.
Requiring minimum client revisions
The Perforce versioning service offers a mechanism to control which revisions of client applications are able to connect to Perforce.
To require a minimum revision, set the configurables minClient
to
the appropriate revision, and (optionally) set minClientMessage
to the
error message displayed when users of older applications connect to the server.
For example:
p4 configure set minClient=2010.2 p4 configure set minClientMessage="Please upgrade to 2010.2 or higher"
Rejecting client connection requests
You can set the rejectList
configurable to block one or more client
programs from accessing the Perforce server. By default, all clients may access the
server.
The simple version of the syntax for setting rejectList
is the
following:
rejectList = progName
[[,progName
]...]
The syntax of programName
is the following:
progName
[,version
=versionName
]
For example, the following command blocks requests from all command line clients.
p4 configure set "rejectList = p4"
The following command blocks requests from command line clients version 13.1 and 13.2.
p4 configure set "rejectList = p4, version=13.1, p4, version=13.2"
You may not use any wild card character in the program name parameter.
The comma is used as the default separator for the elements in
rejectList
. If the version number for the program you are excluding
includes a comma, you must use a slightly more complicated syntax to define
rejectList
:
rejectList = separator=char
progName
[[char
progName
]...]
If you define char
to be #, the previous command line would
look like this:
p4 configure set "rejectList = separator=# p4, version=13,1# p4# version=13,2"
The rejected connection is never logged; the log will not include information about the connection attempt.
You can specify a version using a build number; for example:
p4 configure set "rejectList = p4, version=1221235"
Or you can use platform information; for example:
p4 configure set "rejectList = p4, version=DARWIN90X86_64"
Or you can block for either condition; for example:
p4 configure set "rejectList = p4, version=1221235, p4, version=DARWIN90X86_64"
Note the use of quotation marks for strings that include spaces!
Important
If you accidentally lock out key clients needed to access the server, use the following command to unset the configurable:
p4d -r P4ROOT '-cunset rejectList'
Disabling user metrics collection prompt
P4V users have the option of enabling user metrics collection. By default no data is collected. The first time a user connects to the server, a prompt is displayed asking if the user wants to send Perforce anonymous user data. Such data includes information about system hardware, non-default user preferences, and so on. The user can subsequently change collection preference using the Preferences menu.
If you do not want users to see the prompt, you can set a property on the server as follows:
p4 property -a -n P4.DataAnalyticsPrompt -v off
This prevents the user from seeing the prompt. However, this is an incomplete solution, because if the user connects to a server that does not have the property set, they will see the prompt and might choose to send the data. To fully disable this feature, you will need to have IT shut down any outgoing POST requests to udc.perforce.com.
Case sensitivity and multi-platform development
Very early (pre-97.2) releases of the Perforce server treated all filenames, pathnames, and database entity names with case significance, whether the server was running on UNIX or Windows.
For example, //depot/main/file.c
and
//depot/MAIN/FILE.C
were treated as two completely different files.
This caused problems where users on UNIX were connecting to a Perforce server running on
Windows because the filesystem underlying the server could not store files with the
case-variant names submitted by UNIX users.
In release 97.3, the behavior was changed, and only the UNIX server supports case-sensitive names. However, there are still some case-sensitivity problems that users can encounter when sharing development projects across UNIX and Windows.
If you are running a pre-97.2 server on Windows, please contact
[email protected]
to discuss upgrading your server and database.
For current releases of the server:
-
The Perforce server on UNIX supports case-sensitive names.
-
The Perforce server on Windows ignores case differences.
-
Case is always ignored in keyword-based job searches, regardless of platform.
The following table summarizes these rules.
Case-sensitive |
UNIX server |
Windows server |
---|---|---|
Pathnames and filenames |
Yes |
No |
Database entities (workspaces, labels, and so on.) |
Yes |
No |
Job search keywords |
No |
No |
To find out what platform your Perforce server runs on, use p4 info.
Perforce server on UNIX
If your Perforce server is on UNIX, and you have users on both UNIX and Windows, your UNIX users must be very careful not to submit files whose names differ only by case. Although the UNIX server can support these files, when Windows users sync their workspaces, they'll find files overwriting each other.
Conversely, Windows users will have to be careful to use case consistently in filenames
and pathnames when adding new files. They might not realize that files added as
//depot/main/one.c
and //depot/MAIN/two.c
will
appear in two different directories when synced to a UNIX user's workspace.
The UNIX Perforce server always respects case in client names, label names, branch view
names, and so on. Windows users connecting to a UNIX server should be aware that the
lowercased workstation names are used as the default names for new client workspaces. For
example, if a new user creates a client workspace on a Windows machine named
ROCKET
, his client workspace is named rocket
by
default. If he later sets P4CLIENT
to ROCKET
(or
Rocket
, Perforce will tell him his workspace is undefined. He must set
P4CLIENT
to rocket
(or unset it) to use the client
workspace he defined.
Perforce server on Windows
If your Perforce server is running on Windows, your UNIX users must be aware that their Perforce server will store case-variant files in the same namespace.
For example, users who try something like this:
p4 add dir/file1
p4 add dir/file2
p4 add DIR/file3
should be aware that all three files will be stored in the same depot directory. The
depot pathnames and filenames assigned to the Windows server will be those first referenced.
(In this case, the depot pathname would be dir
, and not
DIR
.)
Setting up and managing Unicode installations
The following sections describe the benefits of running the Perforce server in Unicode mode and explain how you enable this mode.
Note
Converting a server to Unicode mode is a one-way operation! You cannot restore a Unicode server to its previous state.
Overview
The Perforce server can be run in Unicode mode to convert certain elements from their unicode representation on the server, to the particular character set used on clients connected to the server. The following elements are converted:
-
File names or directory names that contain Unicode characters
-
Perforce identifiers (for example, user names) and specifications (for example, changelist descriptions or jobs) that contain Unicode characters
If you need to manage textual files that contain Unicode characters, but do not need the features listed above, you do not need to run your server in Unicode mode. For such installations, assign the Perforce
utf16
file type to textual files that contain Unicode characters. -
unicode
files and metadata. These are converted to the character set configured on the user's machine.The Perforce server also verifies that the unicode files and metadata contain valid UTF-8 characters.
Normally, setting the server in Unicode mode should automatically configure the appropriate rendering for each client, independently of the platform where it runs. However, there are some cases in which you might also have to configure the client. The following subsections describe how you set up the server and the client if needed, and offer some troubleshooting tips.
Note
All p4d error and info logs are in UTF8 for a server in unicode mode. You need an UTF8 console or editor to properly render this log information.
Setting up a server for Unicode
How you configure a Unicode-mode server and the workstations that access it, depends on whether you are starting a server for the first time or whether you are converting an existing non-unicode server to unicode mode. The following sections explain each use case.
Note
The Perforce service limits the lengths of strings used to index job descriptions, to specify filenames and view mappings, and to identify client workspaces, labels, and other objects. The most common limit is 2,048 bytes. Because no basic Unicode character expands to more than three bytes, you can ensure that no name exceeds the Perforce limit by limiting the length of object names and view specifications to 682 characters for Unicode-mode servers.
Configuring a new server for Unicode
To configure a new server for Unicode, start the server using the following command:
p4d -xi -r server_root
[other
options
]
This command verifies that all existing metadata is valid UTF8, and then sets the
protected counter unicode
to indicate that the server now runs in
Unicode mode. If you stop and restart the server, it remains in Unicode mode. Once you
have placed the server in this mode, you cannot change it to non-unicode mode.
When a client connects to the server, it attempts to discover what the server's
setting is, and it sets the P4_
variable to reflect that setting. If the server is not in unicode mode, the variable is
set to port
_CHARSETnone
. If the server is set to Unicode, the variable is set to
auto
. Likewise, the client sets the P4CHARSET
variable to auto
. The client then examines its environment to figure
out what character set it needs to select.
The P4_
variable is stored in a
file called port
_CHARSET.p4enviro
. By default, this file is stored in the user's
home directory. To change the file location, the user must set the P4ENVIRO
variable to the desired path.
Configuring an existing server for Unicode
To convert an existing server to Unicode mode, perform the following steps:
-
Stop the server by issuing the p4 admin stop command.
-
Create a server checkpoint, as described in “Backup and Recovery”.
-
Convert the server to Unicode mode by invoking the server (p4d) and specifying the
-xi
flag, for example:p4d -xi -r
server_root
The server verifies that its existing metadata contains only valid UTF-8 characters, then creates and sets a protected configurable called
unicode
that is used as a flag to ensure that the next time you start the server, it runs in Unicode mode. After validating metadata and setting the configurable, p4d exits and displays the following message:Server switched to Unicode mode.
If the server detects invalid characters in its metadata, it displays error messages like the following:
Table db.job has 7 rows with invalid UTF8.
In case of such errors, contact Perforce Technical Support for instructions on locating and correcting the invalid characters.
-
Restart p4d, specifying server root and port as you normally do. The server now runs in Unicode mode.
When a client connects to the server, it attempts to discover what the server's
setting is, and it sets the P4_
variable to reflect that setting. If the server is not in Unicode mode, the variable is
set to port
_CHARSETnone
. If the server is set to Unicode, the variable is set to
auto
. Likewise, the client sets the P4CHARSET
variable
to auto
. The client then examines its environment to figure out what
character set it needs to select.
The default location of the P4_
variable depends on your operating system:
port
_CHARSET
-
On UNIX or on the Mac, the
P4_
variable is stored in a file calledport
_CHARSET.p4enviro
. By default, this file is stored in the user's home directory. To change the file location, the user must set theP4ENVIRO
variable to the desired path. -
On Windows, the
P4_
variable is stored in the registry. To store it in a file, use the p4 set P4ENVIRO command and specify the path of the file where you want to store the value.port
_CHARSET
Localizing server error messages
By default, the Perforce server informational and error messages are in English. You can localize server messages. To ensure best results, contact Perforce Technical Support. The following overview explains the localization process.
To localize Perforce server messages:
-
Obtain the message file from Perforce Technical Support.
-
Edit the message file, translating messages to the target language. Each message includes a two-character language code. Change the language code from
en
(English) to the code for the target language. Do not translate any of the key parameters or named parameters (which are specified between percent signs and single quotes, for example,%depot%
). You can change the order in which the parameters appear in the message.Original English:
@en@ 0 @db.message@ @en@ 822220833 @Depot '%depot%' unknown - use 'depot' to create it.@
Correct translation to Portuguese (note reordered parameters):
@pt@ 0 @db.message@ @pt@ 822220833 @Depot '%depot' inexistente - use o comando 'depot' para criar-lo.@
Although you are free to use any two-letter language code to designate the target language (so long as it's not "en," you might want to use a standard convention, such as the one described here:
http://www.w3schools.com/tags/ref_language_codes.asp
Many messages use Perforce command names. It is important to distinguish the word as a command name from the word as a description. For example:
@Depot '%depot%' unknown - use 'depot' to create it.@
In this case, 'depot' and '%depot%' should not be translated.
-
Load the translated messages into the server by issuing the following command:
p4d -jr /
fullpath
/message
.txtThis command creates a
db.message
file in the server root. The Perforce service uses this database file when it displays error messages. The Perforce proxy can also use thisdb.message
file; see the section on localizing P4P in Perforce Server Administrator Guide: Multi-site Deployment -
The character set of the resulting translation needs to be UTF-8 for unicode mode servers. That file should not have a leading Byte-order-mark (BOM).
If the target server is not in Unicode mode, the translation file does not need to be in UTF-8. In this case you might want multiple instances of the translated messages in multiple character sets. You can effect this by combining the language code field with a character set name. For example,
@ru_koi8-r@
to indicate Russian with akoi8-r
encoding versus@ru_iso8859-5@
to indicate Russian with an ISQ encoding. -
You can load translated message files into a p4d server by recovering them with the server's journal recovery command:
p4d -r
server_root
-jrtranslated_message_file
To view localized messages, set the P4LANGUAGE
environment variable on
user workstations to the language code you assigned to the messages in the translated
message file. For example, to have your messages returned in Portuguese, set
P4LANGUAGE
to pt
.
To view localized messages using P4V, you must set the LANG
environment variable to the language code that you use in the messages file.
Configuring clients for Unicode
When you set up a server to work in unicode mode, the client determines what character
set to use by examining the current environment and, generally, you should have nothing more
to do to get a correct translation. For example a UNIX client examines the
LANG
or LOCALE
variables to determine the appropriate
character set. However, there might be situations when you need to override the selection
made by the client:
-
The automatically selected setting is producing bad translations.
See Troubleshooting user workstations in Unicode installations for more information.
-
You want to use separate workspaces (clients) and each of these needs to use a different character set. In this case, you must set a different
P4CHARSET
value for each client. -
The files you check out need to be accessed by applications for which byte order is important.
See Unicode character sets and Byte Order Markers (BOMs) for more information.
-
You need to set
P4CHARSET
to anutf16
orutf32
setting.See Controlling translation of server output for more information.
-
The file is checked out using Perforce client applications that handle Unicode environments in different ways.
See Using other Perforce client applications for more information.
In each of these cases, you will need to explicitly set P4CHARSET
to an
appropriate value or take some other action. To get a list of the possible values for
P4CHARSET
, use the command:
p4 help P4CHARSET
Warning
Do not submit a file using a P4CHARSET
that is different than the one
you used to sync it; the file is translated in a way that is likely to be incorrect. That
is to say, do not change the value of P4CHARSET
while files are checked
out.
Unicode character sets and Byte Order Markers (BOMs)
Byte order markers (BOMs) are used in Unicode files to specify the order in which multi-byte characters are stored and to identify the file content as Unicode. Not all extended-character file formats use BOMs.
To ensure that such files are translated correctly by the Perforce server when the
files are synced or submitted, you must set P4CHARSET
to the character set
that corresponds to the format used on your workstation by the applications that access
them, such as text editors or IDEs. Typically the formats are listed when you save the
file using the menu option.
The following table lists valid settings for P4CHARSET
for specifying
byte order properties of Unicode files.
Client Unicode format |
BOM? |
Big or Little-Endian |
Set P4CHARSET to |
Remarks |
---|---|---|---|---|
UTF-8 |
No |
(N/A) |
|
Suppresses Perforce server UTF-8 validation |
Yes |
|
|||
No |
|
|||
Yes |
|
|||
UTF-16 |
Yes |
Per client |
|
Synced with a BOM according to the client platform byte order |
Yes |
Little |
|
Best choice for Windows Unicode files |
|
Yes |
Big |
|
||
No |
Per client |
|
||
No |
Little |
|
||
No |
Big |
|
||
UTF-32 |
Yes |
Per client |
|
Synced with a BOM according to the client platform byte order |
Yes |
Little |
|
||
Yes |
Big |
|
||
No |
Per client |
|
||
No |
Little |
|
||
No |
Big |
|
If you set P4CHARSET
to a UTF-8 setting, the Perforce server does not
translate text files when you sync or submit them. Perforce does verify that such files
contain valid UTF-8 data.
Controlling translation of server output
If you set P4CHARSET
to any utf16
or
utf32
setting, you must set the P4COMMANDCHARSET
to a
non-utf16
or non-utf32
character set in which you
want server output displayed. "Server output" includes informational and error messages,
diff output, and information returned by reporting commands.
To specify P4COMMANDCHARSET
on a per-command basis, use the
-Q
flag. For example, to display all filenames in the depot, as
translated using the winansi
code page, issue the following command:
p4 -Q winansi files //...
Using other Perforce client applications
If you are using other Perforce client applications, note how they handle Unicode environments:
-
P4V (Perforce Visual Client): the first time you connect to a Unicode-mode server, you are prompted to choose the character encoding. Thereafter, P4V retains your selection in association with the connection. P4V also has a global default setting for Charset. If you set this, it will be used instead of asking you to provide a charset.
-
P4Eclipse will ask for a charset when connecting to a Unicode-mode server.
-
P4Web: when you invoke P4Web, you can specify the character encoding on the command line using the
-C
flag. P4Web uses this flag when it sends commands to a Unicode-mode server. This approach means that each instance of P4Web can handle a single character encoding and that browser machines must have compatible fonts installed. -
P4Merge: To configure the character encoding used by P4Merge, choose P4Merge's menu option. When launched from P4V, P4Merge uses P4V's
P4CHARSET
instead of the one defined in it's preferences. -
IDE SCC plug-in: the first time you connect to a Unicode-mode server, you are prompted to choose the character encoding. Thereafter, the plug-in retains your selection in association with the connection.
-
P4GT and P4EXP use environmental settings and will fail with a Unicode-mode server.
Troubleshooting user workstations in Unicode installations
To prevent file corruption, it is essential that you configure your workstation correctly. The following section describes common problems and provides solutions.
-
"Cannot Translate" error message
This message is displayed if your workstation is configured with a character set that does not include characters that are being sent to it by the Perforce server. Your workstation cannot display unmapped characters. For example, if
P4CHARSET
is set toshiftjis
and your depot contains files named using characters from the Japanese EUC character set that do not have mappings in shift-JIS, you see the "Cannot translate" error message when you list the files by issuing the p4 files command.To ensure correct translation, do not use unmappable characters in Perforce user specifications, client specifications, jobs, or file names.
-
Strange display of file content
If you attempt to display an extended-character text file and see odd-looking text, your workstation might lack the font required to display the characters in the file. Typical symptoms of this problem include the display of question marks or boxes in place of characters. To solve this problem, install the required font.
Configuring logging
You might want to address the following issues in setting up logging. For information on setting up structured logging, see Logging and structured log files.
Logging errors
Use the -L
flag to p4d or the environment
variable P4LOG
to specify Perforce's error output file. If no error output
file is defined, errors are dumped to the p4d process' standard error.
Although p4d tries to ensure that all error messages reach the user, if
an error occurs and the user application disconnects before the error is received,
p4d also logs these errors to its error output.
Perforce also supports trace flags used for debugging. See Setting server trace and tracking flags for details.
Logging file access
If your site requires that user access to files be tracked, use the
-A
flag to p4d or the environment variable
P4AUDIT
to activate auditing and specify the Perforce's audit log file.
When auditing is active, every time a user accesses a file, a record is stored in the audit
log file. This option can consume considerable disk space on an active installation.
See Auditing user file access for details.
Configuring P4V settings
Not every site (nor every user at every site) requires the full suite of functionality in P4V, the Perforce Visual Client. By using the p4 property command, it is possible for an administrator to control which P4V features are available for a given site, group, or user. Properties relate to performance, features, or enabling the rich comparison of Microsoft .docx files. Performance and feature-related properties set at the server level override local P4V settings.
Configuring performance-related properties
If a user connects to a new Perforce service, performance-related properties are reloaded for the Perforce service to which the user has most recently connected.
Property |
Meaning |
---|---|
|
Number of changelists, jobs, branch mappings, or labels to fetch at any one time. |
|
Limits the number of files to check in the 'opened' call during a rollback operation. Default value is 1000. If the number of files to roll back exceeds the configured value, a popup informs the user that no opened check will be performed, and asks if the user wants to complete the operation. |
|
Maximum number of files displayed per changelist. |
|
Maximum number of files displayed per changelist. |
|
Maximum size of files to preview, in kilobytes. |
|
Number of time between display refreshes, in minutes. |
Configuring feature-related properties
You can use the following properties to enable or disable P4V features. These
properties are read once, upon P4V startup, from the first service to which the user
connects. Features that are deactivated by setting these properties to
Off
are unavailable in P4V and do not display in P4V's Preferences
page:
Property |
Meaning |
---|---|
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
|
If |
For example, the administrator of a site that does not use Perforce's built-in defect tracking can disable access to jobs from within P4V by running:
p4 property -a -n P4V.Features.Jobs -v Off
A new property is added/updated (-a
), it is named
(-n
) P4V.Features.Jobs
, and it is assigned the value
(-v
) of Off
.
If one group of users within the organization has a need to use the jobs functionality of P4V, the feature can be selectively (and centrally) re-enabled for those users with:
p4 property -a -n P4V.Features.Jobs -v On -g jobusers
The jobs feature of P4V is re-enabled by setting its value to On
,
but only for users in the jobusers
group.
Configuring Swarm connections
In order for P4V to connect to a Swarm server, it must know where the server is installed. Because Swarm is a web application, a URL can specify its location.
The Swarm or P4V administrator uses the P4.Swarm.URL[.serverid]
property to specify the location of a Swarm server.
-
To identify the location of a single Swarm server, use either the
P4.Swarm.URL
or theP4.Swarm.URL[.serverid]
syntax, depending on whether the server has a serverid. For example, the following command specifies that the location of the server given by 10.5.40.145:1666 ishttps://my_swarm_server.com
.p4 -p "10.5.40.145:1666" property -a -n P4.Swarm.URL -v "https://my_swarm_server.com"
-
To identify the location of several Swarm server instances, use the
P4.Swarm.URL[.serverid]
syntax, and specify the server id for each Swarm server each time you invoke the p4 property command. For example:p4 -p "10.5.40.145:1666" property -a -n P4.Swarm.URL.svr1 -v "https://my_swarm_server1.com" p4 -p "10.5.40.145:1667" property -a -n P4.Swarm.URL.svr2 -v "https://my_swarm_server2.com"
Using the serverid format is only necessary if you are using an authentication server (and multiple p4d instances are funneling through it) or if you are deploying multiple instances of Swarm against replicas or edge servers.
When P4V attempts to connect to a server that has no serverid, it checks to see if the
property P4.Swarm.URL
is set, and it uses that URL to access Swarm. If
the property is not set, P4V does not attempt to talk to Swarm.
When P4V attempts to connect to a server that has a serverid,
-
P4V asks the server for its server id and gets, for example,
svr1
. -
P4V checks the setting of
p4.Swarm.URL.svr1
, and it uses that URL to talk to Swarm -
If
p4.Swarm.URL.svr1
is not set, P4V checks the value ofp4.Swarm.URL
and uses that value to access the Swarm server. -
If
p4.Swarm.URL
is not set, P4V does not attempt to talk to Swarm.
If there is a value both for p4.Swarm.URL
and for
p4.Swarm.URL.myserverid
when P4V attempts to connect to a Swarm server,
the serverid match takes precedence over the generic match.
The user issuing the p4 property command must have an account on the specified Swarm server.
You can use the p4 property command to list the current properties of the Swarm server; for example:
# p4 -p "10.5.40.145:1666" property -I -A P4.Swarm.Timeout = 10 (any) #1 P4.Swarm.URL.master-1666 = https://my_swarm_server1.com
Enabling .docx diffs
You can use the P4.Combine.URL
property to enable the rich
comparison of Microsoft Word .docx
files through P4Merge. You must
deploy P4Combine as part of a Commons deployment to use this feature.
To enable the feature, set the P4.Combine.URL
server property to the
P4Combine Web Service URL. P4V will then display a rich compare of
.docx
files in the P4Merge window, using HTML5 to show differences
for text, images, formats, styles, tables, headers, footers, and other objects.
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.