Metaconfig documentation update (part 1)

Fri 06 Sep 2002 20:26, Andy Dougherty
plus some tweaks

p4raw-id: //depot/metaconfig@17889

diff --git a/README b/README
index b6ad3b6..a68cc5b 100644 (file)
--- a/README
+++ b/README
@@ -1,13 +1,37 @@
-Jarrko's How to build Configure tweaked by Nick.
+       Jarrko's How to build Configure tweaked by Nick.
+
+The Configure script and config_h.SH file in the Perl distribution are
+generated by a program called metaconfig.  Metaconfig was originally 
+written by Larry Wall, and was subsequently enhanced and maintained
+by Raphael Manfredi.
 
 You have presumably obtained the metaconfig from the repository e.g.
-p4 sync //depot/metaconfig/...
-or some other way to obtain this file.
+  p4 sync //depot/metaconfig/...
+(those are three literal dots) or some other way to obtain this file,
+like a complete compressed archive from the previous pumpkin.
 
 Normally this directory and perl directory are next to each other
 so ../perl will get you to perl and ../perl/../metaconfig will get you
 back here.
 
+Contents of this directory:
+
+    README:    This file.
+    U:         Metaconfig units used for buliding Perl's Configure
+    U.check:   Sample directory used for testing new metaconfig units.
+               see U.check/README for more information.
+    dist-3.0at70: 
+               dist-3.0 at patchlevel 70.  This is the final version released
+               by Raphael Manfredi.  Don't use it.  Instead, use ...
+    dist-3.0at70b:
+               dist-3.0 at patchlevel 70 with unofficial patches 'a' and 'b'
+               applied.  This version was never officially released, but
+               the patches are essential, so this is the version we use for 
+               perl.  Actually, I've also applied U/dist_patches/dist-p70c
+               to this tree.  If someone with perforce access wants to change
+               the name of the directory, that'd be fine.  Otherwise, it really 
+               doesn't matter.
+
 (a) You need to have dist installed so that you have metalint and metaconfig
     in your $PATH.
     The dist version used for perl is dist-3.0at70b in this directory.
@@ -36,11 +60,13 @@ back here.
      1) have a symlink to ../metaconfig/U called U
      2) have a symlink to ../metaconfig/.package called .package
      3) have a symlink to MANIFEST called MANIFEST.new
+     4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
 
 (c) Write the new unit as U/foo/bar.U (usually 'foo' is just 'perl',
-    but sometimes there's some more appropriate subdir of U)
+    but sometimes there's some more appropriate subdir of U.  See
+    U/README for a description of the various subdirectories.)
 
-(d) metalint to see nits: as opposed to lint, the gripings of
+(d) Run metalint to see nits: as opposed to lint, the gripings of
     metalint are usually serious :-) and need fixing
 
     Exceptions are lots of
@@ -65,15 +91,18 @@ back here.
     For Win32 the process is semi-automated - if you have a Win32
     machine to run dmake on ...
 
-(h) then there's the running of mksample to freshen the Porting/config*
-    and Porting/Glossary, but I can't remember where the 'mksample' came
-    from, could be part of 'dist'. You can skip this phase,
-    it's not essential, just good housekeeping.
-
-(i) make veryclean;sh Configure -des -Dusedevel;make all test
+(h) Edit U/mkglossary (right near the top) to point to where you keep
+    dist's standard metaconfig units as well as your perl-specific ones.
 
-(j) p4 add ../metaconfig/foo/bar.U when you are ready ...
+(i) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
+    Adjust the various compile-time options (e.g. 64bit, threads) as
+    you see fit.
+    You can skip this phase, it's not essential, just good housekeeping.
 
-(k) p4 submit
+(j) make veryclean;sh Configure -des -Dusedevel;make all test
 
+(k) p4 add ../metaconfig/foo/bar.U when you are ready ...
 
+(l) p4 submit
+    Be sure to have EDITOR set to something that does NOT start
+    in the background like 'elvis -fork' or 'gvim'