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