This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix ups for README
[metaconfig.git] / README
diff --git a/README b/README
index 427c34b..95fd9d4 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,8 @@
-       Jarkko's How to build Configure tweaked by Nick and Merijn.
+  Jarkko's How to build Configure tweaked by Nick and Merijn, and now
+                 maintained by perl5-metaconfig
 
 The Configure script and config_h.SH file in the Perl distribution are
-generated by a program called metaconfig.  Metaconfig was originally 
+generated by a program called metaconfig.  Metaconfig was originally
 written by Larry Wall, and was subsequently enhanced and maintained
 by Raphael Manfredi. The binary that invokes the generation of the
 Configure file is called mconfig.
@@ -28,6 +29,8 @@ is generated such as this:
   $ cd metaconfig
   $ ln -s ../perl perl
 
+We will do the reverse symlinks later.
+
 Contents of this directory:
 
     README:    This file.
@@ -73,7 +76,8 @@ Contents of this directory:
     There are some perl specific "dist units" in the 'U' directory.
     The U directory also contains some patches to 'dist' which have already
     been applied to dist-3.5-20 directory.
-    We have not yet arranged for metaconfig to use perl's versions of the
+
+(aa) We have not yet arranged for metaconfig to use perl's versions of the
     'units' by default so you need some housekeeping in the perl directory...
 
     Then add metaconfig/bin to your $PATH or create aliases like
@@ -85,7 +89,7 @@ Contents of this directory:
     examples in the rest of this README will just refer to mlint and mconfig
     as if they appear in your $PATH
 
-(aa)
+(aaa)
 
     If you plan to make changes to mconfig or mlint locally (and you might
     want to, as both are written for perl4), consider installing mconfig and
@@ -93,19 +97,25 @@ Contents of this directory:
     non-autoloading versions and can easily be changed. As these are used by
     all team members, please communicate changes on github first.
 
-(b) You need to be in the 'perl' checkout directory, which you created the symbolic
-    link for in preparation. In this working directory, you need symbolic
-    links too, which are already known to perl itself to ignore. Assuming
-    you have metaconfig and perl side by side on the same level:
-     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/perl/d_bar.U ('perl' can also be 'modified',
-    'compline' or any other existing folder, except for 'all'). Choose
-    the best appropriate subdir of U.  See U/README for a description of
-    the various subdirectories.)
+(b) You need to be in the 'perl' checkout directory, which you created the
+    symbolic link to, in preparation. In this working directory, you need
+    symbolic links too, which are already known to perl itself to ignore.
+    Assuming you have metaconfig and perl side by side on the same level:
+        ln -s ../metaconfig/U U
+        ln -s ../metaconfig/.package .package
+        ln -s MANIFEST MANIFEST.new
+        chmod +w Configure config_h.SH Porting/Glossary Porting/config*
+
+(c) Create a new file for the new unit as U/foo/d_bar.U
+    ('foo' is one of the existing folders in U except for 'all'.  It most
+    likely will be 'perl', but it could also be 'modified', 'compline' or any
+    other existing folder).  Choose the best appropriate subdir of U.  See
+    U/README for a description of the various subdirectories.)  You should
+    choose the closest existing unit file as a starting point, and first copy
+    it to the new file.  For example, the unit for seeing if strtold_l() exists
+    was created as U/threads/d_strtold_l.U, copied from perl/d_strtold.U, then
+    adjusted.  It goes under 'threads' because it is used only on threaded
+    perls.
 
 (d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
     are usually serious and need fixing
@@ -120,11 +130,15 @@ Contents of this directory:
 
     which is apparently normal ...
 
--- the next steps are in the perl folder
-
-(e) chmod +w Configure config_h.SH
+-- the next steps are in the perl folder, though the instructions below include
+   a 'cd perl' at each step, as a reminder.  If you already are in 'perl',
+   disregard the reminders.
 
-    mlint and mconfig will probably die when these are read-only
+(e) There is a chicken and egg problem for newly created units.  To get around
+    this, for such a unit, edit the file metaconfig.h and add to the comment
+    the appropropriate name.  To continue the example above, we would add the
+    string HAS_STRTOLD_L at the end of the comment.  This can be removed once
+    the code base has actual uses of the unit.
 
 (f) mconfig -m -O to regenerate Configure and config_h.SH
 
@@ -139,7 +153,7 @@ Contents of this directory:
     $ perl Porting/config_h.pl
 
     will fix the ordering
-    
+
 (h) The messy semi-automated part is that the knowledge of the new symbol
     needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
     VMS, VOS, EPOC, ...  see previous Configure changes to see which are these
@@ -160,8 +174,13 @@ Contents of this directory:
 
     (of course "define" can also be "undef" based on the changes you made
 
-    For Win32 the process is semi-automated - if you have a Win32
-    machine to run dmake on ...
+    For Win32 the process is semi-automated -- if you have a Win32
+    machine to run dmake on
+
+    For vms, ('configure.com'), you likely will have to hand-edit in the
+    changes, using a similar unit as a starting point.  There likely will be at
+    least 2 groups of changes.  Rerun the tool until you've fixed everything it
+    finds.
 
 (i) Check if U/mkglossary (right near the top) points to where you keep
     dist's standard metaconfig units as well as your perl-specific ones.
@@ -169,12 +188,8 @@ Contents of this directory:
 (j) Run the perl build chain
 
     $ cd perl
-    $ make veryclean
+    $ make veryclean    # Only if Configure already has been run
     $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
-
-    The dependency for uconfig.h isn't carved in stone, so you might
-    need to regenerate it
-
     $ perl regen/uconfig_h.pl
 
     Then make and make test or make test_harness
@@ -189,10 +204,10 @@ Contents of this directory:
 
     again
 
-(k) Run Porting/mksample to freshen the Porting/config*.
+(k) Optionally, run Porting/mksample to freshen the Porting/config*.
     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.
+    You can skip this step, it's not essential, just good housekeeping.
 
     Most of this only works if you have run the core-tests with the new
     generated files
@@ -212,7 +227,7 @@ Contents of this directory:
 
 -- the next steps are in the metaconfig folder again
 
-(l) git add U/perl/foo/bar.U when you are ready ...
+(l) git add U/foo/bar.U when you are ready ...
 
 (m) git commit -m "Your commit description"