github / metaconfig mirrored from git://perl5.git.perl.org/metaconfig.git

  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 
written by Larry Wall, and was subsequently enhanced and maintained
by Raphael Manfredi.

You have presumably obtained the metaconfig from the repository e.g.

  $ 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
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 commit power 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
    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.5-20 in this directory, which is
    a slightly modified version of the original, which you can get at the SVN
    repository https://dist.svn.sourceforge.net/svnroot/dist/trunk
    Unsurprisingly 'dist' uses (its) Configure to generate itself:

    cd dist-3.5-20
    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 it's own way to set/define debugging (see INSTALL)

    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.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...

(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
     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.)

(d) Run metalint 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.
    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

    and

    "End.U": stale ?MAKE: dependency '$W'.

    which is apparently normal ...

-- the next steps are in the perl folder

(e) chmod +w Configure config_h.SH

(f) metaconfig -m to regenerate Configure

(g) metaconfig does not deal with depends in config_h.SH, so some
    reorganization is needed.

    perl Porting/config_h.SH

    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 ...

(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.

(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.

(k) make veryclean; sh Configure -des -Dusedevel; make all test

-- 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"

(n) When all patches are applied, tested and committed, and you are happy,
    git push

    Merijn prefers to do steps (l) through (n) in git-gui