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 86d88c7..3497d96 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-       Jarrko'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 
 
 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.
 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
 
 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.
 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.
     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.
 
 (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:
 
     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.
 
     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
     (e.g. Nick I-S is usually in //depot/perlio/...)
     and you need:
      1) have a symlink to ../metaconfig/U called U
@@ -62,48 +98,91 @@ Contents of this directory:
      3) have a symlink to MANIFEST called MANIFEST.new
      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
 
      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
 
     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
 
     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 ...
 
     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
-    needs to be propagated to non-Configure lands like Win32, Netware,
-    VMS, VOS, ...  see previous Configure changes to see which are these
-    heathen lands
+    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
+    {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
+    configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
+    epoc/config.sh (EPOC).  Depending on the kind of patch djgpp/config*
+    might also need adjusting (for example when adding/changing the list
+    of extensions)
 
     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 ...
 
-(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.
 
     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.
 
     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