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

 

Article

Perforce Platform Notes - Apple Macintosh

« Go Back

Information

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

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

Perforce Mac Products

Mac Command-line Interfaces (CLIs)

Managing Mac Files

A Note on Performance

Perforce Mac Products

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

Operating SystemPerforce 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
• P4FTP

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

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:

<System>/Applications/Utilities/Terminal
  1. Download the CLI (p4) from the downloads page on the Perforce Web site

  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/local/bin directory.

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

    sudo chmod +x /usr/local/bin/p4	

Note: Starting with Mac OS X 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 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.

Issuing Commands

Note: When issuing commands using the Mac OS X CLI:

  • 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 and later 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, as this will not return control to the command line.

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:

/Applications/Perforce 

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 Server on MacOS X

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

  2. Open a Terminal window using the utility at /Applications/Utilities/Terminal.app.

  3. Move the server executable from the Downloads directory to the /usr/local/bin directory:

    mv ~/Downloads/p4d /usr/local/bin/p4d
  4. Make this file "executable" with this command:

    chmod +x /usr/local/bin/p4d	

    Note: As of Mac OS X 11.11 (El Capitan) System Integrity Protection (SIP) limits the locations of Perforce command line binaries and other files to the /usr/local path.

  5. Create a perforce server directory:

    sudo mkdir /usr/local/perforce	
  6. Set the permissions on this directory:

    chown $USER:admin /usr/local/perforce	

    Note: This is a good time to check the server binary to confirm that it runs as expected. Enter the command:

    p4d -V

    You should see the server version and other information about the installed P4D executable.

  7. 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 /usr/local/perforce directory.

To test the server, enter the command:

p4 -p 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

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 X 

For more information about starting daemons under Mac OS X, refer to 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".

A Note on Performance

Mac OS X 10.x 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 we'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
net.inet.tcp.delayed_ack: 3


Try changing it to 2 and you should immediately notice a difference (tyou may also try values of 0 and 1)

$ sudo sysctl -w net.inet.tcp.delayed_ack=2
net.inet.tcp.delayed_ack: 3 -> 2


We're not sure why OS X ships with a default of 3. 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 Mac OS X refer to this article: "Performance Tuning the Network Stack on Mac OS X" (in particular take note of section 7. net.inet.tcp.delayed_ack).

Related Links

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255