+++ /dev/null
-=head1 NAME
-
-repository - 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
-
-You'll need to get hold of the following software.
-
-=over 4
-
-=item Perforce
-
-Download a perforce client from:
-
- http://www.perforce.com/perforce/loadprog.html
-
-You'll probably also want to look at:
-
- http://www.perforce.com/perforce/technical.html
-
-where you can look at or download its documentation.
-
-=item ssh
-
-If you don't already have access to an ssh client, then look at its
-home site C<http://www.cs.hut.fi/ssh> which mentions ftp sites from
-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 Cygwin from:
-
- http://cygwin.com/
-
-which contains an ssh client. (MSYS also contains an ssh client
-but it seems to time-out and disconnect from the server and doesn't
-understand the ServerAliveInterval setting described later that can
-be used to stop Cygwin's ssh client from doing this.)
-
-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
-
-If you already use ssh and want to use the same key pair for perl
-repository access then you can skip the rest of this section.
-Otherwise, generate an ssh key pair for use with the repository
-by typing the command
-
- ssh-keygen
-
-After generating a key pair and testing it, ssh-keygen will ask you
-to enter a filename in which to save the key. The default it offers
-will be the file F<~/.ssh/identity> which is suitable unless you
-particularly want to keep separate ssh identities for some reason.
-If so, you could save the perl repository private key in the file
-F<~/.ssh/perl>, for example, but I will use the standard filename
-in the remainder of the examples of this document. (Some ssh
-implementations will default to creating a F<~/.ssh/id_rsa*>
-ssh prototcol 2 RSA key pair instead - see below. Use the -t rsa1
-option if you really want a protocol 1 key pair.)
-
-After typing in the filename, it will prompt you to type in a
-passphrase. The private key will itself be encrypted so that it is
-usable only when that passphrase is typed. (When using ssh, you will
-be prompted when it requires a pass phrase to unlock a private key.)
-If you provide a blank passphrase then no passphrase will be needed
-to unlock the key and, as a consequence, anyone who gains access to
-the key file gains access to accounts protected with that key
-(barring additional configuration to restrict access by IP address).
-
-When you have typed the passphrase in twice, ssh-keygen will confirm
-where it has saved the private key (in the filename you gave and
-with permissions set to be only readable by you), what your public
-key is (don't worry: you don't need to memorise it) and where it
-has saved the corresponding public key. The public key is saved in
-a filename corresponding to your private key's filename but with
-".pub" appended, usually F<~/.ssh/identity.pub>. That public key
-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.
-
-B<IMPORTANT NOTE FOR CYGWIN USERS:> In order to make the private key
-files only readable by you you must include the string "ntea" in the
-"CYGWIN" environment variable in the shell used to run C<chmod(1)>,
-and in the shell used to run the ssh client itself later. If "CYGWIN"
-doesn't contain "ntea" then it will appear to the ssh client that the
-file permissions are not set correctly, in which case the files will be
-ignored and you won't be able to connect.
-
-=head1 Notifying the Repository Keeper
-
-Mail the contents of that public key file to the keeper of the perl
-repository (see L</Contact Information> below).
-When the key is added to the repository host's configuration file,
-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.
-
-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
-
-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
-port of 1666 is already in use on your machine), I'll briefly
-describe what all those ssh arguments are for.
-
-=over 4
-
-=item B<-l perlrep>
-
-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>
-
-Tells ssh to fork and remain running in the background. Since ssh
-is only being used for its tunnelling capabilities, the command
-that ssh runs never does any I/O and can sit silently in the
-background.
-
-=item B<-q>
-
-Tells ssh to be quiet. Without this option, ssh will output a
-message each time you use a p4 command (since each p4 command
-tunnels over the ssh connection to reach the repository).
-
-=item B<-x>
-
-Tells ssh not to bother to set up a tunnel for X11 connections.
-The repository doesn't allow this anyway.
-
-=item B<-L 1666:127.0.0.1:1666>
-
-This is the important option. It tells ssh to listen out for
-connections made to port 1666 on your local machine. When such
-a connection is made, the ssh client tells the remote side
-(the corresponding ssh daemon on the repository) to make a
-connection to IP address 127.0.0.1, port 1666. Data flowing
-along that connection is tunnelled over the ssh connection
-(encrypted). The perforce daemon running on the repository
-only accepts connections from localhost and that is exactly
-where ssh-tunnelled connections appear to come from.
-
-If port 1666 is already in use on your machine then you can
-choose any non-privileged port (a number between 1024 and 65535)
-which happens to be free on your machine. It's the first of the
-three colon separated values that you should change. Picking
-port 2345 would mean changing the option to
-B<-L 2345:127.0.0.1:1666>. Whatever port number you choose should
-be used for the value of the P4PORT environment variable (q.v.).
-
-=item sickle.activestate.com
-
-This is the canonical name of the host on which the perl repository
-resides.
-
-=item foo
-
-This is a dummy place holder argument. Without an argument
-here, ssh will try to perform an interactive login to the
-repository which is not allowed. Ordinarily, this argument
-is for the one-off command which is to be executed on the
-remote host. However, the repository's ssh configuration
-file uses the "command=" option to force a particular
-command to run so the actual value of the argument is
-ignored. The command that's actually run merely pauses and
-waits for the ssh connection to drop, then exits.
-
-=back
-
-=head1 Problems
-
-You should normally get a prompt that asks for the passphrase
-for your RSA key when you connect with the ssh command shown
-above. If you see a prompt that looks like:
-
- perlrep@sickle.activestate.com's password:
-
-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. Alternatively, some ssh implementations
-will fail to verify your RSA key if the key if readable by others.
-Just lower the permissions to make the key readable to yourself.
-
-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.
-
-If you're using the Cygwin ssh client on Windows then you will probably
-find that the connection times out after a short period of inactivity.
-You will have to keep re-entering your passphrase to reconnect, which
-gets annoying after a while. In order to prevent these time-outs from
-happening place the following two lines in the file F<~/.ssh/config>:
-
- Host sickle.activestate.com
- ServerAliveInterval 120
-
-This causes the ssh client to send a message to the server every 120
-seconds to check that the server is still alive. The client will not
-disconnect unless "ServerAliveCountMax" many of these messages go
-unanswered. Run C<man ssh_config> for more details. Note also that
-this option applies to protocol version 2 only.
-
-=head1 Using the Perforce Client
-
-Remember to read the documentation for Perforce. You need
-to make sure that three environment variable are set
-correctly before using the p4 client with the perl repository.
-
-=over 4
-
-=item P4PORT
-
-Set this to localhost:1666 (the port for your ssh client to listen on)
-unless that port is already in use on your host. If it is, see
-the section above on the B<-L 1666:127.0.0.1:1666> option to ssh.
-
-=item P4CLIENT
-
-The value of this is the name by which Perforce knows your
-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.
-
-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 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.
-
-=item P4USER
-
-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, 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> 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
-
-When you have finished a session using the repository, you
-should kill off the ssh client process to break the tunnel.
-Since ssh forked itself into the background, you'll need to use
-something like ps with the appropriate options to find the ssh
-process and then kill it manually. The default signal of
-SIGTERM is fine.
-
-=head1 Overview of the Repository
-
-Please read at least the introductory sections of the Perforce
-User Guide (and perhaps the Quick Start Guide as well) before
-reading this section.
-
-Every repository user typically "owns" a "branch" of the mainline
-code in the repository. They hold the "pumpkin" for things in this
-area, and are usually the only user who will modify files there.
-This is not strictly enforced in order to allow the flexibility
-of other users stealing the pumpkin for short periods with the
-owner's permission.
-
-Here is (part of) the current structure of the repository:
-
- /----+-----perl - Mainline development (bleadperl)
- +-----perlio - PerlIO Pumpkin's Perl
- +-----vmsperl - VMS Pumpkin's Perl
- +-----maint-5.004------perl - Maintenance branches
- +-----maint-5.005------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
-any file can be a branch of any other file--the fully qualified
-depot path name (of the form //depot/foo/bar.c) uniquely determines
-a file for the purpose of establishing branching relationships.
-Since a branch usually involves hundreds of files, such relationships
-are typically specified en masse using a branch map (try `p4 help branch`).
-`p4 branches` lists the existing branches that have been set up.
-`p4 branch -o branchname` can be used to view the map for a particular
-branch, if you want to determine the ancestor for a particular set of
-files.
-
-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 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
-includes at least their entire branch and the contents of the mainline.
-
-Run `p4 changes -l -m10` to check on the activity in the repository.
-//depot/perl/Porting/genlog is useful to get an annotated changelog
-that shows files and branches. You can use this listing to determine
-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/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 perlio
-back into the mainline, they do:
-
- % p4 integrate -r -b perlio
- ...
-
-Generating a patch for change#42 is done as follows:
-
- % 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
-
-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 E<lt>perl-repository-keepers@perl.orgE<gt> can be used to reach
-all current users of the repository.
-
-The repository keeper is currently Kevin J. Woolley
-E<lt>kevinw@ActiveState.comE<gt>.
-
-=head1 AUTHORS
-
-Malcolm Beattie, E<lt>mbeattie@sable.ox.ac.ukE<gt>, 24 June 1997.
-
-Gurusamy Sarathy, E<lt>gsar@activestate.comE<gt>, 8 May 1999.
-
-Slightly updated by Simon Cozens, E<lt>simon@brecon.co.ukE<gt>, 3 July 2000.
-
-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
-and 08 Aug 2005.
-
-=cut
projects / p5sagit/p5-mst-13.2.git / commitdiff