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 building 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.5-20:
  26                 dist-3.5-20 is almost meta-4.0, still maintained by Raphael
  27                 Manfredi, but with a lot of fixes over 3.0, some changes
  28                 from the perl modifications merged and a much better
  29                 metalint. This directory comes from a tar distribution.
  30     dist-svn:
  31                 a git clone of "dist". Optionally present. See (a) below.
  32     dist:
  33                 a symlink to the lib you actually use. For Merijn that is
  34                 metaconfig/dist -> ../lib/dist
  35
  36 (a) You need to have dist installed so that you have metalint and metaconfig
  37     in your $PATH.
  38     The dist version used for perl is dist-3.5-20 in this directory, which is
  39     a slightly modified version of the original, which you can get at the SVN
  40     repository https://svn.code.sf.net/p/dist/code/trunk/dist. If you'd like
  41     to keep up to date with changes in dist, you can either use svn or git to
  42     create your own clone. For git, that would be something like:
  43
  44     $ git svn clone \
  45       svn://svn.code.sf.net/p/dist/code/trunk/dist \
  46       dist-svn
  47
  48     Unsurprisingly 'dist' uses (its) Configure to generate itself:
  49
  50     $ cd dist-3.5-20    # or dist-svn
  51     $ chmod -R +w .     # We have derived files in git :-(
  52     $ ./Configure
  53     $ make
  54     $ make install
  55
  56     After make install, remove lib/U/d_debugging.U in your target lib, as perl
  57     uses its own way to set/define debugging (see INSTALL)
  58
  59     the dist-3.5-20 installation as used by Merijn is available on his CPAN as
  60     perl-meta-3.5-20.tgz
  61
  62     dist's 'Configure' is similar to perl's but perhaps not quite as polished.
  63
  64     There are some perl specific "dist units" in the 'U' directory.
  65     The U directory also contains some patches to 'dist' which have already
  66     been applied to dist-3.5-20 directory.
  67     We have not yet arranged for metaconfig to use perl's versions of the
  68     'units' by default so you need some housekeeping in the perl directory...
  69
  70 (aa)  -- optional --
  71
  72     If you plan to make changes to metaconfig or metalint locally (and you
  73     probably want to, as both are written for perl4), consider installing
  74     mconfig and mlint from the cmon subdirectory into your $PATH too. These
  75     are the non-autoloading versions and can easily be changed. Here is what
  76     I added at the beginning of mconfig:
  77
  78     --8<---
  79     BEGIN { $ENV{LC_ALL} = "C"; }
  80     chdir "/pro/3gl/CPAN/perl";
  81     {   my @Cc = qw( Configure config_h.SH );
  82         system "chown merijn @Cc";
  83         chmod 0775, @Cc;
  84         #-d "merijn" or mkdir "merijn";
  85         #system "cp -f Configure config_h.SH Porting/Glossary Porting/config.sh merijn/";
  86         system "ls", "-l", @Cc;
  87         }
  88     -->8---
  89
  90     I also added the first two lines of that patch to mlint
  91
  92 (b) You need to be in a/the Perl directory, i.e. either something from
  93     //depot/perl/... or one of its branches
  94     (e.g. Nick I-S is usually in //depot/perlio/...)
  95     and you need:
  96      1) have a symlink to ../metaconfig/U called U
  97      2) have a symlink to ../metaconfig/.package called .package
  98      3) have a symlink to MANIFEST called MANIFEST.new
  99      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
 100
 101 (c) Write the new unit as U/perl/d_bar.U ('perl' can also be 'modified',
 102     'compline' or any other existing folder, except for 'all'). Choose
 103     the best appropriate subdir of U.  See U/README for a description of
 104     the various subdirectories.)
 105
 106 (d) Run metalint (or mlint) to see nits: as opposed to lint, the gripings
 107     of metalint are usually serious :-) and need fixing
 108
 109     Exceptions are lots of
 110       Your private U/modified/issymlink.U overrides the public one.
 111     due to the perl special units
 112
 113     an alias to something like
 114     $ metalint      |& grep -v -e '^    Your private U/'
 115     will make the process silence up on that (of course you can add an
 116     option to mlint to disable that warning (which is already disabled
 117     by the undocumented and forgotten -s option, but that also suppresses
 118     other warnings)
 119
 120     and
 121
 122     "End.U": stale ?MAKE: dependency '$W'.
 123
 124     which is apparently normal ...
 125
 126 -- the next steps are in the perl folder
 127
 128 (e) chmod +w Configure config_h.SH
 129
 130 (f) metaconfig -m to regenerate Configure (or mconfig -m)
 131
 132 (g) metaconfig does not deal with depends in config_h.SH, so some
 133     reorganization is needed.
 134
 135     perl Porting/config_h.SH
 136
 137     will fix the ordering
 138
 139 (h) The messy not-yet-automated part is that the knowledge of the new symbol
 140     needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
 141     VMS, VOS, EPOC, ...  see previous Configure changes to see which are these
 142     heathen lands.  Files to take care of are
 143     {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
 144     configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
 145     epoc/config.sh (EPOC).  Depending on the kind of patch djgpp/config*
 146     might also need adjusting (for example when adding/changing the list
 147     of extensions)
 148
 149     For Win32 the process is semi-automated - if you have a Win32
 150     machine to run dmake on ...
 151
 152 (i) Edit U/mkglossary (right near the top) to point to where you keep
 153     dist's standard metaconfig units as well as your perl-specific ones.
 154
 155 (j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
 156     Adjust the various compile-time options (e.g. 64bit, threads) as
 157     you see fit.
 158     You can skip this phase, it's not essential, just good housekeeping.
 159
 160 (k) Run the perl build chain
 161
 162     make veryclean
 163     sh ./Configure -des -Dusedevel
 164
 165     The dependency for uconfig.h isn't carved in stone, so you might
 166     need to regenerate it
 167
 168     perl regen/uconfig_h.pl
 169
 170     Then make and make test or make test_harness (with TEST_JOBS=5)
 171
 172     make all test_harness
 173
 174     Before you start committing, make sure that the other developers
 175     are happy and run
 176
 177     make test_porting
 178
 179 -- the next steps are in the metaconfig folder again
 180
 181 (l) git add U/perl/foo/bar.U when you are ready ...
 182
 183 (m) git commit -m "Your commit description"
 184
 185 (n) When all patches are applied, tested and committed, and you are happy,
 186     git push
 187
 188     Merijn prefers to do steps (l) through (n) in git-gui