repository - Using the Perl repository
-This document describes what a Perl Porter needs to do
-to start using the Perl repository.
+=head1 Synopsis
+
+First, we assume here that you have already decided that you will
+need B<write> access to the repository. If all you need is B<read>
+access, there are much better ways to access the most current state of
+the perl repository, or explore individual files and patches therein.
+See L<perlhack> for details.
+
+This document describes what a Perl Porter needs to do to start using
+the Perl repository.
=head1 Prerequisites
which it's available. You only need to build the client parts (ssh
and ssh-keygen should suffice).
+If you're on Windows then you might like to obtain MSYS (Minimal System)
+from:
+
+ http://www.mingw.org/download.shtml
+
+which contains an ssh client. If you use this outside of the MSYS
+environment then you'll need to ensure the HOME environment variable
+is set to a suitable directory: ssh.exe will want to access files in
+a F<.ssh> sub-directory of %HOME%.
+
+Alternatively, the "plink" program, part of PuTTY:
+
+ http://www.chiark.greenend.org.uk/~sgtatham/putty/
+
+should also work fine for Windows users.
+
=back
=head1 Creating an SSH Key Pair
can be (but need not be) world readable. It is not used by your
own system at all.
+Note that the above process creates a key pair for ssh protocol 1.
+You can request ssh protocol 2 (RSA) instead if you prefer (if your
+particular ssh client supports it), via the command
+
+ ssh-keygen -t rsa
+
+This will create private/public identity files called F<~/.ssh/id_rsa>
+and F<~/.ssh/id_rsa.pub> respectively. Protocol 2 offers a higher
+level of security than protocol 1. This is not required for access to
+the Perl repository -- ssh is used for authentication rather than
+encryption (the Perl sources are open anyway) -- but either protocol
+is supported by the server.
+
=head1 Notifying the Repository Keeper
Mail the contents of that public key file to the keeper of the perl
you will be able to connect to it with ssh by using the corresponding
private key file (after unlocking it with your chosen passphrase).
+There is no harm in creating both protocol 1 and protocol 2 keys and
+mailing them both in. That way you'll be able to connect using either
+protocol, which may be useful if you later find yourself using a client
+that only supports one or the other protocol.
+
=head1 Connecting to the Repository
Connections to the repository are made by using ssh to provide a
TCP "tunnel" rather than by using ssh to login to or invoke any
-ordinary commands on the repository. When you want to start a
-session using the repository, use the command
+ordinary commands on the repository.
+
+The ssh (secure shell) protocol runs over port number 22, so if you
+have a firewall installed at the client end then you must ensure that
+it is configured to allow you to make an outgoing connection to port 22
+on sickle.activestate.com.
+
+When you want to start a session using the repository, use the command:
- ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com
-foo
+ ssh -l perlrep -f -q -x -L 1666:127.0.0.1:1666 sickle.activestate.com foo
-If you are not using the default filename of F<~/.ssh/identity>
-to hold your perl repository private key then you'll need to add
-the option B<-i filename> to tell ssh where it is. Unless you chose
-a blank passphrase for that private key, ssh will prompt you for the
-passphrase to unlock that key. Then ssh will fork and put itself
+If you are not using the default filename of F<~/.ssh/identity> or
+F<~/.ssh/id_rsa> to hold your perl repository private key then you'll
+need to add the option B<-i filename> to tell ssh where it is. Unless
+you chose a blank passphrase for that private key, ssh will prompt you
+for the passphrase to unlock that key. Then ssh will fork and put itself
in the background, returning you (silently) to your shell prompt.
+
+Note that the first time you connect you may see a message like
+"The authenticity of host 'sickle.activestate.com' can't be established,"
+and asking you if you want to continue. Just answer yes and sickle's
+details will be cached in a F<known_hosts> or F<known_hosts2> file. You
+will not see that message again unless you delete the cache file.
+
The tunnel for repository access is now ready for use.
For the sake of completeness (and for the case where the chosen
=over 4
-=item B<-l perl>
+=item B<-l perlrep>
-Use a remote username of perl. The account on the repository which
-provides the end-point of the ssh tunnel is named "perl".
+Use a remote username of perlrep. (The account on the repository which
+provides the end-point of the ssh tunnel is named "perlrep".)
=item B<-f>
=item sickle.activestate.com
-This is the canonical IP name of the host on which the perl
-repository runs. Its IP number is 199.60.48.20.
+This is the canonical name of the host on which the perl repository
+resides.
=item foo
perlrep@sickle.activestate.com's password:
-Then you either don't have a ~/.ssh/identity file corresponding
-to your public key, or your ~/.ssh/identity file is not readable.
+Then you either don't have a F<~/.ssh/identity> or F<~/.ssh/id_rsa>
+file corresponding to your public key, or that file is not readable.
Fix the problem and try again.
+If you only had the public key file for one protocol installed at the
+server end then make sure your client is using the corresponding
+protocol. An ssh client that supports protocol 2 will probably choose
+that by default, which will fail if the server end only has your public
+key file for protocol 1. Some ssh clients have "-1" and "-2" arguments
+to force which protocol to use.
+
+The "-v" (verbose) flag can be useful for seeing what protocol your
+client is actually trying to connect with, and for spotting any other
+problems. The flag can be specified multiple times to increase
+verbosity. Note that specifying the "-q" flag as well might override
+your request for verbose output, so drop the "-q" flag when trying this.
+
=head1 Using the Perforce Client
Remember to read the documentation for Perforce. You need
=item P4CLIENT
The value of this is the name by which Perforce knows your
-host's workspace. You need to pick a name (for example, your
-hostname unless that clashes with someone else's client name)
+host's workspace. You need to pick a name (normally, your
+Perforce username, a dash, and your host's short name)
when you first start using the perl repository and then
-stick with it. If you connect from multiple hosts (with
-different workspaces) then maybe you could have multiple
-clients. There is a licence limit on the number of perforce
-clients which can be created. Although we have been told that
-Perforce will raise our licence limits within reason, it's
-probably best not to use additional clients unless needed.
-
-Note that perforce only needs the client name so that it can
-find the directory under which your client files are stored.
+stick with it.
+
+Perforce keeps track of the files you have on your machine. It
+does this through your client. When you first sync a version of a
+file, the file comes from the server to your machine. If you sync
+the same file again the server does nothing because it
+knows you already have the file.
+
+You should NOT use the same client on different machines. If you do
+you probably won't get the files you expect, and may end up with
+nasty corruption. Perforce allows you to have as many clients as
+you want. For example, sally-home, sally-openbsd, sally-laptop.
+
+Also, never change the client's root and view at the same time.
+See C<http://www.perforce.com/perforce/doc.002/manuals/p4guide/04_details.html#1048341>
+
If you have multiple hosts sharing the same directory structure
-via NFS then only one client name is necessary.
+via NFS then you may be able to get away with only one client name,
+but be careful.
The C<p4 clients> command lists all currently known clients.
This is the username by which perforce knows you. Use your
username if you have a well known or obvious one or else pick
a new one which other perl5-porters will recognise. There is
-a licence limit on the number of these usernames. Perforce
-doesn't enforce security between usernames. If you set P4USER
-to be somebody else's username then perforce will believe you
-completely with regard to access control, logging and so on.
+a licence limit on the number of these usernames, so be sure not
+to use more than one.
+
+It is very important to set a password for your Perforce username,
+or else anyone can impersonate you. Use the C<p4 passwd> command
+to do this. Once a password is set for your account, you'll need
+to tell Perforce what it is. You can do this by setting the
+environment variable P4PASSWD, or you can use the C<-P> flag
+with the C<p4> command.
+
+There are a few techniques you can use to avoid having to either
+set an environment variable or type the password on every command.
+One is to create a shell alias, for example, in bash, add something like
+ alias p4='p4 -P secret'
+to your F<.bash_profile> file. Another way is to create a small shell
+script, for example
+ #!/bin/bash
+ p4 -P secret $@
+And use this instead of running C<p4> directly.
+
+With either of these, be sure the file containing your password
+(the F<.bash_profile> or shell script file) is only readable by you.
The C<p4 users> command lists all currently known users.
=back
+Note that on Windows P4PORT and P4USER are requested when installing
+Perforce. They are stored in the registry, so they do not need to be
+set in the environment.
+
Once these three environment variables are set, you can use the
perforce p4 client exactly as described in its documentation.
+
After setting these variables and connecting to the repository
-for the first time, you should use the C<p4 user> and
-C<p4 client> commands to tell perforce the details of your
-new username and your new client workspace specifications.
+for the first time, you should use the C<p4 user> command to
+set a valid email address for yourself. Messages to the commit list
+are sent (faked) from whatever email address you set here.
+
+Also use the C<p4 client> command to specify your workspace
+specifications for each individual client from which you will interact
+with the repository. The P4CLIENT environment variable, of course,
+needs to be set to one of these client workspace names.
=head1 Ending a Repository Session
of other users stealing the pumpkin for short periods with the
owner's permission.
-Here is the current structure of the repository:
+Here is (part of) the current structure of the repository:
/----+-----perl - Mainline development (bleadperl)
- +-----cfgperl - Configure Pumpkin's Perl
+ +-----perlio - PerlIO Pumpkin's Perl
+-----vmsperl - VMS Pumpkin's Perl
+-----maint-5.004------perl - Maintainance branches
+-----maint-5.005------perl
- +-----maint-5.6------perl
+ +-----maint-5.6--------perl
+ +-----maint-5.8--------perl
+ +-----pureperl---------pureperl
Perforce uses a branching model that simply tracks relationships
between files. It does not care about directories at all, so
The mainline (aka "trunk") code in the Perl repository is under
"//depot/perl/...". Most branches typically map its entire
contents under a directory that goes by the same name as the branch
-name. Thus the contents of the cfgperl branch are to be found
-in //depot/cfgperl.
+name. Thus the contents of the perlio branch are to be found
+in //depot/perlio.
Run `p4 client` to specify how the repository contents should map to
your local disk. Most users will typically have a client map that
if there are any changes in the mainline that you need to merge into
your own branch. A typical merging session looks like this:
- % cd ~/p4view/cfgperl
- % p4 integrate -b cfgperl # to bring parent changes into cfgperl
- % p4 resolve -a ./... # auto merge the changes
+ % cd ~/p4view/perlio
+ % p4 integrate -b perlio # to bring parent changes into perlio
+ % p4 resolve -am ./... # auto merge the changes
% p4 resolve ./... # manual merge conflicting changes
% p4 submit ./... # check in
-If the owner of the mainline wants to bring the changes in cfgperl
+If the owner of the mainline wants to bring the changes in perlio
back into the mainline, they do:
- % p4 integrate -r -b cfgperl
+ % p4 integrate -r -b perlio
...
Generating a patch for change#42 is done as follows:
- % p4 describe -du 42 | p4desc | p4d2p > change-42.patch
+ % p4genpatch 42 > change-42.patch
+
+F<p4genpatch> is to be found in //depot/perl/Porting/.
+
+The usual routine to apply a patch is
+
+ % p4 edit file.c file.h
+ % patch < patch.txt
+
+(any necessary, re-Configure, make regen_headers, make clean, etc, here)
+
+ % make all test
+
+(preferably make all test in several platforms and under several
+different Configurations)
+
+ % while unhappy
+ do
+ $EDITOR
+ make all test
+ done
+ % p4 submit
-p4desc and p4d2p are to be found in //depot/perl/Porting/.
+Other useful Perforce commands
+
+ % p4 describe -du 12345 # show change 12345
+
+Note: the output of "p4 describe" is not in proper diff format, use
+the F<Porting/p4genpatch> to get a diff-compatible format.
+(Note that it may be easier to get one already prepared: grep
+L<perlhack> for APC, and append eg "/diffs/12345.gz" to one of the
+URLs to get a usable patch.)
+
+ % p4 diff -se ./... # have I modified something but forgotten
+ # to "p4 edit", easy faux pas with autogenerated
+ # files like proto.h, or if one forgets to
+ # look carefully which files a patch modifies
+ % p4 sync file.h # if someone else has modified file.h
+ % p4 opened # which files are opened (p4 edit) by me
+ % p4 opened -a # which files are opened by anybody
+ % p4 diff -du file.c # what changes have I done
+ % p4 revert file.h # never mind my changes
+ % p4 sync -f argh.c # forcibly synchronize your file
+ # from the repository
+ % p4 diff -sr | p4 -x - revert
+ # throw away (opened but) unchanged files
+ # (in Perforce it's a little bit too easy
+ # to checkin unchanged files)
+
+Integrate patch 12345 from the mainline to the maint-5.6 branch:
+(you have to in the directory that has both the mainline and
+the maint-5.6/perl as subdirectories)
+
+ % p4 integrate -d perl/...@12345,12345 maint-5.6/perl/...
+
+Integrate patches 12347-12350 from the perlio branch to the mainline:
+
+ % p4 integrate -d perlio/...@12347,12350 perl/...
=head1 Contact Information
-The mail alias <perlforce@activestate.com> can be used to reach all
-current users of the repository.
+The mail alias E<lt>perl-repository-keepers@perl.orgE<gt> can be used to reach
+all current users of the repository.
The repository keeper is currently Gurusamy Sarathy
-<gsar@activestate.com>.
+E<lt>gsar@activestate.comE<gt>.
=head1 AUTHORS
-Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997.
+Malcolm Beattie, E<lt>mbeattie@sable.ox.ac.ukE<gt>, 24 June 1997.
-Gurusamy Sarathy, gsar@activestate.com, 8 May 1999.
+Gurusamy Sarathy, E<lt>gsar@activestate.comE<gt>, 8 May 1999.
-Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000
+Slightly updated by Simon Cozens, E<lt>simon@brecon.co.ukE<gt>, 3 July 2000.
-=cut
+More updates by Jarkko Hietaniemi, E<lt>jhi@iki.fiE<gt>, 28 June 2001.
+Perforce clarifications by Randall Gellens, E<lt>rcg@users.sourceforge.netE<gt>, 12 July 2001.
+Windows-related updates by Steve Hay E<lt>shay@cpan.orgE<gt>, 23 July 2004.
+
+=cut
https://perl5.git.perl.org / perl5.git / blobdiff