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

Perforce Macintosh Products

Macintosh Clients

MPW Tool

Darwin client (P4)

OS X client (P4)

Managing Macintosh Files

Perforce file types

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 Carbon. ("Carbon" is a portability layer that is similar to the Mac Toolbox, but runs both on Classic MacOS and OS X. Carbon enables developers to port their classic Mac Toolbox-based code to MacOS X.)	MPW tool CodeWarrior plug-in 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 MacOS X GUI), Cocoa, or Carbon. Though Darwin supports HFS+ filesystems, it does not handle forked files or Macintosh Type and Creator attributes. Note: If you use the Darwin client on MacOS X and run the p4 edit command, any Carbon applications you use on that file will believe that the file is still locked. To avoid this problem, use the MacOS X client. IMPORTANT: The Perforce server on Darwin is case-insensitive, unlike Perforce servers on other UNIX platforms.	Perforce server (P4D) Command-line interface (P4) P4Web
OS X: Apple's new UNIX-based operating system. 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) 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 Workbench.
• 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 MacOS	no	yes	yes	MPW	Carriage Return	':'	HFS+ Immutable Bit
CodeWarrior Plugin	Classic MacOS	yes	yes	yes	CodeWarrior	Carriage Return	':'	HFS+ Immutable Bit
Darwin Perforce Client	Darwin / MacOS X	no	no	no	none	Line Feed	'/'	UNIX Permissions
MacOS X Perforce Client	MacOS X	no	yes	no	none	Line Feed	'/'	HFS+ Immutable Bit

Notes

• Both the 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 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.
• On Classic MacOS versions preceding OS X, directory and file names cannot exceed 31 characters.

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 OS X Client (P4)

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

To install the 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 OS X client from the Perforce Web site downloads page (http://www.perforce.com/loadprog.html) to /usr/local/bin/.

Issuing commands

When issuing commands using the 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.

Deleting a Client Workspace

Sometimes you may want to delete all the files in a client workspace, either to change the root of the client of for some other reason. Some of you may have experienced trouble with emptying the trash when it contains locked files. This is a problem with the Mac OS X finder and not perforce.

It is possible to bulk lock/unlock files from the command-line. Here are some commands that will help you...

Managing Macintosh Files

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.

Macintosh file type and creator

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.

When you edit text files, your text editor can change the line ending when you save the file. If you disable translation of line endings on a Macintosh client, you might inadvertently submit text files containing Macintosh line endings to the depot. The Perforce server cannot diff such 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 the original file name with a period prepended. 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.

$Id$