This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Backport #24508
[metaconfig.git] / README
CommitLineData
974341ad 1 Jarkko's How to build Configure tweaked by Nick.
2eb0fc7c
MB
2
3The Configure script and config_h.SH file in the Perl distribution are
4generated by a program called metaconfig. Metaconfig was originally
5written by Larry Wall, and was subsequently enhanced and maintained
6by Raphael Manfredi.
13b7c768
NIS
7
8You have presumably obtained the metaconfig from the repository e.g.
2eb0fc7c
MB
9 p4 sync //depot/metaconfig/...
10(those are three literal dots) or some other way to obtain this file,
11like a complete compressed archive from the previous pumpkin.
13b7c768
NIS
12
13Normally this directory and perl directory are next to each other
14so ../perl will get you to perl and ../perl/../metaconfig will get you
15back here.
16
2eb0fc7c
MB
17Contents 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
13b7c768
NIS
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 +w -R . # 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
2eb0fc7c 63 4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
13b7c768
NIS
64
65(c) Write the new unit as U/foo/bar.U (usually 'foo' is just 'perl',
2eb0fc7c
MB
66 but sometimes there's some more appropriate subdir of U. See
67 U/README for a description of the various subdirectories.)
13b7c768 68
2eb0fc7c 69(d) Run metalint to see nits: as opposed to lint, the gripings of
13b7c768
NIS
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) The messy not-yet-automated part is that the knowledge of the new symbol
974341ad
JH
87 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
88 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
89 heathen lands. Files to take care of are
90 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
91 configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
92 epoc/config.sh (EPOC). Depending on the kind of patch djgpp/config*
93 might also need adjusting (for example when adding/changing the list
94 of extensions)
13b7c768
NIS
95
96 For Win32 the process is semi-automated - if you have a Win32
97 machine to run dmake on ...
98
2eb0fc7c
MB
99(h) Edit U/mkglossary (right near the top) to point to where you keep
100 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 101
2eb0fc7c
MB
102(i) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
103 Adjust the various compile-time options (e.g. 64bit, threads) as
104 you see fit.
105 You can skip this phase, it's not essential, just good housekeeping.
13b7c768 106
2eb0fc7c 107(j) make veryclean;sh Configure -des -Dusedevel;make all test
13b7c768 108
2eb0fc7c 109(k) p4 add ../metaconfig/foo/bar.U when you are ready ...
13b7c768 110
2eb0fc7c 111(l) p4 submit
15b97373
MB
112 IF your $EDITOR and/or $VISUAL start a background edit session
113 ('elvis -fork' or 'gvim'), be sure to set $P4EDITOR to an
114 editor call that is waited for.