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.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.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. 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 \
      http://dist.svn.sourceforge.net/svnroot/dist/trunk/dist \
      dist-svn

    Unsurprisingly 'dist' uses (its) Configure to generate itself:

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