Next: Search::Dict | Previous: pumpkin | [Table of Contents] | [Index] |
repository - Using the Perl repository
This document describes what a Perl Porter needs to do to start using the Perl repository.
You'll need to get hold of the following software.
http://www.perforce.com/perforce/loadprog.html
You'll probably also want to look at: http://www.perforce.com/perforce/technical.html
where you can look at or download its documentation.
http://www.cs.hut.fi/ssh
which mentions ftp sites from
which it's available. You only need to build the client parts (ssh
and ssh-keygen should suffice).
If you already use ssh and want to use the same key pair for perl repository access then you can skip the rest of this section. Otherwise, generate an ssh key pair for use with the repository by typing the command ssh-keygen
After generating a key pair and testing it, ssh-keygen will ask you
to enter a filename in which to save the key. The default it offers
will be the file ~/.ssh/identity
which is suitable unless you
particularly want to keep separate ssh identities for some reason.
If so, you could save the perl repository private key in the file
~/.ssh/perl
, for example, but I will use the standard filename
in the remainder of the examples of this document.
After typing in the filename, it will prompt you to type in a passphrase. The private key will itself be encrypted so that it is usable only when that passphrase is typed. (When using ssh, you will be prompted when it requires a pass phrase to unlock a private key.) If you provide a blank passphrase then no passphrase will be needed to unlock the key and, as a consequence, anyone who gains access to the key file gains access to accounts protected with that key (barring additional configuration to restrict access by IP address).
When you have typed the passphrase in twice, ssh-keygen will confirm
where it has saved the private key (in the filename you gave and
with permissions set to be only readable by you), what your public
key is (don't worry: you don't need to memorise it) and where it
has saved the corresponding public key. The public key is saved in
a filename corresponding to your private key's filename but with
".pub" appended, usually ~/.ssh/identity.pub
. That public key
can be (but need not be) world readable. It is not used by your
own system at all.
Mail the contents of that public key file to the keeper of the perl repository (see the Contact Information entry elsewhere in this document below). When the key is added to the repository host's configuration file, you will be able to connect to it with ssh by using the corresponding private key file (after unlocking it with your chosen passphrase).
Connections to the repository are made by using ssh to provide a TCP "tunnel" rather than by using ssh to login to or invoke any ordinary commands on the repository. When you want to start a session using the repository, use the command ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
If you are not using the default filename of ~/.ssh/identity
to hold your perl repository private key then you'll need to add
the option -i filename to tell ssh where it is. Unless you chose
a blank passphrase for that private key, ssh will prompt you for the
passphrase to unlock that key. Then ssh will fork and put itself
in the background, returning you (silently) to your shell prompt.
The tunnel for repository access is now ready for use.
For the sake of completeness (and for the case where the chosen port of 1666 is already in use on your machine), I'll briefly describe what all those ssh arguments are for.
If port 1666 is already in use on your machine then you can choose any non-privileged port (a number between 1024 and 65535) which happens to be free on your machine. It's the first of the three colon separated values that you should change. Picking port 2345 would mean changing the option to -L 2345:127.0.0.1:1666. Whatever port number you choose should be used for the value of the P4PORT environment variable (q.v.).
You should normally get a prompt that asks for the passphrase for your RSA key when you connect with the ssh command shown above. If you see a prompt that looks like: perlrep@sickle.activestate.com's password:
Then you either don't have a ~/.ssh/identity file corresponding to your public key, or your ~/.ssh/identity file is not readable. Fix the problem and try again.
Remember to read the documentation for Perforce. You need to make sure that three environment variable are set correctly before using the p4 client with the perl repository.
Note that perforce only needs the client name so that it can find the directory under which your client files are stored. If you have multiple hosts sharing the same directory structure via NFS then only one client name is necessary.
The p4 clients
command lists all currently known clients.
The p4 users
command lists all currently known users.
Once these three environment variables are set, you can use the
perforce p4 client exactly as described in its documentation.
After setting these variables and connecting to the repository
for the first time, you should use the p4 user
and
p4 client
commands to tell perforce the details of your
new username and your new client workspace specifications.
When you have finished a session using the repository, you should kill off the ssh client process to break the tunnel. Since ssh forked itself into the background, you'll need to use something like ps with the appropriate options to find the ssh process and then kill it manually. The default signal of SIGTERM is fine.
Please read at least the introductory sections of the Perforce User Guide (and perhaps the Quick Start Guide as well) before reading this section.
Every repository user typically "owns" a "branch" of the mainline code in the repository. They hold the "pumpkin" for things in this area, and are usually the only user who will modify files there. This is not strictly enforced in order to allow the flexibility of other users stealing the pumpkin for short periods with the owner's permission.
Here is the current structure of the repository: /----+-----perl - Mainline development (bleadperl) +-----cfgperl - Configure Pumpkin's Perl +-----vmsperl - VMS Pumpkin's Perl +-----maint-5.004------perl - Maintainance branches +-----maint-5.005------perl +-----maint-5.6------perl
Perforce uses a branching model that simply tracks relationships between files. It does not care about directories at all, so any file can be a branch of any other file--the fully qualified depot path name (of the form //depot/foo/bar.c) uniquely determines a file for the purpose of establishing branching relationships. Since a branch usually involves hundreds of files, such relationships are typically specified en masse using a branch map (try `p4 help branch`). `p4 branches` lists the existing branches that have been set up. `p4 branch -o branchname` can be used to view the map for a particular branch, if you want to determine the ancestor for a particular set of files.
The mainline (aka "trunk") code in the Perl repository is under "//depot/perl/...". Most branches typically map its entire contents under a directory that goes by the same name as the branch name. Thus the contents of the cfgperl branch are to be found in //depot/cfgperl.
Run `p4 client` to specify how the repository contents should map to your local disk. Most users will typically have a client map that includes at least their entire branch and the contents of the mainline.
Run `p4 changes -l -m10` to check on the activity in the repository. //depot/perl/Porting/genlog is useful to get an annotated changelog that shows files and branches. You can use this listing to determine if there are any changes in the mainline that you need to merge into your own branch. A typical merging session looks like this: % cd ~/p4view/cfgperl % p4 integrate -b cfgperl # to bring parent changes into cfgperl % p4 resolve -a ./... # auto merge the changes % p4 resolve ./... # manual merge conflicting changes % p4 submit ./... # check in
If the owner of the mainline wants to bring the changes in cfgperl back into the mainline, they do: % p4 integrate -r -b cfgperl ...
Generating a patch for change#42 is done as follows: % p4 describe -du 42 | p4desc | p4d2p > change-42.patch
p4desc and p4d2p are to be found in //depot/perl/Porting/.
The mail alias <perl-repository-keepers@perl.org> can be used to reach all current users of the repository.
The repository keeper is currently Gurusamy Sarathy <gsar@activestate.com>.
Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997.
Gurusamy Sarathy, gsar@activestate.com, 8 May 1999.
Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000