3 repository - Using the Perl repository
5 This document describes what a Perl Porter needs to do
6 to start using the Perl repository.
10 You'll need to get hold of the following software.
16 Download a perforce client from:
18 http://www.perforce.com/perforce/loadprog.html
20 You'll probably also want to look at:
22 http://www.perforce.com/perforce/technical.html
24 where you can look at or download its documentation.
28 If you don't already have access to an ssh client, then look at its
29 home site C<http://www.cs.hut.fi/ssh> which mentions ftp sites from
30 which it's available. You only need to build the client parts (ssh
31 and ssh-keygen should suffice).
35 =head1 Creating an SSH Key Pair
37 If you already use ssh and want to use the same key pair for perl
38 repository access then you can skip the rest of this section.
39 Otherwise, generate an ssh key pair for use with the repository
44 After generating a key pair and testing it, ssh-keygen will ask you
45 to enter a filename in which to save the key. The default it offers
46 will be the file F<~/.ssh/identity> which is suitable unless you
47 particularly want to keep separate ssh identities for some reason.
48 If so, you could save the perl repository private key in the file
49 F<~/.ssh/perl>, for example, but I will use the standard filename
50 in the remainder of the examples of this document.
52 After typing in the filename, it will prompt you to type in a
53 passphrase. The private key will itself be encrypted so that it is
54 usable only when that passphrase is typed. (When using ssh, you will
55 be prompted when it requires a pass phrase to unlock a private key.)
56 If you provide a blank passphrase then no passphrase will be needed
57 to unlock the key and, as a consequence, anyone who gains access to
58 the key file gains access to accounts protected with that key
59 (barring additional configuration to restrict access by IP address).
61 When you have typed the passphrase in twice, ssh-keygen will confirm
62 where it has saved the private key (in the filename you gave and
63 with permissions set to be only readable by you), what your public
64 key is (don't worry: you don't need to memorise it) and where it
65 has saved the corresponding public key. The public key is saved in
66 a filename corresponding to your private key's filename but with
67 ".pub" appended, usually F<~/.ssh/identity.pub>. That public key
68 can be (but need not be) world readable. It is not used by your
71 =head1 Notifying the Repository Keeper
73 Mail the contents of that public key file to the keeper of the perl
74 repository (see L</Contact Information> below).
75 When the key is added to the repository host's configuration file,
76 you will be able to connect to it with ssh by using the corresponding
77 private key file (after unlocking it with your chosen passphrase).
79 =head1 Connecting to the Repository
81 Connections to the repository are made by using ssh to provide a
82 TCP "tunnel" rather than by using ssh to login to or invoke any
83 ordinary commands on the repository. When you want to start a
84 session using the repository, use the command
86 ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com
89 If you are not using the default filename of F<~/.ssh/identity>
90 to hold your perl repository private key then you'll need to add
91 the option B<-i filename> to tell ssh where it is. Unless you chose
92 a blank passphrase for that private key, ssh will prompt you for the
93 passphrase to unlock that key. Then ssh will fork and put itself
94 in the background, returning you (silently) to your shell prompt.
95 The tunnel for repository access is now ready for use.
97 For the sake of completeness (and for the case where the chosen
98 port of 1666 is already in use on your machine), I'll briefly
99 describe what all those ssh arguments are for.
105 Use a remote username of perl. The account on the repository which
106 provides the end-point of the ssh tunnel is named "perl".
110 Tells ssh to fork and remain running in the background. Since ssh
111 is only being used for its tunnelling capabilities, the command
112 that ssh runs never does any I/O and can sit silently in the
117 Tells ssh to be quiet. Without this option, ssh will output a
118 message each time you use a p4 command (since each p4 command
119 tunnels over the ssh connection to reach the repository).
123 Tells ssh not to bother to set up a tunnel for X11 connections.
124 The repository doesn't allow this anyway.
126 =item B<-L 1666:127.0.0.1:1666>
128 This is the important option. It tells ssh to listen out for
129 connections made to port 1666 on your local machine. When such
130 a connection is made, the ssh client tells the remote side
131 (the corresponding ssh daemon on the repository) to make a
132 connection to IP address 127.0.0.1, port 1666. Data flowing
133 along that connection is tunnelled over the ssh connection
134 (encrypted). The perforce daemon running on the repository
135 only accepts connections from localhost and that is exactly
136 where ssh-tunnelled connections appear to come from.
138 If port 1666 is already in use on your machine then you can
139 choose any non-privileged port (a number between 1024 and 65535)
140 which happens to be free on your machine. It's the first of the
141 three colon separated values that you should change. Picking
142 port 2345 would mean changing the option to
143 B<-L 2345:127.0.0.1:1666>. Whatever port number you choose should
144 be used for the value of the P4PORT environment variable (q.v.).
146 =item sickle.activestate.com
148 This is the canonical IP name of the host on which the perl
149 repository runs. Its IP number is 199.60.48.20.
153 This is a dummy place holder argument. Without an argument
154 here, ssh will try to perform an interactive login to the
155 repository which is not allowed. Ordinarily, this argument
156 is for the one-off command which is to be executed on the
157 remote host. However, the repository's ssh configuration
158 file uses the "command=" option to force a particular
159 command to run so the actual value of the argument is
160 ignored. The command that's actually run merely pauses and
161 waits for the ssh connection to drop, then exits.
167 You should normally get a prompt that asks for the passphrase
168 for your RSA key when you connect with the ssh command shown
169 above. If you see a prompt that looks like:
171 perlrep@sickle.activestate.com's password:
173 Then you either don't have a ~/.ssh/identity file corresponding
174 to your public key, or your ~/.ssh/identity file is not readable.
175 Fix the problem and try again.
177 =head1 Using the Perforce Client
179 Remember to read the documentation for Perforce. You need
180 to make sure that three environment variable are set
181 correctly before using the p4 client with the perl repository.
187 Set this to localhost:1666 (the port for your ssh client to listen on)
188 unless that port is already in use on your host. If it is, see
189 the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
193 The value of this is the name by which Perforce knows your
194 host's workspace. You need to pick a name (normally, your
195 Perforce username, a dash, and your hostname)
196 when you first start using the perl repository and then
199 Perforce keeps track of the files you have on your machine. It
200 does this through your client. When you first sync a version of a
201 file, the file comes from the server to your machine. If you sync
202 the same file again the server does nothing because it
203 knows you already have the file.
205 You should NOT use the same client on different machines. If you do
206 you probably won't get the files you expect, and may end up with
207 nasty corruption. Perforce allows you to have as many clients as
208 you want. For example, sally-home, sally-openbsd, sally-laptop.
210 Also, never change the client's root and view at the same time.
211 See C<http://www.perforce.com/perforce/doc.002/manuals/p4guide/04_details.html#1048341>
213 If you have multiple hosts sharing the same directory structure
214 via NFS then you may be able to get away with only one client name,
217 The C<p4 clients> command lists all currently known clients.
221 This is the username by which perforce knows you. Use your
222 username if you have a well known or obvious one or else pick
223 a new one which other perl5-porters will recognise. There is
224 a licence limit on the number of these usernames, so be sure not
225 to use more than one.
227 It is very important to set a password for your Perforce username,
228 or else anyone can impersonate you. Use the C<p4 passwd> command
229 to do this. Once a password is set for your account, you'll need
230 to tell Perforce what it is. You can do this by setting the
231 environment variable P4PASSWD, or you can use the C<-P> flag
232 with the C<p4> command.
234 There are a few techniques you can use to avoid having to either
235 set an environment variable or type the password on every command.
236 One is to create a shell alias, for example, in bash, add something like
237 alias p4='p4 -P secret'
238 to your F<.bash_profile> file. Another way is to create a small shell
242 And use this instead of running C<p4> directly.
244 With either of these, be sure the file containing your password
245 (the F<.bash_profile> or shell script file) is only readable by you.
247 The C<p4 users> command lists all currently known users.
251 Once these three environment variables are set, you can use the
252 perforce p4 client exactly as described in its documentation.
253 After setting these variables and connecting to the repository
254 for the first time, you should use the C<p4 user> and
255 C<p4 client> commands to tell perforce the details of your
256 new username and your new client workspace specifications.
258 =head1 Ending a Repository Session
260 When you have finished a session using the repository, you
261 should kill off the ssh client process to break the tunnel.
262 Since ssh forked itself into the background, you'll need to use
263 something like ps with the appropriate options to find the ssh
264 process and then kill it manually. The default signal of
267 =head1 Overview of the Repository
269 Please read at least the introductory sections of the Perforce
270 User Guide (and perhaps the Quick Start Guide as well) before
271 reading this section.
273 Every repository user typically "owns" a "branch" of the mainline
274 code in the repository. They hold the "pumpkin" for things in this
275 area, and are usually the only user who will modify files there.
276 This is not strictly enforced in order to allow the flexibility
277 of other users stealing the pumpkin for short periods with the
280 Here is the current structure of the repository:
282 /----+-----perl - Mainline development (bleadperl)
283 +-----perlio - PerlIO Pumpkin's Perl
284 +-----vmsperl - VMS Pumpkin's Perl
285 +-----maint-5.004------perl - Maintainance branches
286 +-----maint-5.005------perl
287 +-----maint-5.6------perl
288 +-----maint-5.6------pureperl
290 Perforce uses a branching model that simply tracks relationships
291 between files. It does not care about directories at all, so
292 any file can be a branch of any other file--the fully qualified
293 depot path name (of the form //depot/foo/bar.c) uniquely determines
294 a file for the purpose of establishing branching relationships.
295 Since a branch usually involves hundreds of files, such relationships
296 are typically specified en masse using a branch map (try `p4 help branch`).
297 `p4 branches` lists the existing branches that have been set up.
298 `p4 branch -o branchname` can be used to view the map for a particular
299 branch, if you want to determine the ancestor for a particular set of
302 The mainline (aka "trunk") code in the Perl repository is under
303 "//depot/perl/...". Most branches typically map its entire
304 contents under a directory that goes by the same name as the branch
305 name. Thus the contents of the perlio branch are to be found
308 Run `p4 client` to specify how the repository contents should map to
309 your local disk. Most users will typically have a client map that
310 includes at least their entire branch and the contents of the mainline.
312 Run `p4 changes -l -m10` to check on the activity in the repository.
313 //depot/perl/Porting/genlog is useful to get an annotated changelog
314 that shows files and branches. You can use this listing to determine
315 if there are any changes in the mainline that you need to merge into
316 your own branch. A typical merging session looks like this:
319 % p4 integrate -b perlio # to bring parent changes into perlio
320 % p4 resolve -am ./... # auto merge the changes
321 % p4 resolve ./... # manual merge conflicting changes
322 % p4 submit ./... # check in
324 If the owner of the mainline wants to bring the changes in perlio
325 back into the mainline, they do:
327 % p4 integrate -r -b perlio
330 Generating a patch for change#42 is done as follows:
332 % p4 describe -du 42 | p4desc | p4d2p > change-42.patch
334 F<p4desc> and F<>p4d2p> are to be found in //depot/perl/Porting/.
336 The usual routine to apply a patch is
338 % p4 edit file.c file.h
341 (any necessary, re-Configure, make regen_headers, make clean, etc, here)
345 (preferably make all test in several platforms and under several
346 different Configurations)
355 Other useful Perforce commands
357 % p4 describe -du 12345 # show change 12345
359 Note: the output of "p4 describe" is not in proper diff format, use
360 the F<Porting/p4d2p> to convert.
362 % p4 diff -se ./... # have I modified something but forgotten
363 # to "p4 edit", easy faux pas with autogenerated
364 # files like proto.h, or if one forgets to
365 # look carefully which files a patch modifies
366 % p4 sync file.h # if someone else has modified file.h
367 % p4 opened # which files are opened (p4 edit) by me
368 % p4 opened -a # which files are opened by anybody
369 % p4 diff -du file.c # what changes have I done
370 % p4 revert file.h # never mind my changes
371 % p4 sync -f argh.c # forcibly synchronize your file
372 # from the repository
373 % p4 diff -sr | p4 -x - revert
374 # throw away (opened but) unchanged files
375 # (in Perforce it's a little bit too easy
376 # to checkin unchanged files)
378 Integrate patch 12345 from the mainline to the maint-5.6 branch:
379 (you have to in the directory that has both the mainline and
380 the maint-5.6/perl as subdirectories)
382 % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/...
384 Integrate patches 12347-12350 from the perlio branch to the mainline:
386 % p4 integrate -d perlio/...@12347,12350 perl/...
388 =head1 Contact Information
390 The mail alias <perl-repository-keepers@perl.org> can be used to reach
391 all current users of the repository.
393 The repository keeper is currently Gurusamy Sarathy
394 <gsar@activestate.com>.
398 Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997.
400 Gurusamy Sarathy, gsar@activestate.com, 8 May 1999.
402 Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000.
404 More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
406 Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.