This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Ultimate discouragement for the old tools, from Andreas.
[perl5.git] / Porting / repository.pod
CommitLineData
0c97a5ed
JH
1=head1 NAME
2
3repository - Using the Perl repository
4
5This document describes what a Perl Porter needs to do
6to start using the Perl repository.
7
8=head1 Prerequisites
9
10You'll need to get hold of the following software.
11
12=over 4
13
14=item Perforce
15
16Download a perforce client from:
17
18 http://www.perforce.com/perforce/loadprog.html
19
20You'll probably also want to look at:
21
22 http://www.perforce.com/perforce/technical.html
23
24where you can look at or download its documentation.
25
26=item ssh
27
28If you don't already have access to an ssh client, then look at its
29home site C<http://www.cs.hut.fi/ssh> which mentions ftp sites from
30which it's available. You only need to build the client parts (ssh
31and ssh-keygen should suffice).
32
33=back
34
35=head1 Creating an SSH Key Pair
36
37If you already use ssh and want to use the same key pair for perl
38repository access then you can skip the rest of this section.
39Otherwise, generate an ssh key pair for use with the repository
40by typing the command
41
42 ssh-keygen
43
44After generating a key pair and testing it, ssh-keygen will ask you
45to enter a filename in which to save the key. The default it offers
46will be the file F<~/.ssh/identity> which is suitable unless you
47particularly want to keep separate ssh identities for some reason.
48If so, you could save the perl repository private key in the file
49F<~/.ssh/perl>, for example, but I will use the standard filename
50in the remainder of the examples of this document.
51
52After typing in the filename, it will prompt you to type in a
53passphrase. The private key will itself be encrypted so that it is
54usable only when that passphrase is typed. (When using ssh, you will
55be prompted when it requires a pass phrase to unlock a private key.)
56If you provide a blank passphrase then no passphrase will be needed
57to unlock the key and, as a consequence, anyone who gains access to
58the key file gains access to accounts protected with that key
59(barring additional configuration to restrict access by IP address).
60
61When you have typed the passphrase in twice, ssh-keygen will confirm
62where it has saved the private key (in the filename you gave and
63with permissions set to be only readable by you), what your public
64key is (don't worry: you don't need to memorise it) and where it
65has saved the corresponding public key. The public key is saved in
66a filename corresponding to your private key's filename but with
67".pub" appended, usually F<~/.ssh/identity.pub>. That public key
68can be (but need not be) world readable. It is not used by your
69own system at all.
70
71=head1 Notifying the Repository Keeper
72
73Mail the contents of that public key file to the keeper of the perl
74repository (see L</Contact Information> below).
75When the key is added to the repository host's configuration file,
76you will be able to connect to it with ssh by using the corresponding
77private key file (after unlocking it with your chosen passphrase).
78
79=head1 Connecting to the Repository
80
81Connections to the repository are made by using ssh to provide a
82TCP "tunnel" rather than by using ssh to login to or invoke any
83ordinary commands on the repository. When you want to start a
84session using the repository, use the command
85
4bc101a5 86 ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
0c97a5ed
JH
87
88If you are not using the default filename of F<~/.ssh/identity>
89to hold your perl repository private key then you'll need to add
90the option B<-i filename> to tell ssh where it is. Unless you chose
91a blank passphrase for that private key, ssh will prompt you for the
92passphrase to unlock that key. Then ssh will fork and put itself
93in the background, returning you (silently) to your shell prompt.
94The tunnel for repository access is now ready for use.
95
96For the sake of completeness (and for the case where the chosen
97port of 1666 is already in use on your machine), I'll briefly
98describe what all those ssh arguments are for.
99
100=over 4
101
4bc101a5 102=item B<-l perlrep>
0c97a5ed 103
4bc101a5
JH
104Use a remote username of perlrep. (The account on the repository which
105provides the end-point of the ssh tunnel is named "perlrep".)
0c97a5ed
JH
106
107=item B<-f>
108
109Tells ssh to fork and remain running in the background. Since ssh
110is only being used for its tunnelling capabilities, the command
111that ssh runs never does any I/O and can sit silently in the
112background.
113
114=item B<-q>
115
116Tells ssh to be quiet. Without this option, ssh will output a
117message each time you use a p4 command (since each p4 command
118tunnels over the ssh connection to reach the repository).
119
120=item B<-x>
121
122Tells ssh not to bother to set up a tunnel for X11 connections.
123The repository doesn't allow this anyway.
124
125=item B<-L 1666:127.0.0.1:1666>
126
127This is the important option. It tells ssh to listen out for
128connections made to port 1666 on your local machine. When such
129a connection is made, the ssh client tells the remote side
130(the corresponding ssh daemon on the repository) to make a
131connection to IP address 127.0.0.1, port 1666. Data flowing
132along that connection is tunnelled over the ssh connection
133(encrypted). The perforce daemon running on the repository
134only accepts connections from localhost and that is exactly
135where ssh-tunnelled connections appear to come from.
136
137If port 1666 is already in use on your machine then you can
138choose any non-privileged port (a number between 1024 and 65535)
139which happens to be free on your machine. It's the first of the
140three colon separated values that you should change. Picking
141port 2345 would mean changing the option to
142B<-L 2345:127.0.0.1:1666>. Whatever port number you choose should
143be used for the value of the P4PORT environment variable (q.v.).
144
145=item sickle.activestate.com
146
4bc101a5
JH
147This is the canonical name of the host on which the perl repository
148resides. Its IP address is 199.60.48.20.
0c97a5ed
JH
149
150=item foo
151
152This is a dummy place holder argument. Without an argument
153here, ssh will try to perform an interactive login to the
154repository which is not allowed. Ordinarily, this argument
155is for the one-off command which is to be executed on the
156remote host. However, the repository's ssh configuration
157file uses the "command=" option to force a particular
158command to run so the actual value of the argument is
159ignored. The command that's actually run merely pauses and
160waits for the ssh connection to drop, then exits.
161
162=back
163
164=head1 Problems
165
166You should normally get a prompt that asks for the passphrase
167for your RSA key when you connect with the ssh command shown
168above. If you see a prompt that looks like:
169
170 perlrep@sickle.activestate.com's password:
171
172Then you either don't have a ~/.ssh/identity file corresponding
173to your public key, or your ~/.ssh/identity file is not readable.
174Fix the problem and try again.
175
176=head1 Using the Perforce Client
177
178Remember to read the documentation for Perforce. You need
179to make sure that three environment variable are set
180correctly before using the p4 client with the perl repository.
181
182=over 4
183
184=item P4PORT
185
186Set this to localhost:1666 (the port for your ssh client to listen on)
187unless that port is already in use on your host. If it is, see
188the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
189
190=item P4CLIENT
191
192The value of this is the name by which Perforce knows your
2f6eead3
RG
193host's workspace. You need to pick a name (normally, your
194Perforce username, a dash, and your hostname)
0c97a5ed 195when you first start using the perl repository and then
2f6eead3
RG
196stick with it.
197
198Perforce keeps track of the files you have on your machine. It
199does this through your client. When you first sync a version of a
200file, the file comes from the server to your machine. If you sync
201the same file again the server does nothing because it
202knows you already have the file.
203
204You should NOT use the same client on different machines. If you do
205you probably won't get the files you expect, and may end up with
206nasty corruption. Perforce allows you to have as many clients as
207you want. For example, sally-home, sally-openbsd, sally-laptop.
208
209Also, never change the client's root and view at the same time.
210See C<http://www.perforce.com/perforce/doc.002/manuals/p4guide/04_details.html#1048341>
211
0c97a5ed 212If you have multiple hosts sharing the same directory structure
2f6eead3
RG
213via NFS then you may be able to get away with only one client name,
214but be careful.
0c97a5ed
JH
215
216The C<p4 clients> command lists all currently known clients.
217
218=item P4USER
219
220This is the username by which perforce knows you. Use your
221username if you have a well known or obvious one or else pick
222a new one which other perl5-porters will recognise. There is
2f6eead3
RG
223a licence limit on the number of these usernames, so be sure not
224to use more than one.
225
226It is very important to set a password for your Perforce username,
227or else anyone can impersonate you. Use the C<p4 passwd> command
228to do this. Once a password is set for your account, you'll need
229to tell Perforce what it is. You can do this by setting the
230environment variable P4PASSWD, or you can use the C<-P> flag
231with the C<p4> command.
232
233There are a few techniques you can use to avoid having to either
234set an environment variable or type the password on every command.
235One is to create a shell alias, for example, in bash, add something like
236 alias p4='p4 -P secret'
237to your F<.bash_profile> file. Another way is to create a small shell
238script, for example
239 #!/bin/bash
240 p4 -P secret $@
241And use this instead of running C<p4> directly.
242
243With either of these, be sure the file containing your password
244(the F<.bash_profile> or shell script file) is only readable by you.
0c97a5ed
JH
245
246The C<p4 users> command lists all currently known users.
247
248=back
249
250Once these three environment variables are set, you can use the
251perforce p4 client exactly as described in its documentation.
252After setting these variables and connecting to the repository
253for the first time, you should use the C<p4 user> and
254C<p4 client> commands to tell perforce the details of your
255new username and your new client workspace specifications.
256
257=head1 Ending a Repository Session
258
259When you have finished a session using the repository, you
260should kill off the ssh client process to break the tunnel.
261Since ssh forked itself into the background, you'll need to use
262something like ps with the appropriate options to find the ssh
263process and then kill it manually. The default signal of
264SIGTERM is fine.
265
266=head1 Overview of the Repository
267
268Please read at least the introductory sections of the Perforce
269User Guide (and perhaps the Quick Start Guide as well) before
270reading this section.
271
272Every repository user typically "owns" a "branch" of the mainline
273code in the repository. They hold the "pumpkin" for things in this
274area, and are usually the only user who will modify files there.
275This is not strictly enforced in order to allow the flexibility
276of other users stealing the pumpkin for short periods with the
277owner's permission.
278
279Here is the current structure of the repository:
280
281 /----+-----perl - Mainline development (bleadperl)
f704d51e 282 +-----perlio - PerlIO Pumpkin's Perl
0c97a5ed
JH
283 +-----vmsperl - VMS Pumpkin's Perl
284 +-----maint-5.004------perl - Maintainance branches
285 +-----maint-5.005------perl
286 +-----maint-5.6------perl
f704d51e 287 +-----maint-5.6------pureperl
0c97a5ed
JH
288
289Perforce uses a branching model that simply tracks relationships
290between files. It does not care about directories at all, so
291any file can be a branch of any other file--the fully qualified
292depot path name (of the form //depot/foo/bar.c) uniquely determines
293a file for the purpose of establishing branching relationships.
294Since a branch usually involves hundreds of files, such relationships
295are 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
298branch, if you want to determine the ancestor for a particular set of
299files.
300
301The mainline (aka "trunk") code in the Perl repository is under
302"//depot/perl/...". Most branches typically map its entire
303contents under a directory that goes by the same name as the branch
f704d51e
JH
304name. Thus the contents of the perlio branch are to be found
305in //depot/perlio.
0c97a5ed
JH
306
307Run `p4 client` to specify how the repository contents should map to
308your local disk. Most users will typically have a client map that
309includes at least their entire branch and the contents of the mainline.
310
311Run `p4 changes -l -m10` to check on the activity in the repository.
312//depot/perl/Porting/genlog is useful to get an annotated changelog
313that shows files and branches. You can use this listing to determine
314if there are any changes in the mainline that you need to merge into
315your own branch. A typical merging session looks like this:
316
f704d51e
JH
317 % cd ~/p4view/perlio
318 % p4 integrate -b perlio # to bring parent changes into perlio
319 % p4 resolve -am ./... # auto merge the changes
0c97a5ed
JH
320 % p4 resolve ./... # manual merge conflicting changes
321 % p4 submit ./... # check in
322
f704d51e 323If the owner of the mainline wants to bring the changes in perlio
0c97a5ed
JH
324back into the mainline, they do:
325
f704d51e 326 % p4 integrate -r -b perlio
0c97a5ed
JH
327 ...
328
329Generating a patch for change#42 is done as follows:
330
a2c6387b 331 % p4genpatch 42 > change-42.patch
0c97a5ed 332
a2c6387b 333F<p4genpatch> is to be found in //depot/perl/Porting/.
f704d51e
JH
334
335The 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
345different Configurations)
346
347 % while unhappy
348 do
349 $EDITOR
350 make all test
351 done
352 % p4 submit
353
354Other useful Perforce commands
355
356 % p4 describe -du 12345 # show change 12345
357
358Note: the output of "p4 describe" is not in proper diff format, use
a2c6387b 359the F<Porting/p4genpatch> to get a diff-compatible format.
f704d51e
JH
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
377Integrate patch 12345 from the mainline to the maint-5.6 branch:
378(you have to in the directory that has both the mainline and
379the maint-5.6/perl as subdirectories)
380
381 % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/...
382
383Integrate patches 12347-12350 from the perlio branch to the mainline:
384
385 % p4 integrate -d perlio/...@12347,12350 perl/...
0c97a5ed
JH
386
387=head1 Contact Information
388
b09defb6
JH
389The mail alias <perl-repository-keepers@perl.org> can be used to reach
390all current users of the repository.
0c97a5ed
JH
391
392The repository keeper is currently Gurusamy Sarathy
393<gsar@activestate.com>.
394
395=head1 AUTHORS
396
397Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997.
398
399Gurusamy Sarathy, gsar@activestate.com, 8 May 1999.
400
f704d51e
JH
401Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000.
402
403More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001.
0c97a5ed 404
2f6eead3
RG
405Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001.
406
0c97a5ed 407=cut