f13bef005ae92b64ba174ccbbadf8c76024ea5c0
[perl.git] / Porting / repository.pod
1 =head1 NAME
2
3 repository - Using the Perl repository
4
5 =head1 Synopsis
6
7 First, we assume here that you have already decided that you will
8 need B<write> access to the repository.  If all you need is B<read>
9 access, there are much better ways to access the most current state of
10 the perl repository, or explore individual files and patches therein.
11 See L<perlhack> for details.
12
13 This document describes what a Perl Porter needs to do to start using
14 the Perl repository.
15
16 =head1 Prerequisites
17
18 You'll need to get hold of the following software.
19
20 =over 4
21
22 =item Perforce
23
24 Download a perforce client from:
25
26    http://www.perforce.com/perforce/loadprog.html
27
28 You'll probably also want to look at:
29
30    http://www.perforce.com/perforce/technical.html
31
32 where you can look at or download its documentation.
33
34 =item ssh
35
36 If you don't already have access to an ssh client, then look at its
37 home site C<http://www.cs.hut.fi/ssh> which mentions ftp sites from
38 which it's available. You only need to build the client parts (ssh
39 and ssh-keygen should suffice).
40
41 If you're on Windows then you might like to obtain Cygwin from:
42
43     http://cygwin.com/
44
45 which contains an ssh client.  (MSYS also contains an ssh client
46 but it seems to time-out and disconnect from the server and doesn't
47 understand the ServerAliveInterval setting described later that can
48 be used to stop Cygwin's ssh client from doing this.)
49
50 Alternatively, the "plink" program, part of PuTTY:
51
52     http://www.chiark.greenend.org.uk/~sgtatham/putty/
53
54 should also work fine for Windows users.
55
56 =back
57
58 =head1 Creating an SSH Key Pair
59
60 If you already use ssh and want to use the same key pair for perl
61 repository access then you can skip the rest of this section.
62 Otherwise, generate an ssh key pair for use with the repository
63 by typing the command
64
65     ssh-keygen
66
67 After generating a key pair and testing it, ssh-keygen will ask you
68 to enter a filename in which to save the key. The default it offers
69 will be the file F<~/.ssh/identity> which is suitable unless you
70 particularly want to keep separate ssh identities for some reason.
71 If so, you could save the perl repository private key in the file
72 F<~/.ssh/perl>, for example, but I will use the standard filename
73 in the remainder of the examples of this document.  (Some ssh
74 implementations will default to creating a F<~/.ssh/id_rsa*>
75 ssh prototcol 2 RSA key pair instead - see below.  Use the -t rsa1
76 option if you really want a protocol 1 key pair.)
77
78 After typing in the filename, it will prompt you to type in a
79 passphrase. The private key will itself be encrypted so that it is
80 usable only when that passphrase is typed. (When using ssh, you will
81 be prompted when it requires a pass phrase to unlock a private key.)
82 If you provide a blank passphrase then no passphrase will be needed
83 to unlock the key and, as a consequence, anyone who gains access to
84 the key file gains access to accounts protected with that key
85 (barring additional configuration to restrict access by IP address).
86
87 When you have typed the passphrase in twice, ssh-keygen will confirm
88 where it has saved the private key (in the filename you gave and
89 with permissions set to be only readable by you), what your public
90 key is (don't worry: you don't need to memorise it) and where it
91 has saved the corresponding public key. The public key is saved in
92 a filename corresponding to your private key's filename but with
93 ".pub" appended, usually F<~/.ssh/identity.pub>. That public key
94 can be (but need not be) world readable. It is not used by your
95 own system at all.
96
97 Note that the above process creates a key pair for ssh protocol 1.
98 You can request ssh protocol 2 (RSA) instead if you prefer (if your
99 particular ssh client supports it), via the command
100
101     ssh-keygen -t rsa
102
103 This will create private/public identity files called F<~/.ssh/id_rsa>
104 and F<~/.ssh/id_rsa.pub> respectively.  Protocol 2 offers a higher
105 level of security than protocol 1.  This is not required for access to
106 the Perl repository -- ssh is used for authentication rather than
107 encryption (the Perl sources are open anyway) -- but either protocol
108 is supported by the server.
109
110 B<IMPORTANT NOTE FOR CYGWIN USERS:>  In order to make the private key
111 files only readable by you you must include the string "ntea" in the
112 "CYGWIN" environment variable in the shell used to run C<chmod(1)>,
113 and in the shell used to run the ssh client itself later.  If "CYGWIN"
114 doesn't contain "ntea" then it will appear to the ssh client that the
115 file permissions are not set correctly, in which case the files will be
116 ignored and you won't be able to connect.
117
118 =head1 Notifying the Repository Keeper
119
120 Mail the contents of that public key file to the keeper of the perl
121 repository (see L</Contact Information> below).
122 When the key is added to the repository host's configuration file,
123 you will be able to connect to it with ssh by using the corresponding
124 private key file (after unlocking it with your chosen passphrase).
125
126 There is no harm in creating both protocol 1 and protocol 2 keys and
127 mailing them both in.  That way you'll be able to connect using either
128 protocol, which may be useful if you later find yourself using a client
129 that only supports one or the other protocol.
130
131 =head1 Connecting to the Repository
132
133 Connections to the repository are made by using ssh to provide a
134 TCP "tunnel" rather than by using ssh to login to or invoke any
135 ordinary commands on the repository.
136
137 The ssh (secure shell) protocol runs over port number 22, so if you
138 have a firewall installed at the client end then you must ensure that
139 it is configured to allow you to make an outgoing connection to port 22
140 on sickle.activestate.com.
141
142 When you want to start a session using the repository, use the command:
143
144     ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
145
146 If you are not using the default filename of F<~/.ssh/identity> or
147 F<~/.ssh/id_rsa> to hold your perl repository private key then you'll
148 need to add the option B<-i filename> to tell ssh where it is. Unless
149 you chose a blank passphrase for that private key, ssh will prompt you
150 for the passphrase to unlock that key. Then ssh will fork and put itself
151 in the background, returning you (silently) to your shell prompt.
152
153 Note that the first time you connect you may see a message like
154 "The authenticity of host 'sickle.activestate.com' can't be established,"
155 and asking you if you want to continue.  Just answer yes and sickle's
156 details will be cached in a F<known_hosts> or F<known_hosts2> file.  You
157 will not see that message again unless you delete the cache file.
158
159 The tunnel for repository access is now ready for use.
160
161 For the sake of completeness (and for the case where the chosen
162 port of 1666 is already in use on your machine), I'll briefly
163 describe what all those ssh arguments are for.
164
165 =over 4
166
167 =item B<-l perlrep>
168
169 Use a remote username of perlrep. (The account on the repository which
170 provides the end-point of the ssh tunnel is named "perlrep".)
171
172 =item B<-f>
173
174 Tells ssh to fork and remain running in the background. Since ssh
175 is only being used for its tunnelling capabilities, the command
176 that ssh runs never does any I/O and can sit silently in the
177 background.
178
179 =item B<-q>
180
181 Tells ssh to be quiet. Without this option, ssh will output a
182 message each time you use a p4 command (since each p4 command
183 tunnels over the ssh connection to reach the repository).
184
185 =item B<-x>
186
187 Tells ssh not to bother to set up a tunnel for X11 connections.
188 The repository doesn't allow this anyway.
189
190 =item B<-L 1666:127.0.0.1:1666>
191
192 This is the important option. It tells ssh to listen out for
193 connections made to port 1666 on your local machine. When such
194 a connection is made, the ssh client tells the remote side
195 (the corresponding ssh daemon on the repository) to make a
196 connection to IP address 127.0.0.1, port 1666. Data flowing
197 along that connection is tunnelled over the ssh connection
198 (encrypted). The perforce daemon running on the repository
199 only accepts connections from localhost and that is exactly
200 where ssh-tunnelled connections appear to come from.
201
202 If port 1666 is already in use on your machine then you can
203 choose any non-privileged port (a number between 1024 and 65535)
204 which happens to be free on your machine. It's the first of the
205 three colon separated values that you should change. Picking
206 port 2345 would mean changing the option to
207 B<-L 2345:127.0.0.1:1666>. Whatever port number you choose should
208 be used for the value of the P4PORT environment variable (q.v.).
209
210 =item sickle.activestate.com
211
212 This is the canonical name of the host on which the perl repository
213 resides.
214
215 =item foo
216
217 This is a dummy place holder argument. Without an argument
218 here, ssh will try to perform an interactive login to the
219 repository which is not allowed. Ordinarily, this argument
220 is for the one-off command which is to be executed on the
221 remote host. However, the repository's ssh configuration
222 file uses the "command=" option to force a particular
223 command to run so the actual value of the argument is
224 ignored. The command that's actually run merely pauses and
225 waits for the ssh connection to drop, then exits.
226
227 =back
228
229 =head1 Problems
230
231 You should normally get a prompt that asks for the passphrase
232 for your RSA key when you connect with the ssh command shown
233 above.  If you see a prompt that looks like:
234
235     perlrep@sickle.activestate.com's password:
236
237 Then you either don't have a F<~/.ssh/identity> or F<~/.ssh/id_rsa>
238 file corresponding to your public key, or that file is not readable.
239 Fix the problem and try again.  Alternatively, some ssh implementations
240 will fail to verify your RSA key if the key if readable by others.
241 Just lower the permissions to make the key readable to yourself.
242
243 If you only had the public key file for one protocol installed at the
244 server end then make sure your client is using the corresponding
245 protocol.  An ssh client that supports protocol 2 will probably choose
246 that by default, which will fail if the server end only has your public
247 key file for protocol 1.  Some ssh clients have "-1" and "-2" arguments
248 to force which protocol to use.
249
250 The "-v" (verbose) flag can be useful for seeing what protocol your
251 client is actually trying to connect with, and for spotting any other
252 problems.  The flag can be specified multiple times to increase
253 verbosity.  Note that specifying the "-q" flag as well might override
254 your request for verbose output, so drop the "-q" flag when trying this.
255
256 If you're using the Cygwin ssh client on Windows then you will probably
257 find that the connection times out after a short period of inactivity.
258 You will have to keep re-entering your passphrase to reconnect, which
259 gets annoying after a while.  In order to prevent these time-outs from
260 happening place the following two lines in the file F<~/.ssh/config>:
261
262         Host sickle.activestate.com
263         ServerAliveInterval 120
264
265 This causes the ssh client to send a message to the server every 120
266 seconds to check that the server is still alive.  The client will not
267 disconnect unless "ServerAliveCountMax" many of these messages go
268 unanswered.  Run C<man ssh_config> for more details.  Note also that
269 this option applies to protocol version 2 only.
270
271 =head1 Using the Perforce Client
272
273 Remember to read the documentation for Perforce. You need
274 to make sure that three environment variable are set
275 correctly before using the p4 client with the perl repository.
276
277 =over 4
278
279 =item P4PORT
280
281 Set this to localhost:1666 (the port for your ssh client to listen on)
282 unless that port is already in use on your host. If it is, see
283 the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
284
285 =item P4CLIENT
286
287 The value of this is the name by which Perforce knows your
288 host's workspace. You need to pick a name (normally, your
289 Perforce username, a dash, and your host's short name)
290 when you first start using the perl repository and then
291 stick with it.
292
293 Perforce keeps track of the files you have on your machine.  It
294 does this through your client. When you first sync a version of a
295 file, the file comes from the server to your machine.  If you sync
296 the same file again the server does nothing because it
297 knows you already have the file.
298
299 You should NOT use the same client on different machines.  If you do
300 you probably won't get the files you expect, and may end up with
301 nasty corruption.  Perforce allows you to have as many clients as
302 you want. For example, sally-home, sally-openbsd, sally-laptop.
303
304 Also, never change the client's root and view at the same time.
305 See C<http://www.perforce.com/perforce/doc.002/manuals/p4guide/04_details.html#1048341>
306
307 If you have multiple hosts sharing the same directory structure
308 via NFS then you may be able to get away with only one client name,
309 but be careful.
310
311 The C<p4 clients> command lists all currently known clients.
312
313 =item P4USER
314
315 This is the username by which perforce knows you. Use your
316 username if you have a well known or obvious one or else pick
317 a new one which other perl5-porters will recognise. There is
318 a licence limit on the number of these usernames, so be sure not
319 to use more than one.
320
321 It is very important to set a password for your Perforce username,
322 or else anyone can impersonate you.  Use the C<p4 passwd> command
323 to do this.  Once a password is set for your account, you'll need
324 to tell Perforce what it is. You can do this by setting the
325 environment variable P4PASSWD, or you can use the C<-P> flag
326 with the C<p4> command.
327
328 There are a few techniques you can use to avoid having to either
329 set an environment variable or type the password on every command.
330 One is to create a shell alias, for example, in bash, add something like
331     alias p4='p4 -P secret'
332 to your F<.bash_profile> file.  Another way is to create a small shell
333 script, for example
334     #!/bin/bash
335     p4 -P secret $@
336 And use this instead of running C<p4> directly.
337
338 With either of these, be sure the file containing your password
339 (the F<.bash_profile> or shell script file) is only readable by you.
340
341 The C<p4 users> command lists all currently known users.
342
343 =back
344
345 Note that on Windows P4PORT and P4USER are requested when installing
346 Perforce.  They are stored in the registry, so they do not need to be
347 set in the environment.
348
349 Once these three environment variables are set, you can use the
350 perforce p4 client exactly as described in its documentation.
351
352 After setting these variables and connecting to the repository
353 for the first time, you should use the C<p4 user> command to
354 set a valid email address for yourself.  Messages to the commit list
355 are sent (faked) from whatever email address you set here.
356
357 Also use the C<p4 client> command to specify your workspace
358 specifications for each individual client from which you will interact
359 with the repository.  The P4CLIENT environment variable, of course,
360 needs to be set to one of these client workspace names.
361
362 =head1 Ending a Repository Session
363
364 When you have finished a session using the repository, you
365 should kill off the ssh client process to break the tunnel.
366 Since ssh forked itself into the background, you'll need to use
367 something like ps with the appropriate options to find the ssh
368 process and then kill it manually. The default signal of
369 SIGTERM is fine.
370
371 =head1 Overview of the Repository
372
373 Please read at least the introductory sections of the Perforce
374 User Guide (and perhaps the Quick Start Guide as well) before
375 reading this section.
376
377 Every repository user typically "owns" a "branch" of the mainline
378 code in the repository.  They hold the "pumpkin" for things in this
379 area, and are usually the only user who will modify files there.
380 This is not strictly enforced in order to allow the flexibility
381 of other users stealing the pumpkin for short periods with the
382 owner's permission.
383
384 Here is (part of) the current structure of the repository:
385
386     /----+-----perl                  - Mainline development (bleadperl)
387          +-----perlio                - PerlIO Pumpkin's Perl
388          +-----vmsperl               - VMS Pumpkin's Perl
389          +-----maint-5.004------perl - Maintenance branches
390          +-----maint-5.005------perl
391          +-----maint-5.6--------perl
392          +-----maint-5.8--------perl
393          +-----pureperl---------pureperl
394
395 Perforce uses a branching model that simply tracks relationships
396 between files.  It does not care about directories at all, so
397 any file can be a branch of any other file--the fully qualified
398 depot path name (of the form //depot/foo/bar.c) uniquely determines
399 a file for the purpose of establishing branching relationships.
400 Since a branch usually involves hundreds of files, such relationships
401 are typically specified en masse using a branch map (try `p4 help branch`).
402 `p4 branches` lists the existing branches that have been set up.
403 `p4 branch -o branchname` can be used to view the map for a particular
404 branch, if you want to determine the ancestor for a particular set of
405 files.
406
407 The mainline (aka "trunk") code in the Perl repository is under
408 "//depot/perl/...".  Most branches typically map its entire
409 contents under a directory that goes by the same name as the branch
410 name.  Thus the contents of the perlio branch are to be found
411 in //depot/perlio.
412
413 Run `p4 client` to specify how the repository contents should map to
414 your local disk.  Most users will typically have a client map that
415 includes at least their entire branch and the contents of the mainline.
416
417 Run `p4 changes -l -m10` to check on the activity in the repository.
418 //depot/perl/Porting/genlog is useful to get an annotated changelog
419 that shows files and branches.  You can use this listing to determine
420 if there are any changes in the mainline that you need to merge into
421 your own branch.  A typical merging session looks like this:
422
423     % cd ~/p4view/perlio
424     % p4 integrate -b perlio     # to bring parent changes into perlio
425     % p4 resolve -am ./...        # auto merge the changes
426     % p4 resolve ./...           # manual merge conflicting changes
427     % p4 submit ./...            # check in
428
429 If the owner of the mainline wants to bring the changes in perlio
430 back into the mainline, they do:
431
432     % p4 integrate -r -b perlio
433     ...
434
435 Generating a patch for change#42 is done as follows:
436
437     % p4genpatch 42 > change-42.patch
438
439 F<p4genpatch> is to be found in //depot/perl/Porting/.
440
441 The usual routine to apply a patch is
442
443     % p4 edit file.c file.h
444     % patch < patch.txt
445
446 (any necessary, re-Configure, make regen_headers, make clean, etc, here)
447
448     % make all test
449
450 (preferably make all test in several platforms and under several
451 different Configurations)
452
453     % while unhappy
454     do
455       $EDITOR
456       make all test
457     done
458     % p4 submit
459
460 Other useful Perforce commands
461
462     % p4 describe -du 12345 # show change 12345
463
464 Note: the output of "p4 describe" is not in proper diff format, use
465 the F<Porting/p4genpatch> to get a diff-compatible format.
466 (Note that it may be easier to get one already prepared: grep
467 L<perlhack> for APC, and append eg "/diffs/12345.gz" to one of the
468 URLs to get a usable patch.)
469
470     % p4 diff -se ./...     # have I modified something but forgotten
471                             # to "p4 edit", easy faux pas with autogenerated
472                             # files like proto.h, or if one forgets to
473                             # look carefully which files a patch modifies
474     % p4 sync file.h        # if someone else has modified file.h
475     % p4 opened             # which files are opened (p4 edit) by me
476     % p4 opened -a          # which files are opened by anybody
477     % p4 diff -du file.c    # what changes have I done
478     % p4 revert file.h      # never mind my changes
479     % p4 sync -f argh.c     # forcibly synchronize your file
480                             # from the repository
481     % p4 diff -sr | p4 -x - revert
482                             # throw away (opened but) unchanged files
483                             # (in Perforce it's a little bit too easy
484                             # to checkin unchanged files)
485
486 Integrate patch 12345 from the mainline to the maint-5.6 branch:
487 (you have to in the directory that has both the mainline and
488 the maint-5.6/perl as subdirectories)
489
490     % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/...
491
492 Integrate patches 12347-12350 from the perlio branch to the mainline:
493
494     % p4 integrate -d perlio/...@12347,12350 perl/...
495
496 =head1 Contact Information
497
498 The mail alias E<lt>perl-repository-keepers@perl.orgE<gt> can be used to reach
499 all current users of the repository.
500
501 The repository keeper is currently Kevin J. Woolley
502 E<lt>kevinw@ActiveState.comE<gt>. 
503
504 =head1 AUTHORS
505
506 Malcolm Beattie, E<lt>mbeattie@sable.ox.ac.ukE<gt>, 24 June 1997.
507
508 Gurusamy Sarathy, E<lt>gsar@activestate.comE<gt>, 8 May 1999.
509
510 Slightly updated by Simon Cozens, E<lt>simon@brecon.co.ukE<gt>, 3 July 2000.
511
512 More updates by Jarkko Hietaniemi, E<lt>jhi@iki.fiE<gt>, 28 June 2001.
513
514 Perforce clarifications by Randall Gellens, E<lt>rcg@users.sourceforge.netE<gt>, 12 July 2001.
515
516 Windows-related updates by Steve Hay E<lt>shay@cpan.orgE<gt>, 23 July 2004
517 and 08 Aug 2005.
518
519 =cut