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