This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
uname -r works on MINIX as well
[metaconfig.git] / README
diff --git a/README b/README
index c349192..3497d96 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-       Jarkko's How to build Configure tweaked by Nick.
+       Jarkko's How to build Configure tweaked by Nick and Merijn.
 
 The Configure script and config_h.SH file in the Perl distribution are
 generated by a program called metaconfig.  Metaconfig was originally 
@@ -6,9 +6,11 @@ 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/...
-(those are three literal dots) or some other way to obtain this file,
-like a complete compressed archive from the previous pumpkin.
+
+  $ git clone git://perl5.git.perl.org/metaconfig.git metaconfig
+
+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
@@ -17,44 +19,78 @@ back here.
 Contents of this directory:
 
     README:    This file.
-    U:         Metaconfig units used for buliding Perl's Configure
+    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-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.
+    dist-3.5-20:
+               dist-3.5-20 is almost meta-4.0, still maintained by Raphael
+               Manfredi, but with a lot of fixes over 3.0, some changes
+               from the perl modifications merged and a much better
+               metalint. This directory comes from a tar distribution.
+    dist-svn:
+               a git clone of "dist". Optionally present. See (a) below.
+    dist:
+               a symlink to the lib you actually use. For Merijn that is
+               metaconfig/dist -> ../lib/dist
 
 (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.
+    The dist version used for perl is dist-3.5-20 in this directory, which is
+    a slightly modified version of the original, which you can get at the SVN
+    repository https://svn.code.sf.net/p/dist/code/trunk/dist. If you'd like
+    to keep up to date with changes in dist, you can either use svn or git to
+    create your own clone. For git, that would be something like:
+
+    $ git svn clone \
+      svn://svn.code.sf.net/p/dist/code/trunk/dist \
+      dist-svn
+
     Unsurprisingly 'dist' uses (its) Configure to generate itself:
 
-    cd dist-3.0at70b
-    chmod +w -R .     # We have derived files in perforce :-(
-    ./Configure
-    make
-    make install
+    $ cd dist-3.5-20   # or dist-svn
+    $ chmod -R +w .     # We have derived files in git :-(
+    $ ./Configure
+    $ make
+    $ make install
+
+    After make install, remove lib/U/d_debugging.U in your target lib, as perl
+    uses its own way to set/define debugging (see INSTALL)
 
-    dist's 'Configure' is similar to perl's but perhaps not
-    quite as polished.
+    the dist-3.5-20 installation as used by Merijn is available on his CPAN as
+    perl-meta-3.5-20.tgz
+
+    dist's 'Configure' is similar to perl's but perhaps not quite as polished.
 
     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.0at70b directory.
-    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...
-
-(b) You need to be in a/the Perl directory, i.e. either
-    something from //depot/perl/... or one of its branches
+    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
+    'units' by default so you need some housekeeping in the perl directory...
+
+(aa)  -- optional --
+
+    If you plan to make changes to metaconfig or metalint locally (and you
+    probably want to, as both are written for perl4), consider installing
+    mconfig and mlint from the cmon subdirectory into your $PATH too. These
+    are the non-autoloading versions and can easily be changed. Here is what
+    I added at the beginning of mconfig:
+
+    --8<---
+    BEGIN { $ENV{LC_ALL} = "C"; }
+    chdir "/pro/3gl/CPAN/perl";
+    {   my @Cc = qw( Configure config_h.SH );
+       system "chown merijn @Cc";
+       chmod 0775, @Cc;
+       #-d "merijn" or mkdir "merijn";
+       #system "cp -f Configure config_h.SH Porting/Glossary Porting/config.sh merijn/";
+       system "ls", "-l", @Cc;
+       }
+    -->8---
+
+    I also added the first two lines of that patch to mlint
+
+(b) You need to be in a/the Perl directory, i.e. either something from
+    //depot/perl/... or one of its branches
     (e.g. Nick I-S is usually in //depot/perlio/...)
     and you need:
      1) have a symlink to ../metaconfig/U called U
@@ -62,28 +98,45 @@ Contents of this directory:
      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.  See
-    U/README for a description of the various subdirectories.)
+(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.)
 
-(d) Run metalint to see nits: as opposed to lint, the gripings of
-    metalint are usually serious :-) and need fixing
+(d) Run metalint (or mlint) to see nits: as opposed to lint, the gripings
+    of metalint are usually serious :-) and need fixing
 
     Exceptions are lots of
-      Your private U/modified/voidflags.U overrides the public one.
+      Your private U/modified/issymlink.U overrides the public one.
     due to the perl special units
 
+    an alias to something like
+    $ metalint      |& grep -v -e '^    Your private U/'
+    will make the process silence up on that (of course you can add an
+    option to mlint to disable that warning (which is already disabled
+    by the undocumented and forgotten -s option, but that also suppresses
+    other warnings)
+
     and
 
     "End.U": stale ?MAKE: dependency '$W'.
 
     which is apparently normal ...
 
-(e) p4 edit Configure config_h.SH
+-- the next steps are in the perl folder
+
+(e) chmod +w Configure config_h.SH
+
+(f) metaconfig -m to regenerate Configure (or mconfig -m)
+
+(g) metaconfig does not deal with depends in config_h.SH, so some
+    reorganization is needed.
 
-(f) metaconfig -m to regenerate Configure
+    perl Porting/config_h.SH
 
-(g) The messy not-yet-automated part is that the knowledge of the new symbol
+    will fix the ordering
+    
+(h) The messy not-yet-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
     heathen lands.  Files to take care of are
@@ -96,19 +149,40 @@ Contents of this directory:
     For Win32 the process is semi-automated - if you have a Win32
     machine to run dmake on ...
 
-(h) Edit U/mkglossary (right near the top) to point to where you keep
+(i) 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.
 
-(i) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
+(j) 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.
 
-(j) make veryclean;sh Configure -des -Dusedevel;make all test
+(k) Run the perl build chain
+
+    make veryclean
+    sh ./Configure -des -Dusedevel
+
+    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 (with TEST_JOBS=5)
+
+    make all test_harness
+
+    Before you start committing, make sure that the other developers
+    are happy and run
+
+    make test_porting
+
+-- the next steps are in the metaconfig folder again
+
+(l) git add U/perl/foo/bar.U when you are ready ...
+
+(m) git commit -m "Your commit description"
 
-(k) p4 add ../metaconfig/foo/bar.U when you are ready ...
+(n) When all patches are applied, tested and committed, and you are happy,
+    git push
 
-(l) p4 submit
-    IF your $EDITOR and/or $VISUAL start a background edit session
-    ('elvis -fork' or 'gvim'), be sure to set $P4EDITOR to an
-    editor call that is waited for.
+    Merijn prefers to do steps (l) through (n) in git-gui