Perforce Macintosh Platform Notes

Summary

How Perforce works on the Apple Mac OS

Details

Platform specific notes for other operating systems are found in Technical Note 19.

Perforce Macintosh Products

Macintosh Command-line Interfaces (CLIs)

• Installation of the CLI (P4)

Setting Environment Variables for Mac OS X GUI's

Managing Macintosh Files

• Macintosh File Type and Creator
• Macintosh File Forks
• File Naming Considerations

Perforce Macintosh Products

For the various Macintosh 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 Aqua (the new Mac OS X GUI), Cocoa, or Carbon. Though Darwin supports HFS+ filesystems, it does not handle forked files or the Macintosh Type and Creator attributes. 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 UNIX-based operating system. Mac OS X runs on top of Darwin and includes Aqua, Carbon, Cocoa, and all Apple-specific development libraries. IMPORTANT: While the Mac OS X PPC clients will work under Rosetta emulation on Intel based Macs, the Mac Intel binaries should be used whenever possible. The server (P4D) should never be run under emulation -- only use the Apple Darwin x86 P4D on Intel Macs.	There is no Perforce Server (P4D) built specifically for Mac OS X (Use the Darwin one) Command-line interface (P4) P4Web CodeWarrior plug-in (Carbonized).

The Macintosh Clients

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

• Perforce CLI (P4): enables you to issue Perforce commands from a command-line prompt.
• P4Web: enables you to use a Web browser to perform Perforce operations.
• CodeWarrior Plugin: enables you to perform some Perforce operations from within the CodeWarrior IDE.

The following table describes the Macintosh client applications in more detail:

Client					CodeWarrior Plugin 1			Darwin Perforce CLI			Mac OS X Perforce CLI
Platform					Mac OS X			Darwin / Mac OS X			Mac OS X
GUI?					yes			no			no
Supports dual-forked files					yes			no 2			yes 2
InternetConfig File-Typing					yes			no			no
Additional Requirements					CodeWarrior			none			none
Line Endings					Line Feed			Line Feed			Line Feed
Path Separators					'/'			'/'			'/'
File-Locking Technique					UNIX Permissions			UNIX Permissions			UNIX Permissions

Notes

1. Because the API upon which the CodeWarrior plugin is built differs from the APIs that the two CLIs were built with, it is recommended you do not use the CodeWarrior plugin with either of the CLIs.
2. 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 CLI (P4)

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

	<System>/Applications/Utilities/Terminal

1. Download the CLI from the Perforce Web site downloads page (http://www.perforce.com/loadprog.html)
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 /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, note the following:

• 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, choose Quit TextEdit from the menu. Do not exit by closing the application window.

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 can't connect to a unicode enable server without setting the P4CHARSET variable. Setting environment variable 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 will need to do this using the Terminal application located in the /Application/Utilities folder. Launch the application and enter this command:

       mkdir ~/.MacOSX

2. Create a text file called environment.plist using a text editor.

3. Insert the following text into this file:

       <?xml version="1.0" encoding="UTF-8"?>
       <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" 
           "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
           <plist version="1.0">
       <dict>
           <key>P4CHARSET</key>
           <string>utf8</string>
       </dict>
       </plist>
   

   Note that most text editors (such as Apple's TextEdit) won't 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 will appear that will allow you to enter a path to the folder. Enter ~/.MacOSX and click "Go". The Finder will open 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. For example, launch XCode - you will now be able to access a unicode enabled server.

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:

/Developer/Applications/Utilities/

For more information about this technique, take a look at the Apple Q&A page at:

Technical Q&A QA1067
Setting environment variables for user processes

http://developer.apple.com/qa/qa2001/qa1067.html

Managing Macintosh Files

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

Mac OS X client programs check the first 1024 bytes of the files 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 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. The CodeWarrior plugin can use InternetConfig mappings to assign the Macintosh file type and creator. However, the only time it does this is when a file is being written to disk for the first time. The first time you sync a file, the Macintosh file type and creator are assigned. Thereafter, those file attributes is not touched unless you remove the file from your client workspace.

Macintosh File Forks

Perforce handles Macintosh 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 Macintosh 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, 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 that have the following characteristics:

• The file has a Macintosh file type other then text.
• The file has a non-zero length resource fork.

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 Macintosh 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 Macintosh 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 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, on 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'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 Macintosh files to your Macintosh 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 on Darwin cannot save filepaths 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 filepaths to Perforce Servers in UTF-8.

For details about running Perforce in International Mode, refer to technical note 066.