Perforce Macintosh Notes

Revised April 11, 2003

These notes provide additional information about using Perforce on Macintosh. You can find all past and present versions of the Perforce clients and server on our ftp site. For general product information, see the Perforce home page

Warning: A bug in Mac OS 10.2 (Jaguar) affects Perforce's ability to change the modification date of files that it has touched. We are unable to reproduce it with Mac OS 10.2.2.

Perforce Macintosh Products

Macintosh Clients

MPW Tool

Darwin client (P4)

Mac OS X client (P4)

Managing Macintosh Files

Macintosh file type and creator

line endings

Macintosh file forks

file naming considerations


Perforce Macintosh Products

For the various Macintosh platforms, Perforce offers the following products.

Operating System Perforce products

Classic: OS 9.x and below, which supports the classic Mac Toolbox and programs linked to the Carbon libraries.

  • MPW tool
  • CodeWarrior plug-in for CWPro 5
  • CodeWarrior plug-in for CWPro 7 (Carbonized)
  • P4Web
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 Aqua (the new Mac OS X GUI), Cocoa, or Carbon. Though Darwin supports HFS+ filesystems, it does not handle forked files or Macintosh Type and Creator attributes.

Note: the Darwin client on Mac OS X relies exclusively on Unix permissions to lock and unlock files. When you run Carbon applications on those files that you synced with the Darwin client, the Carbon apps treats those files as unlocked even though it cannot write to them. To avoid this problem, use the Mac OS X client. To lock or unlock files to solve this problem, set the immutable bit using the chflags command: chflags nouchg filename.

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

  • Perforce server (P4D)
  • Command-line interface (P4)
  • P4Web
Mac OS X: Apple's new UNIX-based operating system. Mac OS X runs on top of Darwin and includes Aqua, Carbon, Cocoa, and all Apple-specific development libraries.
  • There is no Perforce Server (P4D) built specifically for Mac OS X (Use the Darwin one)
  • Command-line interface (P4)
  • CodeWarrior plug-in for CWPro 7 (Carbonized)
  • P4Web


The Macintosh Clients

The Macintosh clients may be used with any Perforce server, release #99.1 or greater. Perforce offers the following Macintosh clients:

The following table describes the Macintosh clients in more detail.

Client Platform GUI? Supports dual-forked files InternetConfig File-Typing Additional Requirements Line Endings Path Separators File-Locking Technique
MPW Tool Classic Mac OS no yes yes MPW Carriage Return ':' HFS+ Immutable Bit
CodeWarrior Plugin Classic Mac OS / Mac OS X yes yes yes CodeWarrior Carriage Return ':' HFS+ Immutable Bit
Darwin Perforce Client Darwin / Mac OS X no no no none Line Feed '/' UNIX Permissions
Mac OS X Perforce Client Mac OS X no yes no none Line Feed '/' HFS+ Immutable Bit

Notes

The MPW Tool

Before you install the Perforce MPW Tool, you must install MPW.

To install the MPW tool:

  1. Download the Perforce MPW client tool from the Perforce Web site downloads page (http://www.perforce.com/loadprog).
  2. Copy the downloaded file into the MPW:User Commands folder.
  3. Launch MPW.
  4. In MPW, set the following variables.
    set -e P4USER <Your user name as seen by Perforce.> (USER is used as a default.)
    Set -e P4PORT <The address of the Perforce server.> (The default is perforce:1666 [host perforce, port 1666].)
    set -e P4CLIENT <The name of your client workspace.> (The default is your computer's name, as identified by its Internet address)

To automatically set these variables when you reboot, put the preceding "set" commands into an MPW script, for example MPW:Startup Items:UserStartup•Perforce.

To verify that you have successfully installed the MPW Tool, issue the P4 command from MPW. If the MPW Tool is installed correctly, it displays a list of common Perforce commands.

Issuing commands

When you issue commands in MPW, you must press the ENTER key, normally located on the numeric keypad, and not the RETURN key.

Specifying file names in P4 commands

To ensure that MPW does not attempt to parse Perforce file specification that include special characters (specifically "/", "#", "...", and "*"), enclose such file specification in single or double quotes. For example:

Right: p4 sync -n "//depot/.../myfile#none"

Wrong: p4 sync -n //depot/.../myfile#none (because MPW treats characters following "#" as a comment)

Handling line endings

The MPW Tool reads and writes text files using Macintosh line endings.

The Darwin Client (P4)

To install the Darwin client:

  1. If the /usr/local/bin/ directory does not exist, create it.
  2. Download the Darwin client from the Perforce Web site downloads page (http://www.perforce.com/loadprog.html) to /usr/local/bin/.

For details about using the Perforce command line client, see the Perforce user documentation and release notes.

The Mac OS X Client (P4)

To install and use the Perforce Mac OS X client, use the Terminal application located in <System>/Applications/Utilities/Terminal.

To install the Mac OS X client:

  1. If the /usr/local/bin/ directory does not exist, create it.
    1. type 'sudo mkdir /usr/local/bin'
    2. type your password
  2. Download the Mac OS X client from the Perforce Web site downloads page (http://www.perforce.com/loadprog.html) to /usr/local/bin/.
  3. Set the file permissions to allow the p4 client to be run: chmod +x /usr/local/bin/p4

Issuing commands

When issuing commands using the Mac OS X command line client, note the following:

Specifying an editor

As of r02.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 you don't have to.

Editing Peforce specifications with TextEdit

By default, you use TextEdit to edit Perforce specifications (for example, client specifications, changelists, and so on). To exit and save your entries, choose Quit TextEdit from the menu. Do not exit by closing the application window.

Unlocking Files when Deleting a Client Workspace or Emptying Trash

If you need to delete a client workspace that contains locked files, use the SetFile command (available on the Macintosh Developer Tools CD) in conjunction with the find command to unlock the files. (SImilarly, you might need to unlock files in the trash before emptying it.)

The following commands enable you to lock or unlock multiple files.

find . -type f -print0 | xargs -0 -n 1 SetFile -a l Unlocks all the files in the current directory and below
find . -type f -print0 | xargs -0 -n 1 SetFile -a L Locks all the files in the current directory and below


Managing Macintosh Files

Macintosh file type and creator

When you add files to a Perforce depot, Perforce assigns each file a file type, which determines how the file is stored and whether it can be diffed. The 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 file type.

Perforce Macintosh client programs determine file type as follows:

Note that Macintosh considers more characters printable than UNIX and NT do (mostly the "option" characters). A file added from the Mac might be assigned the text file type -- the same file added from UNIX might be assigned the binary file type.

For text files, Perforce does not store the Macintosh file type and creator information in the depot. When you sync a file from the depot to your client workspace, the Perforce client uses InternetConfig mappings to assign the file type and creator. After you open your file for edit, you can change the Macintosh file type and creator, and your changes are saved when you submit the file to the depot. However, if you remove the file from your client workspace, then sync it again, the file type and creator are reassigned according to the InternetConfig mappings. In short: for text files, the first time you sync, the file type and creator are assigned. Thereafter, the file type/creator information is not changed unless you remove the file from your client workspace.

Line endings

The line ending character used in a text file depends on the platform on which the file originates. The following table lists the conventions.

Platform Line ending
UNIX Linefeed (LF)
Windows Carriage return Linefeed (CRLF)
Macintosh Carriage return (CR)

In the Perforce depot, text files are stored using UNIX line endings. Perforce client workspaces can be configured to translate line endings to the convention used by the client platform, or to perform no translation when files are synced. To set the line ending option, edit your client specification. (see "p4 help client")

When you edit text files, your text editor can change the line ending when you save the file. If you inadvertently submit text files containing Macintosh line endings to the depot, the Perforce server will be unable to diff these files, which it must do to store your changes. To avoid this problem, configure your text editor to save files using UNIX line endings.

Macintosh file forks

Perforce handles Macintosh file forks as follows.

To change a file's Perforce file type, use the p4 reopen -t filetype filename command.

Using the apple file type (version 99.2 and later)

Perforce assigns the apple file type to Macintosh files with the following characteristics:

When an apple file is synced to a non-Macintosh client workspace (version 99.2 or higher), it is stored on the client as AppleDouble. For example, Macintosh 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 99.1 or earlier client, the file is stored on the client as a binary file, and will be 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)

In version 99.1 and earlier, Perforce stores data and resource forks in separate files. The resource fork is assigned the original file name with a period pre-pended. When working with Macintosh files using pre-99.2 Perforce servers, observe the following:

Changing resource files to apple files

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

  1. Install the 99.2 server and client.
  2. Sync the most recent file revisions of all Mac files to your Mac client.
  3. Use p4 edit -t apple on all files with resource forks.
  4. Use p4 delete to delete all the old resource forks (they all begin with a dot: ".").
  5. p4 submit the deletions and edits from the last two steps.

File naming considerations

The Perforce server can now handle spaces in file names (spaces are very common in Mac file names), but not characters that the server machine considers to be non-printable. Thus the Mac "option" characters cannot appear in filenames stored in the Perforce server. Mac files with /'s in their names are likely to cause problems, as Perforce considers / to be a path separator.

The following are required to handle files with names longer than 31 characters


$Id: //depot/r03.2/p4-doc/user/macnotes.html#1 $