This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
-Duserelocatableinc and -Duseshrplib don't work together
[metaconfig.git] / README
CommitLineData
e00c5fdc 1 Jarkko's How to build Configure tweaked by Nick and Merijn.
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.
e00c5fdc
MB
34 dist-3.5-20:
35 dist-3.5-20 is almost meta-4.0, still maintained by Raphael
36 Manfredi, but with a lot of fixes over 3.0, some changes
37 from the perl modifications merged and a much better metalint
38 dist:
39 a symlink to the lib you actually use. For Merijn that is
40 metaconfig/dist -> ../lib/dist
2eb0fc7c 41
13b7c768
NIS
42(a) You need to have dist installed so that you have metalint and metaconfig
43 in your $PATH.
e00c5fdc
MB
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 the SVN
46 repository https://dist.svn.sourceforge.net/svnroot/dist/trunk
13b7c768
NIS
47 Unsurprisingly 'dist' uses (its) Configure to generate itself:
48
e00c5fdc 49 cd dist-3.5-20
b15dd5ec 50 chmod -R +w . # We have derived files in perforce :-(
13b7c768
NIS
51 ./Configure
52 make
53 make install
54
e00c5fdc
MB
55 After make install, remove lib/U/d_debugging.U in your target lib, as perl
56 uses it's own way to set/define debugging (see INSTALL)
57
58 the dist-3.5-20 installation as used by Merijn is available on his CPAN as
59 perl-meta-3.5-20.tgz
60
61 dist's 'Configure' is similar to perl's but perhaps not quite as polished.
13b7c768
NIS
62
63 There are some perl specific "dist units" in the 'U' directory.
e00c5fdc
MB
64 The U directory also contains some patches to 'dist' which have already
65 been applied to dist-3.5-20 directory.
66 We have not yet arranged for metaconfig to use perl's versions of the
67 'units' by default so you need some housekeeping in the perl directory...
68
69(b) You need to be in a/the Perl directory, i.e. either something from
70 //depot/perl/... or one of its branches
13b7c768
NIS
71 (e.g. Nick I-S is usually in //depot/perlio/...)
72 and you need:
73 1) have a symlink to ../metaconfig/U called U
74 2) have a symlink to ../metaconfig/.package called .package
75 3) have a symlink to MANIFEST called MANIFEST.new
2eb0fc7c 76 4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
13b7c768
NIS
77
78(c) Write the new unit as U/foo/bar.U (usually 'foo' is just 'perl',
2eb0fc7c
MB
79 but sometimes there's some more appropriate subdir of U. See
80 U/README for a description of the various subdirectories.)
13b7c768 81
2eb0fc7c 82(d) Run metalint to see nits: as opposed to lint, the gripings of
13b7c768
NIS
83 metalint are usually serious :-) and need fixing
84
85 Exceptions are lots of
86 Your private U/modified/voidflags.U overrides the public one.
87 due to the perl special units
88
e00c5fdc
MB
89 an alias to something like
90 $ metalint |& grep -v -e '^ Your private U/'
91 will make the process silence up on that
92
13b7c768
NIS
93 and
94
95 "End.U": stale ?MAKE: dependency '$W'.
96
97 which is apparently normal ...
98
99(e) p4 edit Configure config_h.SH
100
101(f) metaconfig -m to regenerate Configure
102
b15dd5ec
MB
103(g) metaconfig does not deal with depends in config_h.SH, so some
104 reorganization is needed.
105
106 perl Porting/config_h.SH
107
108 will fix the ordering
109
110(h) The messy not-yet-automated part is that the knowledge of the new symbol
974341ad
JH
111 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
112 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
113 heathen lands. Files to take care of are
114 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
115 configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
116 epoc/config.sh (EPOC). Depending on the kind of patch djgpp/config*
117 might also need adjusting (for example when adding/changing the list
118 of extensions)
13b7c768
NIS
119
120 For Win32 the process is semi-automated - if you have a Win32
121 machine to run dmake on ...
122
b15dd5ec 123(i) Edit U/mkglossary (right near the top) to point to where you keep
2eb0fc7c 124 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 125
b15dd5ec 126(j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
2eb0fc7c
MB
127 Adjust the various compile-time options (e.g. 64bit, threads) as
128 you see fit.
129 You can skip this phase, it's not essential, just good housekeeping.
13b7c768 130
b15dd5ec 131(k) make veryclean;sh Configure -des -Dusedevel;make all test
13b7c768 132
b15dd5ec 133(l) p4 add ../metaconfig/foo/bar.U when you are ready ...
13b7c768 134
b15dd5ec 135(m) p4 submit
15b97373
MB
136 IF your $EDITOR and/or $VISUAL start a background edit session
137 ('elvis -fork' or 'gvim'), be sure to set $P4EDITOR to an
138 editor call that is waited for.