Shift-Right uses the commercial Perforce version management software to maintain its open source projects. Perforce has provided Shift-Right a free server license to be used with our open source software. Perforce has a very good tutorial on accessing their public Perforce server. Using Shift-Right’s public Perforce server is very similar. If you are unfamiliar with Perforce, it is highly recommending reviewing the tutorial before proceeding.
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: http://www.perforce.com/perforce/loadprog.html. 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.
Once you have downloaded the p4 binary and put it on your command path, you want to set the following environment variables:
|
P4PORT |
= |
65.168.17.220:2666 |
|
P4USER |
= |
anonymous |
|
P4PASSWD |
= |
anonymous |
|
P4CLIENT |
= |
PROJECT_YOURNAME_WORKSPACENAME |
|
|
|
|
where you would replace PROJECT_YOURNAME_WORKSPACENAME with a unique name (you can't use a client that someone else is already using). For instance a valid client name might be: openrepo_johndoe_viper.
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 the repository. Once you have the above variables set up, you can verify your access to the Perforce server by typing the following:
p4 info
You should see something similar to the following if it can connect successfully:
User name: anonymous
Client name: openrepo_johndoe_viper
Client host: madmax
Client unknown.
Current directory: c:\oss-views
Client address: 192.168.1.108:2072
Server address: 208.147.135.177:2666
Server root: /var/lib/perforce/oss
Server date: 2003/03/15 13:58:33 -0500 EST
Server version: P4D/LINUX24X86/2002.2/41936 (2003/02/26)
Server license: Shift-Right Technologies, LLC 6 users (expires 2004/03/07)
You can also access Shift-Right’s public Perforce repository via a web browser. (the web interface is restricted to read-only access). Simply point your web browser to the following URL:
The repository is organized into the following depots:
|
//openrepo/… |
Contains the source code and third-party software for the Shift-Right Open Repository. |
|
//xmk/… |
Contains the source code for the eXtreme Minimal Kernel (XMK) open source project. |
|
//benv/… |
Contains the makefiles, scripts, source, etc. for the BENV build environment. Note: The contents of this depot are required to build projects contained in the other depots. |
Once you are able to connect to the Perforce server, you need to set up a client specification. The client specification is what allows you to map in only the portions of the 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.
Setting up the “right” client specification is important since the client specifications determines what, how many, and where files are stored on your local machine. Unfortunately, the default client specification will not only include all the repository files (i.e. a long time to sync/download the files) but it will put the files in the “wrong” directories on your client machine. To get you stared there are template/example clients specifications that you can use as a starting point for defining your own client specifications. All example clients start with template_xxxx. To get a list of existing clients, type:
|
p4 clients |
(All clients) |
|
or p4 clients | grep template_ |
(Example clients only) |
You can view any client specification by typing:
p4 client –o <client_name>
Example: p4 client –o template_latest_openrepo_core
To create a new client specification from using an existing client specification, type:
p4 client –t <existing_client> <new_client>
Example: p4 client –t template_latest_openrepo_core openrepo_joedoe_viper
The p4 client command will bring you into a form editor. It will include comments at the top about what the sections of the form are used for. There are two sections 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. For example:
Root: c:\views\openrepo
The view defines what parts of the perforce repository you want mapped to your local machine. This is where you tell the Perforce server what files you what and where to store them on your local drive. If you need more, or less files than what the example client specifications provide, you will need to add, delete, or modify the file mappings. More information about client specifications and file mappings can be found here.
Once you have created a client specification and set the P4CLIENT environment variable to name of the client specification, simple type the following to update your local machine:
p4 sync
The first time you run the p4 sync command all of the files defined by your client specification will be downloaded to your local machine. Subsequent calls to p4 sync will only download files that have changes since you last did a p4 sync command.
Anonymous access to the repository is read-only in that you can not check files back into the repository. If you want to contribute to the repository please contact Shift-Right’s Open Source Supervisor and you will be provided with a user account (and password) that has limited write permissions to the repository. Each contributing developer is granted write access to their own “branch” in the repository. As a contributor, you may only submit changes to your own branch in the repository. To have your changes "published", your changes must be approved by Shift-Right’s Open Source Supervisor. Once approved, the supervisor will integrate your changes into the main development line of the repository.
To access the repository as a contributing developer simple follow the steps for anonymous access, but set the P4USER and P4PASSWD environment variables to your user account.
The process in the same for creating a client specification is the same as with anonymous access. The only difference is in the definitions of the file mappings under the view section. Example client specifications for development have been provided. Type the following to get a list of development specific example clients:
p4 clients | grep template_develop
Listed below are brief instructions for working with a development branch. It is strongly recommended that you review the Perforce tutorial.
p4 integ –v //openrepo/main/… //openrepo/devel/<user>/…
p4 integ –v //benv/main/… //benv/devel/<user>/…
p4 integ –v //xmk/main/… //xmk/devel/<user>/…
p4 submit
p4 sync
p4 integ –n//openrepo/main/… //openrepo/devel/<user>/…
p4 integ –n//benv/main/… //benv/devel/<user>/…
p4 integ –n//xmk/main/… //xmk/devel/<user>/…
p4 integ //openrepo/main/… //openrepo/devel/<user>/…
p4 integ //benv/main/… //benv/devel/<user>/…
p4 integ //xmk/main/… //xmk/devel/<user>/…
p4 resolve
p4 submit