Win32 pacifying from mjd.
[perl.git] / Porting / repository.pod
1 =head1 NAME
2
3 repository - Using the Perl repository
4
5 This document describes what a Perl Porter needs to do
6 to start using the Perl repository.
7
8 =head1 Prerequisites
9
10 You'll need to get hold of the following software.
11
12 =over 4
13
14 =item Perforce
15
16 Download a perforce client from:
17
18    http://www.perforce.com/perforce/loadprog.html
19
20 You'll probably also want to look at:
21
22    http://www.perforce.com/perforce/technical.html
23
24 where you can look at or download its documentation.
25
26 =item ssh
27
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).
32
33 =back
34
35 =head1 Creating an SSH Key Pair
36
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
40 by typing the command
41
42     ssh-keygen
43
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.
51
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).
60
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
69 own system at all.
70
71 =head1 Notifying the Repository Keeper
72
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).
78
79 =head1 Connecting to the Repository
80
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
85
86     ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
87
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.
95
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.
99
100 =over 4
101
102 =item B<-l perlrep>
103
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".)
106
107 =item B<-f>
108
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
112 background.
113
114 =item B<-q>
115
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).
119
120 =item B<-x>
121
122 Tells ssh not to bother to set up a tunnel for X11 connections.
123 The repository doesn't allow this anyway.
124
125 =item B<-L 1666:127.0.0.1:1666>
126
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.
136
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.).
144
145 =item sickle.activestate.com
146
147 This is the canonical name of the host on which the perl repository
148 resides. Its IP address is 199.60.48.20.
149
150 =item foo
151
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.
161
162 =back
163
164 =head1 Problems
165
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:
169
170     perlrep@sickle.activestate.com's password:
171
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.
175
176 =head1 Using the Perforce Client
177
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.
181
182 =over 4
183
184 =item P4PORT
185
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.
189
190 =item P4CLIENT
191
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
196 stick with it.
197
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.
203
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.
208
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>
211
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,
214 but be careful.
215
216 The C<p4 clients> command lists all currently known clients.
217
218 =item P4USER
219
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.
225
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.
232
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
238 script, for example
239     #!/bin/bash
240     p4 -P secret $@
241 And use this instead of running C<p4> directly.
242
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.
245
246 The C<p4 users> command lists all currently known users.
247
248 =back
249
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.
256
257 =head1 Ending a Repository Session
258
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
264 SIGTERM is fine.
265
266 =head1 Overview of the Repository
267
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.
271
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
277 owner's permission.
278
279 Here is the current structure of the repository:
280
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
288
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
299 files.
300
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
305 in //depot/perlio.
306
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.
310
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:
316
317     % cd ~/p4view/perlio
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
322
323 If the owner of the mainline wants to bring the changes in perlio
324 back into the mainline, they do:
325
326     % p4 integrate -r -b perlio
327     ...
328
329 Generating a patch for change#42 is done as follows:
330
331     % p4 describe -du 42 | p4desc | p4d2p > change-42.patch
332
333 F<p4desc> and F<>p4d2p> are to be found in //depot/perl/Porting/.
334
335 The usual routine to apply a patch is
336
337     % p4 edit file.c file.h
338     % patch < patch.txt
339
340 (any necessary, re-Configure, make regen_headers, make clean, etc, here)
341
342     % make all test
343
344 (preferably make all test in several platforms and under several
345 different Configurations)
346
347     % while unhappy
348     do
349       $EDITOR
350       make all test
351     done
352     % p4 submit
353
354 Other useful Perforce commands
355
356     % p4 describe -du 12345 # show change 12345
357
358 Note: the output of "p4 describe" is not in proper diff format, use
359 the F<Porting/p4d2p> to convert.
360
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)
376
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)
380
381     % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/...
382
383 Integrate patches 12347-12350 from the perlio branch to the mainline:
384
385     % p4 integrate -d perlio/...@12347,12350 perl/...
386
387 =head1 Contact Information
388
389 The mail alias <perl-repository-keepers@perl.org> can be used to reach
390 all current users of the repository.
391
392 The repository keeper is currently Gurusamy Sarathy
393 <gsar@activestate.com>.
394
395 =head1 AUTHORS
396
397 Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997.
398
399 Gurusamy Sarathy, gsar@activestate.com, 8 May 1999.
400
401 Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000.
402
403 More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
404
405 Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.
406
407 =cut