This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fix from dist-svn
[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.
6475898c
MB
9
10 $ git clone git://perl5.git.perl.org/metaconfig.git metaconfig
11
12or some other way to obtain this file, like a complete compressed archive
13from the previous pumpkin.
13b7c768
NIS
14
15Normally this directory and perl directory are next to each other
16so ../perl will get you to perl and ../perl/../metaconfig will get you
17back here.
18
2eb0fc7c
MB
19Contents 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.
e00c5fdc
MB
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
1e695180
MB
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.
e00c5fdc
MB
32 dist:
33 a symlink to the lib you actually use. For Merijn that is
34 metaconfig/dist -> ../lib/dist
2eb0fc7c 35
13b7c768
NIS
36(a) You need to have dist installed so that you have metalint and metaconfig
37 in your $PATH.
e00c5fdc
MB
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
1e695180
MB
40 repository https://dist.svn.sourceforge.net/svnroot/dist/trunk. If you'd
41 like to keep up to date with changes in dist, you can either use svn or
42 git to create your own clone. For git, that would be something like:
43
44 $ git svn clone \
45 http://dist.svn.sourceforge.net/svnroot/dist/trunk/dist \
46 dist-svn
47
13b7c768
NIS
48 Unsurprisingly 'dist' uses (its) Configure to generate itself:
49
1e695180
MB
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
13b7c768 55
e00c5fdc
MB
56 After make install, remove lib/U/d_debugging.U in your target lib, as perl
57 uses it's 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.
13b7c768
NIS
63
64 There are some perl specific "dist units" in the 'U' directory.
e00c5fdc
MB
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(b) You need to be in a/the Perl directory, i.e. either something from
71 //depot/perl/... or one of its branches
13b7c768
NIS
72 (e.g. Nick I-S is usually in //depot/perlio/...)
73 and you need:
74 1) have a symlink to ../metaconfig/U called U
75 2) have a symlink to ../metaconfig/.package called .package
76 3) have a symlink to MANIFEST called MANIFEST.new
2eb0fc7c 77 4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
13b7c768 78
6475898c
MB
79(c) Write the new unit as U/perl/d_bar.U ('perl' can also be 'modified',
80 'compline' or any other existing folder, except for 'all'). Choose
81 the best appropriate subdir of U. See U/README for a description of
82 the various subdirectories.)
13b7c768 83
2eb0fc7c 84(d) Run metalint to see nits: as opposed to lint, the gripings of
13b7c768
NIS
85 metalint are usually serious :-) and need fixing
86
87 Exceptions are lots of
88 Your private U/modified/voidflags.U overrides the public one.
89 due to the perl special units
90
e00c5fdc
MB
91 an alias to something like
92 $ metalint |& grep -v -e '^ Your private U/'
93 will make the process silence up on that
94
13b7c768
NIS
95 and
96
97 "End.U": stale ?MAKE: dependency '$W'.
98
99 which is apparently normal ...
100
6475898c
MB
101-- the next steps are in the perl folder
102
103(e) chmod +w Configure config_h.SH
13b7c768
NIS
104
105(f) metaconfig -m to regenerate Configure
106
b15dd5ec
MB
107(g) metaconfig does not deal with depends in config_h.SH, so some
108 reorganization is needed.
109
110 perl Porting/config_h.SH
111
112 will fix the ordering
113
114(h) The messy not-yet-automated part is that the knowledge of the new symbol
974341ad
JH
115 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
116 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
117 heathen lands. Files to take care of are
118 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
119 configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
120 epoc/config.sh (EPOC). Depending on the kind of patch djgpp/config*
121 might also need adjusting (for example when adding/changing the list
122 of extensions)
13b7c768
NIS
123
124 For Win32 the process is semi-automated - if you have a Win32
125 machine to run dmake on ...
126
b15dd5ec 127(i) Edit U/mkglossary (right near the top) to point to where you keep
2eb0fc7c 128 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 129
b15dd5ec 130(j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
2eb0fc7c
MB
131 Adjust the various compile-time options (e.g. 64bit, threads) as
132 you see fit.
133 You can skip this phase, it's not essential, just good housekeeping.
13b7c768 134
6475898c
MB
135(k) make veryclean; sh Configure -des -Dusedevel; make all test
136
137-- the next steps are in the metaconfig folder again
138
139(l) git add U/perl/foo/bar.U when you are ready ...
140
141(m) git commit -m "Your commit description"
13b7c768 142
6475898c
MB
143(n) When all patches are applied, tested and committed, and you are happy,
144 git push
13b7c768 145
6475898c 146 Merijn prefers to do steps (l) through (n) in git-gui