I recently went on an adventure to set up Perforce so I had source control for the game I’m working on. Obviously, source control is incredibly important, so I didn’t want to get too into the work I’m doing before it got set up. But being, perhaps, rare in my desire to run it on mac as opposed to Windows or Linux, I ran into some initial hurdles while trying to figure it out. While, in the end it wasn’t difficult to set up, I had to go digging for how to run the perforce server since their docs didn’t include instructions that worked for mac.

Acquire and set up the Perforce server

1. Acquire the Perforce Server Software.
2. Unzip the .tgz archive file
3. Move the files to folder where you’d like to run the server from. For example, ~/server.
4. Launch the Perforce Server. Open the terminal of your choice and navigate to the folder, then run ./p4d. If this is the first launch, it will do some setup and you’ll need to run ./p4d again to start.

If you encounter errors when running the server see the Troubleshooting section for possible fixes.

Acquire and set up Perforce Visual Client

1. Download the Perforce Visual Client.
2. Install the p4v app
3. Launch p4v

Create an account and login

1. On the p4v Open Connection screen click New next to the User box
2. Input user name and password. This information is local to the server and isn’t validated anywhere.
3. Set the Server to the correct location. When run on the same machine, you can use localhost:<port>. The default port is 1666.
4. Input your username and click connect
5. Input your password if you set one
6. When prompted about superuser access, click yes to proceed. This means your account will have full control of everything and access to the admin panel. You’ll have to control permissions, create depots, etc through the admin panel. This can be transferred to other accounts.

Configure and setup

1. Configure security. Note that when running a local server that’s only accessible on your home network, you don’t need level 3.
2. Create a new depot. A depot is the shared repository where the code lives. Files are checked in and out from it.
3. Create a new stream. Streams are similar to branches in git, and is a source of code in the depot that is modified independent of other streams. This allows for testing and iteration of changes without modifying the main code.
4. Create a workspace. This is just the folder where the code will exist. In this step, you’ll be creating it for the server.

Configure Unreal

Set the typemap

A typemap tells perforce how to handle certain files. It seems vaguely similar to a gitignore file. I haven’t looked too much into it, just copied from Unreal’s example for now. Unreal’s docs have a clear guide to setting up the typemap, however I found a Mac specific issue in following their steps that I wanted to clarify here.

1. In Terminal, navigate to the server location on your machine (~/server)
2. Type ./p4 typemap (If you’ve installed Perforce’s command line tools you should be able to just type p4 typemap)
3. A text window will open with the default typemap file. Copy and paste the example from Unreal’s docs into the file.
4. Save the file, then close it. Important note for mac: Make sure the application is fully closed, and not just closed the window. You’ll know if it’s closed fully as the terminal will either indicate “typemap saved” or display an error. If you close the window and the message doesn’t appear, make sure to right click and close your text editor from your dock.

Set up Unreal for source control

Either move your existing file to your workspace folder or create a new project in that folder. Then follow Unreal’s guide to setting up perforce in Unreal.

Troubleshooting

P4 Server: Error: perforce server error: listen <port number> failed. TCP listen on <port number> failed

If this error is encountered, there is an application currently using that port number. To solve:

Find the application using the port

1. Open terminal and run lsof -i:<port number>

The applications using that port number will appear on screen. Note the PID for that application.

Kill the process

1. In terminal, run kill <PID>

Re-launch the perforce server and it should now work as expected.

P4 Server: Warning: No entries made in db.topology for server address: <port number>

This warning doesn’t seem to impact server functionality.