Perforce Public Knowledge Base - Perforce Platform Notes - Apple Macintosh
Reset Search



Perforce Platform Notes - Apple Macintosh

« Go Back


This article details the use of Perforce on the Apple Mac OS.

Platform specific notes for other operating systems are found in KB Article "Various-Platform-Notes".

Perforce Mac Products

Mac Command-line Interfaces (CLIs)

Setting Environment Variables for Mac OS X GUI's

Managing Mac Files

Perforce Mac Products

For the various Mac platforms, Perforce offers the following products:

Operating System Perforce Products

Darwin: Apple's Open Source operating system, which is also the core of Mac OS X. Darwin is similar to FreeBSD UNIX. Darwin does not include the  Mac OS X GUI libraries. Though Darwin supports HFS+ filesystems, it does not handle forked files or the Macintosh Type and Creator attributes.  Darwin binaries are universal binaries which will run on both PowerPC and x86 based Macs.  Darwin builds contain no Perforce GUI tools.

IMPORTANT: The Perforce server on Darwin is case-insensitive, unlike Perforce servers on other UNIX platforms.

• Perforce server (P4D, P4P, P4Broker)
• Command-line interface (P4)
• P4Web

Mac OS X: Apple's UNIX-based operating system. Mac OS X runs on top of Darwin and includes Aqua, Carbon, Cocoa, and all Apple-specific development libraries and file types.

IMPORTANT: The Perforce server on Mac OS X is case-insensitive, unlike Perforce servers on other UNIX platforms.

• All Darwin Products
• P4V, P4Admin, P4Merge
• P4Eclipse
The Mac Clients

The Mac clients can be used with any Perforce server, release 99.1 or greater. Perforce offers the following Mac clients:

  • Perforce CLI (P4): enables you to issue Perforce commands from a command-line prompt

  • P4V: Provides a graphical interface and tools for merging and visualizing code evolution

  • P4Web: enables you to use a Web browser to perform Perforce operations.

  • P4FTP: enables access to a repository using ftp.

Note: Both the Mac OS X and Darwin CLI can use the pre-2000.2 two-file scheme to handle resource forks. However, the clients handle apple files differently:

  • The Mac OS X CLI syncs apple files into one file with two forks.

  • The Darwin CLI syncs apple files to the client as two files: "file" and "%file".

Installation of the Command Line Client (P4)

To install and use the Perforce CLI, use the Terminal application located in:

  1. Download the CLI from the Perforce Web site downloads page.

  2. Place the CLI binary file (Darwin or Mac OS X) in a directory that is listed in the "PATH" environment variable. We recommend that you place this file in the /usr/bin directory.

  3. Set the file permissions to enable the p4 CLI to be run:

    sudo chmod +x /full_path_to/p4

Issuing Commands

When issuing commands using the Mac OS X CLI, note the following:

  • File paths: to specify path separators, use a forward slash (/), not a colon (:). To enter a file's path, you can select the file and drag it to the command window.

With either the Darwin or the Mac OS X 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).

Specifying a Perforce Forms Editor (for Mac OS X CLI only)

As of release 2002.1, you can specify any application to be the default editor. It may be a unix command-line editor, a Carbon application, or a Cocoa application. You may specify the ".app" extension, but it's not required.

Editing Perforce Specifications With TextEdit (for Mac OS X CLI only)

By default, you use TextEdit to edit Perforce 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.

Installing Perforce graphical client applications in Mac OS X

Download the P4V installer from the Perforce Downloads page.

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 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.

Setting Environment Variables for Mac OS X GUI Applications

Some IDE's with integrated Perforce SCM support do not present a way for you to pass some Perforce settings that you might need to connect to the Perforce server. For example, if you try to use XCode's built in Perforce support, you cannot connect to a unicode enable server without setting the P4CHARSET variable. Setting environment variables using the Terminal application only works for the command line environment.

Fortunately Apple does provide a technique to set environment variables for GUI applications launched from the Finder:

  1. Create a directory called .MacOSX in your home directory. You need to do this using the Terminal application located in the /Application/Utilities folder. Launch the application and enter the following command:

    mkdir ~/.MacOSX
  2. Create a text file called environment.plist using a text editor.

  3. Insert the following text into this .plist file:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
    <plist version="1.0">

    Note: Most text editors (such as Apple's TextEdit) do not allow you to save to a hidden directory. To get around this limitation, save the file to your home directory. To move it to the .MacOSX directory, select the "Go -> Go To Folder..." menu item in the Finder -- a dialog appears that allows you to enter a path to the folder. Enter ~/.MacOSX and click "Go". The Finder opens the hidden directory, allowing you to drag the environment.plist file to this folder.

  4. Log out of the Mac OS X user account, and log back in.

  5. Test the GUI application.  You can now access a unicode enabled Perforce server.

Note: You can use this same technique to set any environment variable, such as P4PORT, P4CLIENT, P4USER, and so forth.

You may find it easier to edit this file using an Application called 'Property List Editor' (rather than manually editing the XML text file). This utility is installed with Apple's Developer Tools and can be found under the following path:


More information exporting shell variables can be found on Apple's developer site, in their "Shell Scripting Primer".

Installing a Perforce Server on MacOS X

  1. Download the appropriate server from  the Perforce Downloads page.

  2. The file name is p4d with no extension. Copy this file to:


    Note: Create this directory if it does not exist

    Note: The Perforce server executable can be placed in any accessible location on the Mac OS file system, but for the purposes of this article we will use the Applications directory path.

  3. Create a perforce server directory:

  4. Open a Terminal window, navigate to your server directory, then start the server by running:

    /Applications/Perforce/p4d -d -p 1666

    This will start your server as a daemon on port 1666 in your current working directory. You will be able to quit the server using control-c (or closing the terminal window). Open a second terminal window to test the server with the p4 info command.

To automatically launch the Perforce server as a daemon when the Mac host boots, refer to this Apple document on Creating Launch Daemons and Agents.

Managing Mac Files

Perforce File Types and Mac 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 Mac client programs determine Perforce file type as follows:

Mac OS X 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: The Mac considers more characters as printable than UNIX and NT do (mostly the "option" modifier key characters). A file added from the Mac might be assigned the text file type, while the same file added from UNIX might be assigned the binary file type.

Note: For classic Mac text files with resource and data forks, Perforce does not store the Mac file type and creator information in the depot.

Mac File Forks

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:

  • The file has a Mac file type other than text.

  • The file has a non-zero length resource fork.

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.

Changing Resource Files to "apple" Files

If you are using the old resource file type, and want to change to the new apple scheme:

  1. Install the 99.2 or higher server and client.

  2. Sync the most recent file revisions of all Macintosh files to your Macintosh client.

  3. For all files with resource forks enter the following:

    p4 edit -t apple
  4. Use p4 delete to delete all the old resource forks (they all begin with a dot: ".").

  5. Use p4 submit the deletions and edits from the last two steps.

File Naming Considerations

The Perforce 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 OSX and Darwin clients send file paths to Perforce Servers in UTF-8.

For details about running Perforce in International Mode, refer to KB article "Internationalization and Localization".

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255