README

   1         Jarkko's How to build Configure tweaked by Nick and Merijn.
   2
   3 The Configure script and config_h.SH file in the Perl distribution are
   4 generated by a program called metaconfig.  Metaconfig was originally
   5 written by Larry Wall, and was subsequently enhanced and maintained
   6 by Raphael Manfredi.
   7
   8 You have presumably obtained the metaconfig from the repository e.g.
   9   p4 sync //depot/metaconfig/...
  10 (those are three literal dots) or some other way to obtain this file,
  11 like a complete compressed archive from the previous pumpkin.
  12
  13 Normally this directory and perl directory are next to each other
  14 so ../perl will get you to perl and ../perl/../metaconfig will get you
  15 back here.
  16
  17 Contents of this directory:
  18
  19     README:     This file.
  20     U:          Metaconfig units used for buliding Perl's Configure
  21     U.check:    Sample directory used for testing new metaconfig units.
  22                 see U.check/README for more information.
  23     dist-3.0at70:
  24                 dist-3.0 at patchlevel 70.  This is the final version released
  25                 by Raphael Manfredi.  Don't use it.  Instead, use ...
  26     dist-3.0at70b:
  27                 dist-3.0 at patchlevel 70 with unofficial patches 'a' and 'b'
  28                 applied.  This version was never officially released, but
  29                 the patches are essential, so this is the version we use for
  30                 perl.  Actually, I've also applied U/dist_patches/dist-p70c
  31                 to this tree.  If someone with perforce access wants to change
  32                 the name of the directory, that'd be fine.  Otherwise, it really
  33                 doesn't matter.
  34     dist-3.5-20:
  35                 dist-3.5-20 is almost meta-4.0, still maintained by Raphael
  36                 Manfredi, but with a lot of fixes over 3.0, some changes
  37                 from the perl modifications merged and a much better metalint
  38     dist:
  39                 a symlink to the lib you actually use. For Merijn that is
  40                 metaconfig/dist -> ../lib/dist
  41
  42 (a) You need to have dist installed so that you have metalint and metaconfig
  43     in your $PATH.
  44     The dist version used for perl is dist-3.5-20 in this directory, which is
  45     a slightly modified version of the original, which you can get at the SVN
  46     repository https://dist.svn.sourceforge.net/svnroot/dist/trunk
  47     Unsurprisingly 'dist' uses (its) Configure to generate itself:
  48
  49     cd dist-3.5-20
  50     chmod -R +w .     # We have derived files in perforce :-(
  51     ./Configure
  52     make
  53     make install
  54
  55     After make install, remove lib/U/d_debugging.U in your target lib, as perl
  56     uses it's own way to set/define debugging (see INSTALL)
  57
  58     the dist-3.5-20 installation as used by Merijn is available on his CPAN as
  59     perl-meta-3.5-20.tgz
  60
  61     dist's 'Configure' is similar to perl's but perhaps not quite as polished.
  62
  63     There are some perl specific "dist units" in the 'U' directory.
  64     The U directory also contains some patches to 'dist' which have already
  65     been applied to dist-3.5-20 directory.
  66     We have not yet arranged for metaconfig to use perl's versions of the
  67     'units' by default so you need some housekeeping in the perl directory...
  68
  69 (b) You need to be in a/the Perl directory, i.e. either something from
  70     //depot/perl/... or one of its branches
  71     (e.g. Nick I-S is usually in //depot/perlio/...)
  72     and you need:
  73      1) have a symlink to ../metaconfig/U called U
  74      2) have a symlink to ../metaconfig/.package called .package
  75      3) have a symlink to MANIFEST called MANIFEST.new
  76      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
  77
  78 (c) Write the new unit as U/foo/bar.U (usually 'foo' is just 'perl',
  79     but sometimes there's some more appropriate subdir of U.  See
  80     U/README for a description of the various subdirectories.)
  81
  82 (d) Run metalint to see nits: as opposed to lint, the gripings of
  83     metalint are usually serious :-) and need fixing
  84
  85     Exceptions are lots of
  86       Your private U/modified/voidflags.U overrides the public one.
  87     due to the perl special units
  88
  89     an alias to something like
  90     $ metalint      |& grep -v -e '^    Your private U/'
  91     will make the process silence up on that
  92
  93     and
  94
  95     "End.U": stale ?MAKE: dependency '$W'.
  96
  97     which is apparently normal ...
  98
  99 (e) p4 edit Configure config_h.SH
 100
 101 (f) metaconfig -m to regenerate Configure
 102
 103 (g) metaconfig does not deal with depends in config_h.SH, so some
 104     reorganization is needed.
 105
 106     perl Porting/config_h.SH
 107
 108     will fix the ordering
 109
 110 (h) The messy not-yet-automated part is that the knowledge of the new symbol
 111     needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
 112     VMS, VOS, EPOC, ...  see previous Configure changes to see which are these
 113     heathen lands.  Files to take care of are
 114     {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
 115     configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
 116     epoc/config.sh (EPOC).  Depending on the kind of patch djgpp/config*
 117     might also need adjusting (for example when adding/changing the list
 118     of extensions)
 119
 120     For Win32 the process is semi-automated - if you have a Win32
 121     machine to run dmake on ...
 122
 123 (i) Edit U/mkglossary (right near the top) to point to where you keep
 124     dist's standard metaconfig units as well as your perl-specific ones.
 125
 126 (j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
 127     Adjust the various compile-time options (e.g. 64bit, threads) as
 128     you see fit.
 129     You can skip this phase, it's not essential, just good housekeeping.
 130
 131 (k) make veryclean;sh Configure -des -Dusedevel;make all test
 132
 133 (l) p4 add ../metaconfig/foo/bar.U when you are ready ...
 134
 135 (m) p4 submit
 136     IF your $EDITOR and/or $VISUAL start a background edit session
 137     ('elvis -fork' or 'gvim'), be sure to set $P4EDITOR to an
 138     editor call that is waited for.