Commit | Line | Data |
0c97a5ed |
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 |
87 | foo |
88 | |
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. |
96 | |
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. |
100 | |
101 | =over 4 |
102 | |
103 | =item B<-l perl> |
104 | |
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". |
107 | |
108 | =item B<-f> |
109 | |
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 |
113 | background. |
114 | |
115 | =item B<-q> |
116 | |
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). |
120 | |
121 | =item B<-x> |
122 | |
123 | Tells ssh not to bother to set up a tunnel for X11 connections. |
124 | The repository doesn't allow this anyway. |
125 | |
126 | =item B<-L 1666:127.0.0.1:1666> |
127 | |
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. |
137 | |
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.). |
145 | |
146 | =item sickle.activestate.com |
147 | |
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. |
150 | |
151 | =item foo |
152 | |
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. |
162 | |
163 | =back |
164 | |
165 | =head1 Problems |
166 | |
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: |
170 | |
171 | perlrep@sickle.activestate.com's password: |
172 | |
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. |
176 | |
177 | =head1 Using the Perforce Client |
178 | |
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. |
182 | |
183 | =over 4 |
184 | |
185 | =item P4PORT |
186 | |
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. |
190 | |
191 | =item P4CLIENT |
192 | |
193 | The value of this is the name by which Perforce knows your |
2f6eead3 |
194 | host's workspace. You need to pick a name (normally, your |
195 | Perforce username, a dash, and your hostname) |
0c97a5ed |
196 | when you first start using the perl repository and then |
2f6eead3 |
197 | stick with it. |
198 | |
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. |
204 | |
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. |
209 | |
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> |
212 | |
0c97a5ed |
213 | If you have multiple hosts sharing the same directory structure |
2f6eead3 |
214 | via NFS then you may be able to get away with only one client name, |
215 | but be careful. |
0c97a5ed |
216 | |
217 | The C<p4 clients> command lists all currently known clients. |
218 | |
219 | =item P4USER |
220 | |
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 |
2f6eead3 |
224 | a licence limit on the number of these usernames, so be sure not |
225 | to use more than one. |
226 | |
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. |
233 | |
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 |
239 | script, for example |
240 | #!/bin/bash |
241 | p4 -P secret $@ |
242 | And use this instead of running C<p4> directly. |
243 | |
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. |
0c97a5ed |
246 | |
247 | The C<p4 users> command lists all currently known users. |
248 | |
249 | =back |
250 | |
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. |
257 | |
258 | =head1 Ending a Repository Session |
259 | |
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 |
265 | SIGTERM is fine. |
266 | |
267 | =head1 Overview of the Repository |
268 | |
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. |
272 | |
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 |
278 | owner's permission. |
279 | |
280 | Here is the current structure of the repository: |
281 | |
282 | /----+-----perl - Mainline development (bleadperl) |
f704d51e |
283 | +-----perlio - PerlIO Pumpkin's Perl |
0c97a5ed |
284 | +-----vmsperl - VMS Pumpkin's Perl |
285 | +-----maint-5.004------perl - Maintainance branches |
286 | +-----maint-5.005------perl |
287 | +-----maint-5.6------perl |
f704d51e |
288 | +-----maint-5.6------pureperl |
0c97a5ed |
289 | |
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 |
300 | files. |
301 | |
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 |
f704d51e |
305 | name. Thus the contents of the perlio branch are to be found |
306 | in //depot/perlio. |
0c97a5ed |
307 | |
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. |
311 | |
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: |
317 | |
f704d51e |
318 | % cd ~/p4view/perlio |
319 | % p4 integrate -b perlio # to bring parent changes into perlio |
320 | % p4 resolve -am ./... # auto merge the changes |
0c97a5ed |
321 | % p4 resolve ./... # manual merge conflicting changes |
322 | % p4 submit ./... # check in |
323 | |
f704d51e |
324 | If the owner of the mainline wants to bring the changes in perlio |
0c97a5ed |
325 | back into the mainline, they do: |
326 | |
f704d51e |
327 | % p4 integrate -r -b perlio |
0c97a5ed |
328 | ... |
329 | |
330 | Generating a patch for change#42 is done as follows: |
331 | |
332 | % p4 describe -du 42 | p4desc | p4d2p > change-42.patch |
333 | |
f704d51e |
334 | F<p4desc> and F<>p4d2p> are to be found in //depot/perl/Porting/. |
335 | |
336 | The usual routine to apply a patch is |
337 | |
338 | % p4 edit file.c file.h |
339 | % patch < patch.txt |
340 | |
341 | (any necessary, re-Configure, make regen_headers, make clean, etc, here) |
342 | |
343 | % make all test |
344 | |
345 | (preferably make all test in several platforms and under several |
346 | different Configurations) |
347 | |
348 | % while unhappy |
349 | do |
350 | $EDITOR |
351 | make all test |
352 | done |
353 | % p4 submit |
354 | |
355 | Other useful Perforce commands |
356 | |
357 | % p4 describe -du 12345 # show change 12345 |
358 | |
359 | Note: the output of "p4 describe" is not in proper diff format, use |
360 | the F<Porting/p4d2p> to convert. |
361 | |
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) |
377 | |
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) |
381 | |
382 | % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/... |
383 | |
384 | Integrate patches 12347-12350 from the perlio branch to the mainline: |
385 | |
386 | % p4 integrate -d perlio/...@12347,12350 perl/... |
0c97a5ed |
387 | |
388 | =head1 Contact Information |
389 | |
b09defb6 |
390 | The mail alias <perl-repository-keepers@perl.org> can be used to reach |
391 | all current users of the repository. |
0c97a5ed |
392 | |
393 | The repository keeper is currently Gurusamy Sarathy |
394 | <gsar@activestate.com>. |
395 | |
396 | =head1 AUTHORS |
397 | |
398 | Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997. |
399 | |
400 | Gurusamy Sarathy, gsar@activestate.com, 8 May 1999. |
401 | |
f704d51e |
402 | Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000. |
403 | |
404 | More updates by Jarkko Hietaniemi, jhi@iki.fi, 28 June 2001. |
0c97a5ed |
405 | |
2f6eead3 |
406 | Perforce clarifications by Randall Gellens, rcg@users.sourceforge.net, 12 July 2001. |
407 | |
0c97a5ed |
408 | =cut |
409 | |
410 | |