From: Dave Rolsky <autarch@urth.org>
Date: Mon, 31 May 2004 12:52:43 +0000 (-0500)
Subject: perlhack.pod - working with the Perl source
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=fcc89a6494dc130c3657cad22a6e534f2cdd2805;p=p5sagit%2Fp5-mst-13.2.git

perlhack.pod - working with the Perl source
Message-ID: <Pine.LNX.4.58.0405311250520.7714@urth.org>

p4raw-id: //depot/perl@22882
---

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 5d746ac..0d7581c 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -479,6 +479,93 @@ 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<overwrite> 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<Configure> 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<perl-rsync> 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 you see this, you can abort the F<Configure> script, and you
+will see that the directory you are in has a tree of symlinks to the
+F<perl-rsync> 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
+	    /bin/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