whitespace consistency

[metaconfig.git] / README

diff --git a/README b/README
index 35cae4a..248f88c 100644 (file)
--- a/README
+++ b/README
@@ -35,8 +35,6 @@ Contents of this directory:
 
     README:    This file.
     U:         Metaconfig units used for building Perl's Configure
-    U.check:   Sample directory used for testing new metaconfig units.
-               see U.check/README for more information.
     dist-git:
                a git clone of "dist". Optionally present. See (a) below.
                This is where dist/meta resides as of 2016-04-01
@@ -45,9 +43,15 @@ Contents of this directory:
                These may differ from dist-git, as upstream also moves
                on and develops.
 
-(a) You need to have dist installed so that you have metalint and metaconfig
-    in your $PATH. As dist/meta binaries are now included in the git checkout,
-    you do NOT need to install dist/meta itself.
+Development workflow:
+
+(a) In order to assemble Configure from its units, you need mlint/metaline and
+    mconfig/metaconfig from the "dist" package installed and available in your
+    $PATH. You can either use the version that comes with your OS (Debian ships
+    it) or the versions that are included in this checkout: just add the full
+    name of this folder/bin to your $PATH. If you are not planning to analyse
+    differences of the current state with upstream dist, you can skip the rest
+    op step (a) now.
 
     If you also want to play with or compare to the original meta/dist, you
     can checkout that too.
@@ -84,7 +88,7 @@ Contents of this directory:
 
     $ export MC5=/your/path/to/metaconfig
     $ alias ml="perl $MC5/bin/mlint -O"
-    $ alias mc="perl $MC5/bin/mconfig -m -O"
+    $ alias mc="perl $MC5/bin/mconfig -m -O -X .metaconf-exclusions.txt"
 
     examples in the rest of this README will just refer to mlint and mconfig
     as if they appear in your $PATH
@@ -140,7 +144,8 @@ Contents of this directory:
     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   # regenerate Configure and config_h.SH
+(f) "mconfig -m -O -X .metaconf-exclusions.txt" to regenerate Configure and
+    config_h.SH
 
     Make *sure* your mconfig is the correct one in your $PATH, as the mono-web
     package will install /usr/bin/mconfig which will do something completely
@@ -165,17 +170,22 @@ Contents of this directory:
 
     Most can be checked and updated by a tool Nicholas provided:
 
-    $ cd perl
-    $ perl Porting/checkcfgvar.pl
+      $ cd perl
+      $ perl Porting/checkcfgvar.pl
 
-    and if it shows differences,
+    and if it shows differences, use one of:
 
-    $ perl Porting/checkcfgvar.pl --regen --default=define
+      $ perl Porting/checkcfgvar.pl --regen --default=undef
+      $ perl Porting/checkcfgvar.pl --regen --default=define
 
-    (of course "define" can also be "undef" based on the changes you made
+    based on the changes you made.  For safety, probes should probably be
+    'undef', whereas some other things unconditionally should default to
+    'define'.  For example, 'default_inc_excludes_dot' should be 'define'
+    except in very limited circumstances, because it closes a security hole.
 
-    For Win32 the process is semi-automated -- if you have a Win32
-    machine to run dmake on
+    For Win32 the process is semi-automated.  You have to have a Win32
+    machine to run dmake on to complete the process, but that can be done
+    later by someone with such access.
 
     For VMS, ('configure.com'), it may be best to add the units as 'undef' and
     let the VMS experts deal with them later.  However, you can set them to
@@ -209,12 +219,11 @@ Contents of this directory:
     $ make -j12
     $ env TEST_JOBS=13 make test_harness
 
-    Before you start committing, make sure that the other developers
-    are happy and run
+    Before you start committing, make sure that
 
     $ make test_porting
 
-    again
+    still passes
 
 (k) Optionally, run Porting/mksample to freshen the Porting/config*.
     Adjust the various compile-time options (e.g. 64bit, threads) as
@@ -246,6 +255,19 @@ Contents of this directory:
 (n) When all patches are applied, tested and committed, and you are happy,
     git push
 
-(o) Documentation on 'dist' may be found at these locations:
-    https://github.com/rmanfredi/dist/blob/master/mcon/man/mconfig.SH
-    https://manpages.debian.org/stretch/dist/metaconfig.1.en.html
+References:
+
+Documentation on 'dist' may be found at these locations:
+https://github.com/rmanfredi/dist/blob/master/mcon/man/mconfig.SH
+https://manpages.debian.org/stretch/dist/metaconfig.1.en.html
+
+Git tags:
+
+Tags are maintained in this git repository mapping the version of the
+units that were used for the Configure in a given release of perl,
+named simply after the version of perl in question (for example, at
+the time of writing the current stable release is 5.26.1). This provides
+a stable reference for downstreams wishing to import the metaconfig units
+into their own packaging. Therefore, at minimum tags for each stable
+release should be made (adding tags for development releases being an
+optional extra).