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 foo
88 If you are not using the default filename of F<~/.ssh/identity>
89 to hold your perl repository private key then you'll need to add
90 the option B<-i filename> to tell ssh where it is. Unless you chose
91 a blank passphrase for that private key, ssh will prompt you for the
92 passphrase to unlock that key. Then ssh will fork and put itself
93 in the background, returning you (silently) to your shell prompt.
94 The tunnel for repository access is now ready for use.
96 For the sake of completeness (and for the case where the chosen
97 port of 1666 is already in use on your machine), I'll briefly
98 describe what all those ssh arguments are for.
104 Use a remote username of perlrep. (The account on the repository which
105 provides the end-point of the ssh tunnel is named "perlrep".)
109 Tells ssh to fork and remain running in the background. Since ssh
110 is only being used for its tunnelling capabilities, the command
111 that ssh runs never does any I/O and can sit silently in the
116 Tells ssh to be quiet. Without this option, ssh will output a
117 message each time you use a p4 command (since each p4 command
118 tunnels over the ssh connection to reach the repository).
122 Tells ssh not to bother to set up a tunnel for X11 connections.
123 The repository doesn't allow this anyway.
125 =item B<-L 1666:127.0.0.1:1666>
127 This is the important option. It tells ssh to listen out for
128 connections made to port 1666 on your local machine. When such
129 a connection is made, the ssh client tells the remote side
130 (the corresponding ssh daemon on the repository) to make a
131 connection to IP address 127.0.0.1, port 1666. Data flowing
132 along that connection is tunnelled over the ssh connection
133 (encrypted). The perforce daemon running on the repository
134 only accepts connections from localhost and that is exactly
135 where ssh-tunnelled connections appear to come from.
137 If port 1666 is already in use on your machine then you can
138 choose any non-privileged port (a number between 1024 and 65535)
139 which happens to be free on your machine. It's the first of the
140 three colon separated values that you should change. Picking
141 port 2345 would mean changing the option to
142 B<-L 2345:127.0.0.1:1666>. Whatever port number you choose should
143 be used for the value of the P4PORT environment variable (q.v.).
145 =item sickle.activestate.com
147 This is the canonical name of the host on which the perl repository
148 resides. Its IP address is 199.60.48.20.
152 This is a dummy place holder argument. Without an argument
153 here, ssh will try to perform an interactive login to the
154 repository which is not allowed. Ordinarily, this argument
155 is for the one-off command which is to be executed on the
156 remote host. However, the repository's ssh configuration
157 file uses the "command=" option to force a particular
158 command to run so the actual value of the argument is
159 ignored. The command that's actually run merely pauses and
160 waits for the ssh connection to drop, then exits.
166 You should normally get a prompt that asks for the passphrase
167 for your RSA key when you connect with the ssh command shown
168 above. If you see a prompt that looks like:
170 perlrep@sickle.activestate.com's password:
172 Then you either don't have a ~/.ssh/identity file corresponding
173 to your public key, or your ~/.ssh/identity file is not readable.
174 Fix the problem and try again.
176 =head1 Using the Perforce Client
178 Remember to read the documentation for Perforce. You need
179 to make sure that three environment variable are set
180 correctly before using the p4 client with the perl repository.
186 Set this to localhost:1666 (the port for your ssh client to listen on)
187 unless that port is already in use on your host. If it is, see
188 the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
192 The value of this is the name by which Perforce knows your
193 host's workspace. You need to pick a name (normally, your
194 Perforce username, a dash, and your hostname)
195 when you first start using the perl repository and then
198 Perforce keeps track of the files you have on your machine. It
199 does this through your client. When you first sync a version of a
200 file, the file comes from the server to your machine. If you sync
201 the same file again the server does nothing because it
202 knows you already have the file.
204 You should NOT use the same client on different machines. If you do
205 you probably won't get the files you expect, and may end up with
206 nasty corruption. Perforce allows you to have as many clients as
207 you want. For example, sally-home, sally-openbsd, sally-laptop.
209 Also, never change the client's root and view at the same time.
210 See C<http://www.perforce.com/perforce/doc.002/manuals/p4guide/04_details.html#1048341>
212 If you have multiple hosts sharing the same directory structure
213 via NFS then you may be able to get away with only one client name,
216 The C<p4 clients> command lists all currently known clients.
220 This is the username by which perforce knows you. Use your
221 username if you have a well known or obvious one or else pick
222 a new one which other perl5-porters will recognise. There is
223 a licence limit on the number of these usernames, so be sure not
224 to use more than one.
226 It is very important to set a password for your Perforce username,
227 or else anyone can impersonate you. Use the C<p4 passwd> command
228 to do this. Once a password is set for your account, you'll need
229 to tell Perforce what it is. You can do this by setting the
230 environment variable P4PASSWD, or you can use the C<-P> flag
231 with the C<p4> command.
233 There are a few techniques you can use to avoid having to either
234 set an environment variable or type the password on every command.
235 One is to create a shell alias, for example, in bash, add something like
236 alias p4='p4 -P secret'
237 to your F<.bash_profile> file. Another way is to create a small shell
241 And use this instead of running C<p4> directly.
243 With either of these, be sure the file containing your password
244 (the F<.bash_profile> or shell script file) is only readable by you.
246 The C<p4 users> command lists all currently known users.
250 Once these three environment variables are set, you can use the
251 perforce p4 client exactly as described in its documentation.
252 After setting these variables and connecting to the repository
253 for the first time, you should use the C<p4 user> and
254 C<p4 client> commands to tell perforce the details of your
255 new username and your new client workspace specifications.
257 =head1 Ending a Repository Session
259 When you have finished a session using the repository, you
260 should kill off the ssh client process to break the tunnel.
261 Since ssh forked itself into the background, you'll need to use
262 something like ps with the appropriate options to find the ssh
263 process and then kill it manually. The default signal of
266 =head1 Overview of the Repository
268 Please read at least the introductory sections of the Perforce
269 User Guide (and perhaps the Quick Start Guide as well) before
270 reading this section.
272 Every repository user typically "owns" a "branch" of the mainline
273 code in the repository. They hold the "pumpkin" for things in this
274 area, and are usually the only user who will modify files there.
275 This is not strictly enforced in order to allow the flexibility
276 of other users stealing the pumpkin for short periods with the
279 Here is the current structure of the repository:
281 /----+-----perl - Mainline development (bleadperl)
282 +-----perlio - PerlIO Pumpkin's Perl
283 +-----vmsperl - VMS Pumpkin's Perl
284 +-----maint-5.004------perl - Maintainance branches
285 +-----maint-5.005------perl
286 +-----maint-5.6------perl
287 +-----maint-5.6------pureperl
289 Perforce uses a branching model that simply tracks relationships
290 between files. It does not care about directories at all, so
291 any file can be a branch of any other file--the fully qualified
292 depot path name (of the form //depot/foo/bar.c) uniquely determines
293 a file for the purpose of establishing branching relationships.
294 Since a branch usually involves hundreds of files, such relationships
295 are typically specified en masse using a branch map (try `p4 help branch`).
296 `p4 branches` lists the existing branches that have been set up.
297 `p4 branch -o branchname` can be used to view the map for a particular
298 branch, if you want to determine the ancestor for a particular set of
301 The mainline (aka "trunk") code in the Perl repository is under
302 "//depot/perl/...". Most branches typically map its entire
303 contents under a directory that goes by the same name as the branch
304 name. Thus the contents of the perlio branch are to be found
307 Run `p4 client` to specify how the repository contents should map to
308 your local disk. Most users will typically have a client map that
309 includes at least their entire branch and the contents of the mainline.
311 Run `p4 changes -l -m10` to check on the activity in the repository.
312 //depot/perl/Porting/genlog is useful to get an annotated changelog
313 that shows files and branches. You can use this listing to determine
314 if there are any changes in the mainline that you need to merge into
315 your own branch. A typical merging session looks like this:
318 % p4 integrate -b perlio # to bring parent changes into perlio
319 % p4 resolve -am ./... # auto merge the changes
320 % p4 resolve ./... # manual merge conflicting changes
321 % p4 submit ./... # check in
323 If the owner of the mainline wants to bring the changes in perlio
324 back into the mainline, they do:
326 % p4 integrate -r -b perlio
329 Generating a patch for change#42 is done as follows:
331 % p4genpatch 42 > change-42.patch
333 F<p4genpatch> is to be found in //depot/perl/Porting/.
335 The usual routine to apply a patch is
337 % p4 edit file.c file.h
340 (any necessary, re-Configure, make regen_headers, make clean, etc, here)
344 (preferably make all test in several platforms and under several
345 different Configurations)
354 Other useful Perforce commands
356 % p4 describe -du 12345 # show change 12345
358 Note: the output of "p4 describe" is not in proper diff format, use
359 the F<Porting/p4genpatch> to get a diff-compatible format.
361 % p4 diff -se ./... # have I modified something but forgotten
362 # to "p4 edit", easy faux pas with autogenerated
363 # files like proto.h, or if one forgets to
364 # look carefully which files a patch modifies
365 % p4 sync file.h # if someone else has modified file.h
366 % p4 opened # which files are opened (p4 edit) by me
367 % p4 opened -a # which files are opened by anybody
368 % p4 diff -du file.c # what changes have I done
369 % p4 revert file.h # never mind my changes
370 % p4 sync -f argh.c # forcibly synchronize your file
371 # from the repository
372 % p4 diff -sr | p4 -x - revert
373 # throw away (opened but) unchanged files
374 # (in Perforce it's a little bit too easy
375 # to checkin unchanged files)
377 Integrate patch 12345 from the mainline to the maint-5.6 branch:
378 (you have to in the directory that has both the mainline and
379 the maint-5.6/perl as subdirectories)
381 % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/...
383 Integrate patches 12347-12350 from the perlio branch to the mainline:
385 % p4 integrate -d perlio/...@12347,12350 perl/...
387 =head1 Contact Information
389 The mail alias <perl-repository-keepers@perl.org> can be used to reach
390 all current users of the repository.
392 The repository keeper is currently Gurusamy Sarathy
393 <gsar@activestate.com>.
397 Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997.
399 Gurusamy Sarathy, gsar@activestate.com, 8 May 1999.
401 Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000.
403 More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
405 Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.