Perforce Macintosh Notes

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:

• MPW Tool: enables you to issue Perforce commands from within the Macintosh Programmer's Workshop.
• CodeWarrior Plugin: enables you to perform some Perforce operations from within the CodeWarrior IDE.
• Perforce command-line client (P4): enables you to issues Perforce commands from a command line prompt.
• P4Web: enables you to use a Web browser to perform Perforce operations.

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

• Both the Mac OS X and Darwin client can use the pre-2000.2 two-file scheme to handle resource forks. However, the clients handle apple files differently: The Mac OS X client syncs apple files into one file with two forks. The Darwin client syncs apple files to the client as two files: "file" and "%file".
• Dual-boot OS 9/OS X systems must allocate separate workspaces for each OS, to avoid file locking problems.
• If you use an HFS+ disk and run Mac OS 9 an greater, you will be able to sync files with >31 characters in their names.

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:

• 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.
• Line endings: use UNIX line endings in text file you submit to the depot. You can configure your text editor to save files using UNIX line endings.

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.

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:

• Mac Classic client programs use the InternetConfig mappings.
• 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. 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.

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.

• Pre 99.2 servers: The data and resource forks are stored are 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.

Using the apple file type (version 99.2 and later)

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

• The file has a Macintosh file type other then text
• The file has 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 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:

• 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 good way of comparing resource forks. The .file actually contains both the resource fork and file header information. Because this information changes with each access to a file, p4 diff will almost always report that the resource fork has changed.
• Pre-2020 non-Mac clients cannot sync the resource fork of a depot file. Non-Mac clients from version 2020 on 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 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

• OS 9 or greater
• HFS+ disk
• Perforce release 2002.1 or higher

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