README

   1         Jarkko's How to build Configure tweaked by Nick.
   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
  35 (a) You need to have dist installed so that you have metalint and metaconfig
  36     in your $PATH.
  37     The dist version used for perl is dist-3.0at70b in this directory.
  38     Unsurprisingly 'dist' uses (its) Configure to generate itself:
  39
  40     cd dist-3.0at70b
  41     chmod -R +w .     # We have derived files in perforce :-(
  42     ./Configure
  43     make
  44     make install
  45
  46     dist's 'Configure' is similar to perl's but perhaps not
  47     quite as polished.
  48
  49     There are some perl specific "dist units" in the 'U' directory.
  50     The U directory also contains some patches to 'dist' which
  51     have already been applied to dist-3.0at70b directory.
  52     We have not yet arranged for metaconfig to use perl's versions
  53     of the 'units' by default so you need some housekeeping
  54     in the perl directory...
  55
  56 (b) You need to be in a/the Perl directory, i.e. either
  57     something from //depot/perl/... or one of its branches
  58     (e.g. Nick I-S is usually in //depot/perlio/...)
  59     and you need:
  60      1) have a symlink to ../metaconfig/U called U
  61      2) have a symlink to ../metaconfig/.package called .package
  62      3) have a symlink to MANIFEST called MANIFEST.new
  63      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
  64
  65 (c) Write the new unit as U/foo/bar.U (usually 'foo' is just 'perl',
  66     but sometimes there's some more appropriate subdir of U.  See
  67     U/README for a description of the various subdirectories.)
  68
  69 (d) Run metalint to see nits: as opposed to lint, the gripings of
  70     metalint are usually serious :-) and need fixing
  71
  72     Exceptions are lots of
  73       Your private U/modified/voidflags.U overrides the public one.
  74     due to the perl special units
  75
  76     and
  77
  78     "End.U": stale ?MAKE: dependency '$W'.
  79
  80     which is apparently normal ...
  81
  82 (e) p4 edit Configure config_h.SH
  83
  84 (f) metaconfig -m to regenerate Configure
  85
  86 (g) metaconfig does not deal with depends in config_h.SH, so some
  87     reorganization is needed.
  88
  89     perl Porting/config_h.SH
  90
  91     will fix the ordering
  92
  93 (h) The messy not-yet-automated part is that the knowledge of the new symbol
  94     needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
  95     VMS, VOS, EPOC, ...  see previous Configure changes to see which are these
  96     heathen lands.  Files to take care of are
  97     {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
  98     configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
  99     epoc/config.sh (EPOC).  Depending on the kind of patch djgpp/config*
 100     might also need adjusting (for example when adding/changing the list
 101     of extensions)
 102
 103     For Win32 the process is semi-automated - if you have a Win32
 104     machine to run dmake on ...
 105
 106 (i) Edit U/mkglossary (right near the top) to point to where you keep
 107     dist's standard metaconfig units as well as your perl-specific ones.
 108
 109 (j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
 110     Adjust the various compile-time options (e.g. 64bit, threads) as
 111     you see fit.
 112     You can skip this phase, it's not essential, just good housekeeping.
 113
 114 (k) make veryclean;sh Configure -des -Dusedevel;make all test
 115
 116 (l) p4 add ../metaconfig/foo/bar.U when you are ready ...
 117
 118 (m) p4 submit
 119     IF your $EDITOR and/or $VISUAL start a background edit session
 120     ('elvis -fork' or 'gvim'), be sure to set $P4EDITOR to an
 121     editor call that is waited for.