Commit | Line | Data |
---|---|---|
0c97a5ed JH |
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 | |
194 | host's workspace. You need to pick a name (for example, your | |
195 | hostname unless that clashes with someone else's client name) | |
196 | when you first start using the perl repository and then | |
197 | stick with it. If you connect from multiple hosts (with | |
198 | different workspaces) then maybe you could have multiple | |
199 | clients. There is a licence limit on the number of perforce | |
200 | clients which can be created. Although we have been told that | |
201 | Perforce will raise our licence limits within reason, it's | |
202 | probably best not to use additional clients unless needed. | |
203 | ||
204 | Note that perforce only needs the client name so that it can | |
205 | find the directory under which your client files are stored. | |
206 | If you have multiple hosts sharing the same directory structure | |
207 | via NFS then only one client name is necessary. | |
208 | ||
209 | The C<p4 clients> command lists all currently known clients. | |
210 | ||
211 | =item P4USER | |
212 | ||
213 | This is the username by which perforce knows you. Use your | |
214 | username if you have a well known or obvious one or else pick | |
215 | a new one which other perl5-porters will recognise. There is | |
216 | a licence limit on the number of these usernames. Perforce | |
217 | doesn't enforce security between usernames. If you set P4USER | |
218 | to be somebody else's username then perforce will believe you | |
219 | completely with regard to access control, logging and so on. | |
220 | ||
221 | The C<p4 users> command lists all currently known users. | |
222 | ||
223 | =back | |
224 | ||
225 | Once these three environment variables are set, you can use the | |
226 | perforce p4 client exactly as described in its documentation. | |
227 | After setting these variables and connecting to the repository | |
228 | for the first time, you should use the C<p4 user> and | |
229 | C<p4 client> commands to tell perforce the details of your | |
230 | new username and your new client workspace specifications. | |
231 | ||
232 | =head1 Ending a Repository Session | |
233 | ||
234 | When you have finished a session using the repository, you | |
235 | should kill off the ssh client process to break the tunnel. | |
236 | Since ssh forked itself into the background, you'll need to use | |
237 | something like ps with the appropriate options to find the ssh | |
238 | process and then kill it manually. The default signal of | |
239 | SIGTERM is fine. | |
240 | ||
241 | =head1 Overview of the Repository | |
242 | ||
243 | Please read at least the introductory sections of the Perforce | |
244 | User Guide (and perhaps the Quick Start Guide as well) before | |
245 | reading this section. | |
246 | ||
247 | Every repository user typically "owns" a "branch" of the mainline | |
248 | code in the repository. They hold the "pumpkin" for things in this | |
249 | area, and are usually the only user who will modify files there. | |
250 | This is not strictly enforced in order to allow the flexibility | |
251 | of other users stealing the pumpkin for short periods with the | |
252 | owner's permission. | |
253 | ||
254 | Here is the current structure of the repository: | |
255 | ||
256 | /----+-----perl - Mainline development (bleadperl) | |
257 | +-----cfgperl - Configure Pumpkin's Perl | |
258 | +-----vmsperl - VMS Pumpkin's Perl | |
259 | +-----maint-5.004------perl - Maintainance branches | |
260 | +-----maint-5.005------perl | |
261 | +-----maint-5.6------perl | |
262 | ||
263 | Perforce uses a branching model that simply tracks relationships | |
264 | between files. It does not care about directories at all, so | |
265 | any file can be a branch of any other file--the fully qualified | |
266 | depot path name (of the form //depot/foo/bar.c) uniquely determines | |
267 | a file for the purpose of establishing branching relationships. | |
268 | Since a branch usually involves hundreds of files, such relationships | |
269 | are typically specified en masse using a branch map (try `p4 help branch`). | |
270 | `p4 branches` lists the existing branches that have been set up. | |
271 | `p4 branch -o branchname` can be used to view the map for a particular | |
272 | branch, if you want to determine the ancestor for a particular set of | |
273 | files. | |
274 | ||
275 | The mainline (aka "trunk") code in the Perl repository is under | |
276 | "//depot/perl/...". Most branches typically map its entire | |
277 | contents under a directory that goes by the same name as the branch | |
278 | name. Thus the contents of the cfgperl branch are to be found | |
279 | in //depot/cfgperl. | |
280 | ||
281 | Run `p4 client` to specify how the repository contents should map to | |
282 | your local disk. Most users will typically have a client map that | |
283 | includes at least their entire branch and the contents of the mainline. | |
284 | ||
285 | Run `p4 changes -l -m10` to check on the activity in the repository. | |
286 | //depot/perl/Porting/genlog is useful to get an annotated changelog | |
287 | that shows files and branches. You can use this listing to determine | |
288 | if there are any changes in the mainline that you need to merge into | |
289 | your own branch. A typical merging session looks like this: | |
290 | ||
291 | % cd ~/p4view/cfgperl | |
292 | % p4 integrate -b cfgperl # to bring parent changes into cfgperl | |
293 | % p4 resolve -a ./... # auto merge the changes | |
294 | % p4 resolve ./... # manual merge conflicting changes | |
295 | % p4 submit ./... # check in | |
296 | ||
297 | If the owner of the mainline wants to bring the changes in cfgperl | |
298 | back into the mainline, they do: | |
299 | ||
300 | % p4 integrate -r -b cfgperl | |
301 | ... | |
302 | ||
303 | Generating a patch for change#42 is done as follows: | |
304 | ||
305 | % p4 describe -du 42 | p4desc | p4d2p > change-42.patch | |
306 | ||
307 | p4desc and p4d2p are to be found in //depot/perl/Porting/. | |
308 | ||
309 | =head1 Contact Information | |
310 | ||
b09defb6 JH |
311 | The mail alias <perl-repository-keepers@perl.org> can be used to reach |
312 | all current users of the repository. | |
0c97a5ed JH |
313 | |
314 | The repository keeper is currently Gurusamy Sarathy | |
315 | <gsar@activestate.com>. | |
316 | ||
317 | =head1 AUTHORS | |
318 | ||
319 | Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997. | |
320 | ||
321 | Gurusamy Sarathy, gsar@activestate.com, 8 May 1999. | |
322 | ||
323 | Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000 | |
324 | ||
325 | =cut | |
326 | ||
327 |