Perforce Mac Products
Mac Command-line Interfaces (CLIs)
Managing Mac Files
A Note on PerformanceFurther Reading
Perforce Mac Products
|Operating System||Perforce Products|
Darwin: Apple's Open Source operating system, which is also the core of MacOS. Darwin is similar to FreeBSD UNIX. Darwin does not include the MacOS GUI libraries. Though Darwin supports HFS+ filesystems, it does not handle forked files or the Macintosh Type and Creator attributes. Darwin binaries are x86 only; "Universal" binaries containing PowerPC (PPC) code are no longer offered or supported. Darwin builds contain no Perforce Helix GUI tools.
IMPORTANT: The Perforce Helix server on Darwin is case-insensitive, unlike Perforce Helix servers on other UNIX platforms.
|• Perforce server (P4D, P4P, P4Broker)|
• Command-line interface (P4)
MacOS: Apple's UNIX-based operating system. MacOS runs on top of Darwin and includes Aqua, Carbon, Cocoa, and all Apple-specific development libraries and file types.
IMPORTANT: The Perforce server on MacOS is case-insensitive, unlike Perforce servers on other UNIX platforms.
• All Darwin Products
• P4V, P4Admin, P4Merge
The Mac Clients
The Mac clients can be used with any Perforce server, release 99.1 or greater. Perforce offers the following Mac clients:
Note: Both the MacOS and Darwin CLI can use the pre-2000.2 two-file scheme to handle resource forks. However, the clients handle apple files differently:
Installation of the Command Line Client (P4)
To install and use the Perforce Helix CLI only, use the Terminal application located in:
Download the CLI (p4) from the downloads page on the Perforce Web site
Place the CLI binary file (Darwin or MacOS) in a directory that is listed in the "PATH" environment variable. We recommend that you place this file in the /usr/local/bin directory.
Set the file permissions to enable the p4 CLI to be run:
sudo chmod +x /usr/local/bin/p4
Note: Starting with MacOS 11.11 (El Capitan) Apple has implemented a feature called System Integrity Protection (SIP). This feature, which is on by default, limits users (even those with root, or 'sudo' access) from writing to sensitive areas of the file system. Attempts to copy Perforce Helix executables to a path protected by SIP will produce an error:
sudo cp p4 /usr/bin/p4
cp: /usr/bin/p4: Operation not permitted
While possible to do so, disabling SIP is not recommended. Use /usr/local to store your Perforce binaries.
When issuing commands using the MacOS CLI:
- File paths: to specify path separators, use a forward slash (/), not a colon (:). To enter a file or folder's path, you can select the file or folder and drag it to the command window. Once dropped the full path will appear.
With either the Darwin or the MacOS CLI:
Line endings: use "unix" line endings in text files that you submit to the depot. You can configure your text editor to save files using "unix" line endings. Setting the Line ending to "local" on the Mac is equivalent to a setting of "unix". A setting of "mac" is for the old style Mac line endings (CR), however this option is deprecated and no longer supported.
Specifying a Perforce Forms Editor (for MacOS CLI only)
As of release 2002.1 and later you can specify any application to be the default editor. It may be a unix command-line editor, or a GUI application. You may specify the ".app" extension, but it's not required.
Editing Perforce Helix Specifications With TextEdit (for MacOS CLI only)
By default, you use TextEdit to edit Perforce Helix specifications (for example, client specifications, changelists, and so on). To exit and save your entries, select the TextEdit | Quit TextEdit menu item. Do not exit by closing the application window, as this will not return control to the command line.
Installing Perforce Helix graphical client applications in MacOS
Download the P4V disk image file (.dmg).
When you mount the P4V.dmg disk image it will open a new window on your desktop, showing three applications p4admin, p4merge and p4v.
Using the Finder, make the directory:
Drag and drop the three applications from the installer into this directory. You can then drag the three applications from
/Applications/Perforce onto your Dock to make them available from the Desktop.
Installing a Perforce Helix Server on MacOS
Note: These instruction assume you are installing both the Helix server and client at the same time.
Download the appropriate server from the Perforce Downloads page.
Open a Terminal window using the utility at
Move the p4d server and p4 CLI executables from the Downloads directory to the /usr/local/bin directory:
sudo mv ~/Downloads/p4d /usr/local/bin/p4d
sudo mv ~/Downloads/p4 /usr/local/bin/p4
Note: You will be prompted for your Administrator password. Once entered the command will run.
Make both moved files "executable" with this command:
sudo chmod +x /usr/local/bin/p4*
Create a perforce server directory:
sudo mkdir /usr/local/perforce
Set the permissions on this directory:
sudo chown $USER:admin /usr/local/perforce
Note: This is a good time to check both binaries to confirm they run as expected. Enter the commands:
You should see version and other information about the installed P4 executables. If you receive a permissions error, check that the executable bit set in step 4 was applied as expected:
ls -lah /usr/local/bin/p4*
This should display output similar to:
-rwxr-xr-x 1 a_user staff 4.1M May 5 02:45 /usr/local/bin/p4
-rwxr-xr-x 1 a_user staff 8.7M May 5 02:46 /usr/local/bin/p4d
If the "x" bits are missing re-run the chmod command.
Start the Perforce server:
p4d -r /usr/local/perforce -d -p 1666
This will start your server as a daemon on port 1666 in the
To test the server, enter the command:
p4 -p localhost:1666 info
Look for those two lines:
Server address: localhost:1666
Server root: /usr/local/perforce
If those lines appear as they do here then you've set up and started your Perforce server correctly.
Note: To stop the server, enter the command:
p4 -p 1666 admin stop
Perforce Server stopped...
To automatically launch the Perforce server as a daemon when the Mac host boots, refer to the knowledge base article Starting Perforce on Mac OS
For more information about starting daemons under Mac OS X, refer to Apple document on Creating Launch Daemons and Agents.
Managing MacOS Files
Perforce Helix File Types and MacOS File Types and Creator Attributes
When you add files to a Perforce depot, Perforce assigns each file a Perforce file type, which determines how the file is stored and whether it can be diffed. The Perforce file type is initially assigned by the Perforce client program with which you add the file. After the file is added, you can change the Perforce file type.
Perforce Helix MacOS client programs determine Perforce file type as follows:
MacOS client programs check the first 1024 bytes of the file's data fork and apply the following logic:
If the first 1024 bytes contain only text, the text file type is assigned.
If the first 1024 bytes contain any binary data, then files with resource forks are assigned the apple file type, and files without resource forks are assigned the binary file type.
Note: MacOS considers more characters as printable than UNIX and NT do (mostly the "option" modifier key characters). A file added from MacOS might be assigned the text file type, while the same file added from UNIX might be assigned the binary file type. Consider using p4 typemap to enforce the desired file type for those files.
Note: For classic Apple/Macintosh text files with resource and data forks, Perforce does not store the file type and creator information in the depot.
Mac File Forks
Note: This section remains for historical reasons for users that may still have some legacy resource fork files. Use of those files on Apple platforms is very rare currently, and is no longer supported by Apple itself.
Perforce handles Mac file forks as follows:
Pre 99.2 servers: The data and resource forks are stored as separate files. The resource fork is assigned a filetype of "resource" and its filename is preceded with a dot (.). For example, a Mac file named "myfile" is stored as "myfile" (data fork) and ".myfile" (resource fork).
99.2 and higher servers: Mac files are assigned the apple file type and stored in AppleSingle format on the server.
To change a file's Perforce file type after opening a file for add or edit in Perforce, use the following command:
p4 reopen -t filetype filename
Using the "apple" File Type (version 99.2 and later)
Perforce assigns the apple file type to Mac files that have the following characteristics:
When an apple file is synced to a non-Mac client workspace (version 99.2 or higher), it is stored on the client as AppleDouble. For example, Mac file "myfile", if synced to a non-Macintosh client workspace, is stored as "myfile" (data fork) plus "%myfile" (resource fork). Perforce Mac clients maintain only the file's data fork, resource fork, and finfo structure. Any other AppleSingle constructs are ignored when submitting or syncing files between the Mac client and the server.
If you sync an apple file to a Perforce 99.1 or earlier client, the file is stored on the client as a binary file, and is unreadable unless you use a third-party tool that reads AppleSingle files.
Warning: To avoid data corruption, do not assign the apple file type to non-Macintosh files.
Using the "resource" File Type (version 99.1 and earlier)
When working with Macintosh files using pre-99.2 Perforce servers, observe the following:
If you invoke p4 edit on either fork, the file is made writable. However, when you p4 submit only the opened fork is submitted. If you plan on changing both the resource and data forks, invoke p4 edit on both forks, for example:
p4 edit myfile .myfile
Deleting the resource fork does not delete the actual file. To delete a forked file, delete the data fork.
There is no way to compare resource forks. The .file contains both the resource fork and file header information. Because this information changes with each access to a file, p4 diff almost always reports that the resource fork has changed.
Pre-2002 non-Macintosh Perforce client applications cannot sync the resource fork of a depot file. Non-Macintosh Perforce client applications from version 2002 and higher receive a binary file.
File Naming Considerations
The Perforce Helix server on Darwin cannot save file paths that are not valid UTF-8. To ensure that UTF-8 paths are stored correctly, run your Darwin servers in International (Unicode) Mode. Mac OS and Darwin clients send file paths to Perforce Helix Servers in UTF-8.
For details about running a Perforce Helix server in International Mode, refer to KB article "Internationalization and Localization".
A Note on Performance
MacOS has had some TCP/IP network stack issues that seem to come and go depending on the version and patch level of the OS and the overall network topology. In particular I've seen significant performance problems with Mac clients connected to Linux and Solaris hosts.
A simple fix for this is to disable the stack's auto detection of when to employ delayed_ack:
Get the current value for net.inet.tcp.delayed_ack (default is 3):
sudo sysctl -a net.inet.tcp.delayed_ack
Try changing it to 2. You should immediately notice an improvement in network performance. (you can also try values of 0 and 1):
sudo sysctl -w net.inet.tcp.delayed_ack=2
net.inet.tcp.delayed_ack: 3 -> 2
This fix works for many types of network performance and compatibility issues with Samba, netatalk, FreeBSD, Linux, Solaris, and Windows.
To make this persistent across reboots you will need to use /etc/sysctl.conf. If this file does not exist, create it, or use the following command.
echo "net.inet.tcp.delayed_ack=2" | sudo tee -a /etc/sysctl.conf
For details about performance tuning the TCP/IP stack on MacOS refer to this article:"Performance Tuning the Network Stack on MacOS" (in particular take note of section 7, net.inet.tcp.delayed_ack).
Please refer to the Helix Versioning Engine Administrator Guide: Fundamentals for details on setting up your Perforce Helix Mac OS server.