diff options
Diffstat (limited to 'Porting')
| -rw-r--r-- | Porting/Glossary | 9 | ||||
| -rw-r--r-- | Porting/config.sh | 6 | ||||
| -rw-r--r-- | Porting/config_H | 13 | ||||
| -rw-r--r-- | Porting/repository.pod | 327 |
4 files changed, 352 insertions, 3 deletions
diff --git a/Porting/Glossary b/Porting/Glossary index 1b93821e9b..40e468d56a 100644 --- a/Porting/Glossary +++ b/Porting/Glossary @@ -1478,6 +1478,15 @@ d_stdio_ptr_lval (d_stdstdio.U): This variable conditionally defines STDIO_PTR_LVALUE if the FILE_ptr macro can be used as an lvalue. +d_stdio_ptr_lval_nochange_cnt (d_stdstdio.U): + This symbol is defined if using the FILE_ptr macro as an lvalue + to increase the pointer by n leaves File_cnt(fp) unchanged. + +d_stdio_ptr_lval_sets_cnt (d_stdstdio.U): + This symbol is defined if using the FILE_ptr macro as an lvalue + to increase the pointer by n has the side effect of decreasing the + value of File_cnt(fp) by n. + d_stdio_stream_array (stdio_streams.U): This variable tells whether there is an array holding the stdio streams. diff --git a/Porting/config.sh b/Porting/config.sh index 632c469288..2c9a49e235 100644 --- a/Porting/config.sh +++ b/Porting/config.sh @@ -8,7 +8,7 @@ # Package name : perl5 # Source directory : /m/fs/work/work/permanent/perl/pp4/perl -# Configuration time: Fri Oct 13 02:12:22 EET DST 2000 +# Configuration time: Tue Oct 24 21:07:39 EET DST 2000 # Configured by : jhi # Target system : osf1 alpha.hut.fi v4.0 878 alpha @@ -62,7 +62,7 @@ ccsymbols='__alpha=1 __LANGUAGE_C__=1 __osf__=1 __unix__=1 _LONGLONG=1 _SYSTYPE_ ccversion='V5.6-082' cf_by='jhi' cf_email='yourname@yourhost.yourplace.com' -cf_time='Fri Oct 13 02:12:22 EET DST 2000' +cf_time='Tue Oct 24 21:07:39 EET DST 2000' charsize='1' chgrp='' chmod='' @@ -336,6 +336,8 @@ d_statfs_s='define' d_statvfs='define' d_stdio_cnt_lval='define' d_stdio_ptr_lval='define' +d_stdio_ptr_lval_nochange_cnt='undef' +d_stdio_ptr_lval_sets_cnt='undef' d_stdio_stream_array='define' d_stdiobase='define' d_stdstdio='define' diff --git a/Porting/config_H b/Porting/config_H index 149760ceaf..3cbfeaebf9 100644 --- a/Porting/config_H +++ b/Porting/config_H @@ -17,7 +17,7 @@ /* * Package name : perl5 * Source directory : /m/fs/work/work/permanent/perl/pp4/perl - * Configuration time: Fri Oct 13 02:12:22 EET DST 2000 + * Configuration time: Tue Oct 24 21:07:39 EET DST 2000 * Configured by : jhi * Target system : osf1 alpha.hut.fi v4.0 878 alpha */ @@ -2028,12 +2028,23 @@ * This symbol is defined if the FILE_cnt macro can be used as an * lvalue. */ +/* STDIO_PTR_LVAL_SETS_CNT: + * This symbol is defined if using the FILE_ptr macro as an lvalue + * to increase the pointer by n has the side effect of decreasing the + * value of File_cnt(fp) by n. + */ +/* STDIO_PTR_LVAL_NOCHANGE_CNT: + * This symbol is defined if using the FILE_ptr macro as an lvalue + * to increase the pointer by n leaves File_cnt(fp) unchanged. + */ #define USE_STDIO_PTR /**/ #ifdef USE_STDIO_PTR #define FILE_ptr(fp) ((fp)->_ptr) #define STDIO_PTR_LVALUE /**/ #define FILE_cnt(fp) ((fp)->_cnt) #define STDIO_CNT_LVALUE /**/ +/*#define STDIO_PTR_LVAL_SETS_CNT / **/ +/*#define STDIO_PTR_LVAL_NOCHANGE_CNT / **/ #endif /* USE_STDIO_BASE: diff --git a/Porting/repository.pod b/Porting/repository.pod new file mode 100644 index 0000000000..5f1338dd64 --- /dev/null +++ b/Porting/repository.pod @@ -0,0 +1,327 @@ +=head1 NAME + +repository - Using the Perl repository + +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). + +=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. + +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. + +=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). + +=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 + + 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 +in the background, returning you (silently) to your shell prompt. +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 perl> + +Use a remote username of perl. The account on the repository which +provides the end-point of the ssh tunnel is named "perl". + +=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 IP name of the host on which the perl +repository runs. Its IP number is 199.60.48.20. + +=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 ~/.ssh/identity file corresponding +to your public key, or your ~/.ssh/identity file is not readable. +Fix the problem and try again. + +=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 (for example, your +hostname unless that clashes with someone else's client 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. +If you have multiple hosts sharing the same directory structure +via NFS then only one client name is necessary. + +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. 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. + +The C<p4 users> command lists all currently known users. + +=back + +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. + +=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 the current structure of the repository: + + /----+-----perl - Mainline development (bleadperl) + +-----cfgperl - Configure Pumpkin's Perl + +-----vmsperl - VMS Pumpkin's Perl + +-----maint-5.004------perl - Maintainance branches + +-----maint-5.005------perl + +-----maint-5.6------perl + +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 cfgperl branch are to be found +in //depot/cfgperl. + +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/cfgperl + % p4 integrate -b cfgperl # to bring parent changes into cfgperl + % p4 resolve -a ./... # 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 +back into the mainline, they do: + + % p4 integrate -r -b cfgperl + ... + +Generating a patch for change#42 is done as follows: + + % p4 describe -du 42 | p4desc | p4d2p > change-42.patch + +p4desc and p4d2p are to be found in //depot/perl/Porting/. + +=head1 Contact Information + +The mail alias <perl-repository-keepers@perl.org> can be used to reach +all current users of the repository. + +The repository keeper is currently Gurusamy Sarathy +<gsar@activestate.com>. + +=head1 AUTHORS + +Malcolm Beattie, mbeattie@sable.ox.ac.uk, 24 June 1997. + +Gurusamy Sarathy, gsar@activestate.com, 8 May 1999. + +Slightly updated by Simon Cozens, simon@brecon.co.uk, 3 July 2000 + +=cut + + |