From: Rafael Garcia-Suarez Date: Fri, 26 Dec 2008 08:47:06 +0000 (+0100) Subject: Remove mentions of the old way of rsync'ing the source X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b16c2e4a254d31480561f2bca5aeaeb75328de9c;p=p5sagit%2Fp5-mst-13.2.git Remove mentions of the old way of rsync'ing the source --- diff --git a/pod/perlhack.pod b/pod/perlhack.pod index ef648e7..dde67a3 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -207,23 +207,22 @@ interpreter. "A core module" is one that ships with Perl. =head2 Keeping in sync The source code to the Perl interpreter, in its different versions, is -kept in a repository managed by a revision control system ( which is -currently the Perforce program, see http://perforce.com/ ). The -pumpkings and a few others have access to the repository to check in -changes. Periodically the pumpking for the development version of Perl -will release a new version, so the rest of the porters can see what's -changed. The current state of the main trunk of repository, and patches -that describe the individual changes that have happened since the last -public release are available at this location: +kept in a repository managed by the git revision control system. The +pumpkings and a few others have write access to the repository to check in +changes. - http://public.activestate.com/pub/apc/ - ftp://public.activestate.com/pub/apc/ +How to clone and use the git perl repository is described in L. -If you're looking for a particular change, or a change that affected -a particular set of files, you may find the B -useful: +You can also choose to use rsync to get a copy of the current source tree +for the bleadperl branch and all maintainance branches : - http://public.activestate.com/cgi-bin/perlbrowse + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-current . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.10.x . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.8.x . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.6.x . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.005xx . + +(Add the C<--delete> option to remove leftover files) You may also want to subscribe to the perl5-changes mailing list to receive a copy of each patch that gets submitted to the maintenance @@ -240,334 +239,6 @@ Needless to say, the source code in perl-current is usually in a perpetual state of evolution. You should expect it to be very buggy. Do B use it for any purpose other than testing and development. -Keeping in sync with the most recent branch can be done in several ways, -but the most convenient and reliable way is using B, available at -ftp://rsync.samba.org/pub/rsync/ . (You can also get the most recent -branch by FTP.) - -If you choose to keep in sync using rsync, there are two approaches -to doing so: - -=over 4 - -=item rsync'ing the source tree - -Presuming you are in the directory where your perl source resides -and you have rsync installed and available, you can "upgrade" to -the bleadperl using: - - # rsync -avz rsync://public.activestate.com/perl-current/ . - -This takes care of updating every single item in the source tree to -the latest applied patch level, creating files that are new (to your -distribution) and setting date/time stamps of existing files to -reflect the bleadperl status. - -Note that this will not delete any files that were in '.' before -the rsync. Once you are sure that the rsync is running correctly, -run it with the --delete and the --dry-run options like this: - - # rsync -avz --delete --dry-run rsync://public.activestate.com/perl-current/ . - -This will I an rsync run that also deletes files not -present in the bleadperl master copy. Observe the results from -this run closely. If you are sure that the actual run would delete -no files precious to you, you could remove the '--dry-run' option. - -You can than check what patch was the latest that was applied by -looking in the file B<.patch>, which will show the number of the -latest patch. - -If you have more than one machine to keep in sync, and not all of -them have access to the WAN (so you are not able to rsync all the -source trees to the real source), there are some ways to get around -this problem. - -=over 4 - -=item Using rsync over the LAN - -Set up a local rsync server which makes the rsynced source tree -available to the LAN and sync the other machines against this -directory. - -From http://rsync.samba.org/README.html : - - "Rsync uses rsh or ssh for communication. It does not need to be - setuid and requires no special privileges for installation. It - does not require an inetd entry or a daemon. You must, however, - have a working rsh or ssh system. Using ssh is recommended for - its security features." - -=item Using pushing over the NFS - -Having the other systems mounted over the NFS, you can take an -active pushing approach by checking the just updated tree against -the other not-yet synced trees. An example would be - - #!/usr/bin/perl -w - - use strict; - use File::Copy; - - my %MF = map { - m/(\S+)/; - $1 => [ (stat $1)[2, 7, 9] ]; # mode, size, mtime - } `cat MANIFEST`; - - my %remote = map { $_ => "/$_/pro/3gl/CPAN/perl-5.7.1" } qw(host1 host2); - - foreach my $host (keys %remote) { - unless (-d $remote{$host}) { - print STDERR "Cannot Xsync for host $host\n"; - next; - } - foreach my $file (keys %MF) { - my $rfile = "$remote{$host}/$file"; - my ($mode, $size, $mtime) = (stat $rfile)[2, 7, 9]; - defined $size or ($mode, $size, $mtime) = (0, 0, 0); - $size == $MF{$file}[1] && $mtime == $MF{$file}[2] and next; - printf "%4s %-34s %8d %9d %8d %9d\n", - $host, $file, $MF{$file}[1], $MF{$file}[2], $size, $mtime; - unlink $rfile; - copy ($file, $rfile); - utime time, $MF{$file}[2], $rfile; - chmod $MF{$file}[0], $rfile; - } - } - -though this is not perfect. It could be improved with checking -file checksums before updating. Not all NFS systems support -reliable utime support (when used over the NFS). - -=back - -=item rsync'ing the patches - -The source tree is maintained by the pumpking who applies patches to -the files in the tree. These patches are either created by the -pumpking himself using C after updating the file manually or -by applying patches sent in by posters on the perl5-porters list. -These patches are also saved and rsync'able, so you can apply them -yourself to the source files. - -Presuming you are in a directory where your patches reside, you can -get them in sync with - - # rsync -avz rsync://public.activestate.com/perl-current-diffs/ . - -This makes sure the latest available patch is downloaded to your -patch directory. - -It's then up to you to apply these patches, using something like - - # last="`cat ../perl-current/.patch`.gz" - # rsync -avz rsync://public.activestate.com/perl-current-diffs/ . - # find . -name '*.gz' -newer $last -exec gzcat {} \; >blead.patch - # cd ../perl-current - # patch -p1 -N <../perl-current-diffs/blead.patch - -or, since this is only a hint towards how it works, use CPAN-patchaperl -from Andreas König to have better control over the patching process. - -=back - -=head2 Why rsync the source tree - -=over 4 - -=item It's easier to rsync the source tree - -Since you don't have to apply the patches yourself, you are sure all -files in the source tree are in the right state. - -=item It's more reliable - -While both the rsync-able source and patch areas are automatically -updated every few minutes, keep in mind that applying patches may -sometimes mean careful hand-holding, especially if your version of -the C program does not understand how to deal with new files, -files with 8-bit characters, or files without trailing newlines. - -=back - -=head2 Why rsync the patches - -=over 4 - -=item It's easier to rsync the patches - -If you have more than one machine that you want to keep in track with -bleadperl, it's easier to rsync the patches only once and then apply -them to all the source trees on the different machines. - -In case you try to keep in pace on 5 different machines, for which -only one of them has access to the WAN, rsync'ing all the source -trees should than be done 5 times over the NFS. Having -rsync'ed the patches only once, I can apply them to all the source -trees automatically. Need you say more ;-) - -=item It's a good reference - -If you do not only like to have the most recent development branch, -but also like to B bugs, or extend features, you want to dive -into the sources. If you are a seasoned perl core diver, you don't -need no manuals, tips, roadmaps, perlguts.pod or other aids to find -your way around. But if you are a starter, the patches may help you -in finding where you should start and how to change the bits that -bug you. - -The file B is updated on occasions the pumpking sees as his -own little sync points. On those occasions, he releases a tar-ball of -the current source tree (i.e. perl@7582.tar.gz), which will be an -excellent point to start with when choosing to use the 'rsync the -patches' scheme. Starting with perl@7582, which means a set of source -files on which the latest applied patch is number 7582, you apply all -succeeding patches available from then on (7583, 7584, ...). - -You can use the patches later as a kind of search archive. - -=over 4 - -=item Finding a start point - -If you want to fix/change the behaviour of function/feature Foo, just -scan the patches for patches that mention Foo either in the subject, -the comments, or the body of the fix. A good chance the patch shows -you the files that are affected by that patch which are very likely -to be the starting point of your journey into the guts of perl. - -=item Finding how to fix a bug - -If you've found I the function/feature Foo misbehaves, but you -don't know how to fix it (but you do know the change you want to -make), you can, again, peruse the patches for similar changes and -look how others apply the fix. - -=item Finding the source of misbehaviour - -When you keep in sync with bleadperl, the pumpking would love to -I that the community efforts really work. So after each of his -sync points, you are to 'make test' to check if everything is still -in working order. If it is, you do 'make ok', which will send an OK -report to I. (If you do not have access to a mailer -from the system you just finished successfully 'make test', you can -do 'make okfile', which creates the file C, which you can -than take to your favourite mailer and mail yourself). - -But of course, as always, things will not always lead to a success -path, and one or more test do not pass the 'make test'. Before -sending in a bug report (using 'make nok' or 'make nokfile'), check -the mailing list if someone else has reported the bug already and if -so, confirm it by replying to that message. If not, you might want to -trace the source of that misbehaviour B sending in the bug, -which will help all the other porters in finding the solution. - -Here the saved patches come in very handy. You can check the list of -patches to see which patch changed what file and what change caused -the misbehaviour. If you note that in the bug report, it saves the -one trying to solve it, looking for that point. - -=back - -If searching the patches is too bothersome, you might consider using -perl's bugtron to find more information about discussions and -ramblings on posted bugs. - -If you want to get the best of both worlds, rsync both the source -tree for convenience, reliability and ease and rsync the patches -for reference. - -=back - -=head2 Working with the source - -Because you cannot use the Perforce client, you cannot easily generate -diffs against the repository, nor will merges occur when you update -via rsync. If you edit a file locally and then rsync against the -latest source, changes made in the remote copy will I your -local versions! - -The best way to deal with this is to maintain a tree of symlinks to -the rsync'd source. Then, when you want to edit a file, you remove -the symlink, copy the real file into the other tree, and edit it. You -can then diff your edited file against the original to generate a -patch, and you can safely update the original tree. - -Perl's F script can generate this tree of symlinks for you. -The following example assumes that you have used rsync to pull a copy -of the Perl source into the F directory. In the directory -above that one, you can execute the following commands: - - mkdir perl-dev - cd perl-dev - ../perl-rsync/Configure -Dmksymlinks -Dusedevel -D"optimize=-g" - -This will start the Perl configuration process. After a few prompts, -you should see something like this: - - Symbolic links are supported. - - Checking how to test for symbolic links... - Your builtin 'test -h' may be broken. - Trying external '/usr/bin/test -h'. - You can test for symbolic links with '/usr/bin/test -h'. - - Creating the symbolic links... - (First creating the subdirectories...) - (Then creating the symlinks...) - -The specifics may vary based on your operating system, of course. -After it's all done, you -will see that the directory you are in has a tree of symlinks to the -F directories and files. - -If you plan to do a lot of work with the Perl source, here are some -Bourne shell script functions that can make your life easier: - - function edit { - if [ -L $1 ]; then - mv $1 $1.orig - cp $1.orig $1 - vi $1 - else - vi $1 - fi - } - - function unedit { - if [ -L $1.orig ]; then - rm $1 - mv $1.orig $1 - fi - } - -Replace "vi" with your favorite flavor of editor. - -Here is another function which will quickly generate a patch for the -files which have been edited in your symlink tree: - - mkpatchorig() { - local diffopts - for f in `find . -name '*.orig' | sed s,^\./,,` - do - case `echo $f | sed 's,.orig$,,;s,.*\.,,'` in - c) diffopts=-p ;; - pod) diffopts='-F^=' ;; - *) diffopts= ;; - esac - diff -du $diffopts $f `echo $f | sed 's,.orig$,,'` - done - } - -This function produces patches which include enough context to make -your changes obvious. This makes it easier for the Perl pumpking(s) -to review them when you send them to the perl5-porters list, and that -means they're more likely to get applied. - -This function assumed a GNU diff, and may require some tweaking for -other diff variants. - =head2 Perlbug administration There is a single remote administrative interface for modifying bug status, @@ -587,20 +258,14 @@ Always submit patches to I. If you're patching a core module and there's an author listed, send the author a copy (see L). This lets other porters review your patch, which catches a surprising number of errors in patches. -Either use the diff program (available in source code form from -ftp://ftp.gnu.org/pub/gnu/ , or use Johan Vromans' I -(available from I). Unified diffs are preferred, -but context diffs are accepted. Do not send RCS-style diffs or diffs -without context lines. More information is given in the -I file in the Perl source distribution. Please -patch against the latest B version. (e.g., even if you're -fixing a bug in the 5.8 track, patch against the latest B -version rsynced from rsync://public.activestate.com/perl-current/ ) +Please patch against the latest B version. (e.g., even if +you're fixing a bug in the 5.8 track, patch against the C branch in +the git repository.) If changes are accepted, they are applied to the development branch. Then -the 5.8 pumpking decides which of those patches is to be backported to the -maint branch. Only patches that survive the heat of the development -branch get applied to maintenance versions. +the maintainance pumpking decides which of those patches is to be +backported to the maint branch. Only patches that survive the heat of the +development branch get applied to maintenance versions. Your patch should update the documentation and test suite. See L. If you have added or removed files in the distribution, @@ -3699,3 +3364,6 @@ is, after all, what it's for. This document was written by Nathan Torkington, and is maintained by the perl5-porters mailing list. +=head1 SEE ALSO + +L