Configure Perforce client

From Open Watcom

Revision as of 21:05, 13 September 2008; view current revision
←Older revision | Newer revision→
Jump to: navigation, search


Accessing Open Watcom Public Software Repository

 Note: the proper term is Perforce Depot, but we use the word 'repository' here to avoid confusing new users.

The Open Watcom Project uses the commercial Perforce version management software to maintain its source code repository. Perforce Software has graciously allowed Open Source software projects to be able to use a free server license for that source code.

Perforce access is currently only available to contributors. If you are interested in anonymous access to the latest source code, download the daily source snapshot.

Download a Perforce Client

In order to get Perforce up and running on your system, you will need to download the Perforce client program for your OS. Perforce Software provides clients for just about every OS freely on their web site at: All you need to do is download the appropriate 'p4' binary for your OS from their web site. You may also want to download or browse the documentation for p4, although it is quite simple to use from the command line and has extensive command line help.

In order to use Perforce you will need a TCP/IP connection to the internet, either via modem or direct connect. Accessing Perforce via modem is actually quite fast, and we have successfully done remote development over a 28K modem line from Australia!

Setting up your environment for access

Before you can read or write to the Open Watcom Perforce repository you will need to get an account on the Perforce server. Log onto the contributor's news group to request your account. This will also give you an opportunity to introduce yourself to the community and tell us a little about you plan to do.

Once you have downloaded the P4 binary and put it on your path, you want to set the following environment variables:

     P4PORT   =
     P4EDITOR = (path to your favorite console editor, such as Open Watcom's vi)

where you would replace YOURNAME_YOURMACHINE_YOUROS with a unique name (you can't use a client workspace that someone else is already using). For instance a valid client workspace name might be: JOEBLOGGS_DEVEL_LINUX

The client names the view that maintains the information about what files you have checked out on that system, and it must be unique for each user, and each machine. If you are doing development under multiple OS'es or multiple machines, you need a separate client view for each machine and each OS that will contain a copy of the source code from Perforce (hence the above naming convention for client workspaces).

Once you have the above variables set up, you can see if Perforce can access our server by typing the following:

     p4 info

You should see something similar to the following if it can connect successfully:

     User name: PeterC
     Client name: pchapin_WHIRLWIND_WinXP
     Client host: whirlwind
     Client root: c:\OW
     Current directory: c:\OW\bld
     Client address:
     Server address:
     Server root: /home/p4_public
     Server date: 2007/03/06 09:31:26 -0800 PST
     Server version: P4D/LINUX26X86/2006.1/106725 (2006/09/07)
     Server license: Open Watcom Project 100 users (expires 2008/01/09)

Setting up your client mapping

Once you are are able to connect, you need to set up your client mapping since by default it will be empty. The client space is what allows you to map in only the portions of the software repository that you care about, and where to put them on your local system. The client information is then stored remotely on our server so it knows what files you have on your system and where they live. In this respect Perforce behaves quite differently than CVS or Subversion so if you are used to those other systems, take careful note here!

To set up your client mapping, type:

     p4 client

This will bring you into your editor of choice. It will include comments at the top of the file about what the various parts of the file are used for. There are two parts that you need to modify; the 'root' definition and the 'view' definition. The 'root' is the root directory where all files get checked out onto your system, and this should be the root of the Open Watcom directory (ie: /home/pchapin/OW is where I put the Open Watcom source code on Unix systems, or c:\OW for DOS, Windows or OS/2 systems). For example:

     Root:     c:\OW

The 'options' defines what options are in effect for that client. The most important one you will want to change is the 'nocompress' option to 'compress'. By enabling compression, you will drastically reduce the time required for syncs over an internet connection!

The 'view' defines what parts of the perforce repository you want mapped to your local drive. The simplest mapping which will pull down all the files you would need (and the one you should probably use) would be:

     View:         //depot/openwatcom/... //YOURNAME_YOURMACHINE_YOUROS/...

where you would replace the 'YOURNAME_YOURMACHINE_YOUROS' above with the name of your client workspace. This line indicates that all files get mapped to the c:\OW directory and all subdirectories under this (like bld, docs etc). Now once you have the client view defined, exit your editor and it will send the changes to the perforce server.

Syncing up for the first time

To synchronize your client workspace with the head revision in the repository, simply issue the command

     p4 sync

The Open Watcom software repository contains a lot of code, and doing a full sync will pull down well in excess of 80 megabytes of files. This can take quite a bit of time on a slow link. Hence in order to save time for the initial sync, you can download and install all the files from the latest source achive of the software to your system, and then tell Perforce that you have all files at the time that archive was made. Then when you sync up you will only pull down all the files that have changed since the last official source archive release.

Note however that we now maintain two separate sets of source archives for download. The first set is the source files that correspond directly to actual released binaries, and the second set is the current development tree from the development branch in Perforce. If you wish to keep up to date with the release branch, download the release source code and flush your tree to the release label. If you wish to keep up to date with the development branch (the most common option), download the development source code and perform the flush with the development branch label. The labels in Perforce always match the source archive names, making it easy to determine which source archive you need to use with each label.

Also note that if you are developing on a Unix machine with Unix style line endings, download the tar.bz2 archives rather than the ZIP archives. The ZIP archives contains files in DOS/Windows style line endings, and you will need to use the correct version for your system or Perforce will get confused.

For example, to do the initial sync for the Open Watcom 1.2.1 development release, use the following commands:

     p4 flush -f @open_watcom_devel_1.2.1
     p4 sync

to tell Perforce that you have all the files at the label 'open_watcom_devel_1.2.1' (change open_watcom_devel_1.2.1 to the label appropriate for the source archive you have downloaded). The 'p4 sync' then grabs any changes that have occurred since the 'open_watcom_devel_1.2.1' label and ZIP files were built. Once you have sync'ed up the first time, you should only use 'p4 sync' to get the latest updates to all the files.

Using Perforce from the command line

Using Perforce is very easy, and you can get help from the command line with:

     p4 help 

The following is a quick overview of the most common Perforce commands:

     p4 sync     - Sync up with the latest sources
     p4 edit     - Open a file for editing
     p4 add      - Add a new file to the repository
     p4 delete   - Delete a file from the repository
     p4 resolve  - Resolve conflicts if two people edit the same file
     p4 revert   - Revert changes for a currently opened file
     p4 submit   - Submit all changes to the repository
     p4 opened   - List all files you currently have opened

The big difference between Perforce and other SCM systems like RCS is that Perforce is 'change' oriented. When you submit a change list, included in the list will be all of the files that you currently have opened (if you don't want a file in that change list, simply delete it from the change list in the editor and it won't be submitted but will remain in your list of open files are the submit). You must provide a description for the change, and then the entire set of files associated with the changes is submitted as a single change to the server, including file additions and deletions! Hence when you need to revert back to older versions of the code, you can do it via the revision number for a specific file, a change list number to go back to the state when a particular change was submitted, or a label which you defined earlier.

Do's and Don'ts of Perforce Usage

To make your own and everyone else's life easier, follow a simple set of basic rules:

  • Do set your editor to convert tabs to spaces and strip trailing blanks. Only files that require unusual formatting (eg. GNU makefiles) are exempt.
  • Don't submit files that didn't change. You can run p4 diff -sr | p4 -x - revert to revert files that are open but unchanged.
  • Do follow the source code style guidelines, or your code will be mercilessly edited.
  • Don't mix style changes with functional changes, for your own good. It's too difficult to find out what went wrong with a change that's 5% different in functionality and 95% different in style from earlier revision.
  • Do submit changes that are a logical unit and modify only one aspect of the code in each change. It's much better than mixing unrelated changes together in one change list.
  • Don't keep files open for too long (ie. more than several days).
  • Do be paranoid and make sure affected projects still build and work before submitting any change. People will get upset otherwise, and repeat offenders shall lose write access.
Personal tools