This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Chainsaw out the possibility to disable useperlio
[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.
25 dist-3.0at70:
26 dist-3.0 at patchlevel 70. This is the final version released
27 by Raphael Manfredi. Don't use it. Instead, use ...
28 dist-3.0at70b:
29 dist-3.0 at patchlevel 70 with unofficial patches 'a' and 'b'
30 applied. This version was never officially released, but
31 the patches are essential, so this is the version we use for
32 perl. Actually, I've also applied U/dist_patches/dist-p70c
6475898c
MB
33 to this tree. If someone with commit power wants to change
34 the name of the directory, that'd be fine. Otherwise, it
35 really doesn't matter.
e00c5fdc
MB
36 dist-3.5-20:
37 dist-3.5-20 is almost meta-4.0, still maintained by Raphael
38 Manfredi, but with a lot of fixes over 3.0, some changes
39 from the perl modifications merged and a much better metalint
40 dist:
41 a symlink to the lib you actually use. For Merijn that is
42 metaconfig/dist -> ../lib/dist
2eb0fc7c 43
13b7c768
NIS
44(a) You need to have dist installed so that you have metalint and metaconfig
45 in your $PATH.
e00c5fdc
MB
46 The dist version used for perl is dist-3.5-20 in this directory, which is
47 a slightly modified version of the original, which you can get at the SVN
48 repository https://dist.svn.sourceforge.net/svnroot/dist/trunk
13b7c768
NIS
49 Unsurprisingly 'dist' uses (its) Configure to generate itself:
50
e00c5fdc 51 cd dist-3.5-20
6475898c 52 chmod -R +w . # We have derived files in git :-(
13b7c768
NIS
53 ./Configure
54 make
55 make install
56
e00c5fdc
MB
57 After make install, remove lib/U/d_debugging.U in your target lib, as perl
58 uses it's own way to set/define debugging (see INSTALL)
59
60 the dist-3.5-20 installation as used by Merijn is available on his CPAN as
61 perl-meta-3.5-20.tgz
62
63 dist's 'Configure' is similar to perl's but perhaps not quite as polished.
13b7c768
NIS
64
65 There are some perl specific "dist units" in the 'U' directory.
e00c5fdc
MB
66 The U directory also contains some patches to 'dist' which have already
67 been applied to dist-3.5-20 directory.
68 We have not yet arranged for metaconfig to use perl's versions of the
69 'units' by default so you need some housekeeping in the perl directory...
70
71(b) You need to be in a/the Perl directory, i.e. either something from
72 //depot/perl/... or one of its branches
13b7c768
NIS
73 (e.g. Nick I-S is usually in //depot/perlio/...)
74 and you need:
75 1) have a symlink to ../metaconfig/U called U
76 2) have a symlink to ../metaconfig/.package called .package
77 3) have a symlink to MANIFEST called MANIFEST.new
2eb0fc7c 78 4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
13b7c768 79
6475898c
MB
80(c) Write the new unit as U/perl/d_bar.U ('perl' can also be 'modified',
81 'compline' or any other existing folder, except for 'all'). Choose
82 the best appropriate subdir of U. See U/README for a description of
83 the various subdirectories.)
13b7c768 84
2eb0fc7c 85(d) Run metalint to see nits: as opposed to lint, the gripings of
13b7c768
NIS
86 metalint are usually serious :-) and need fixing
87
88 Exceptions are lots of
89 Your private U/modified/voidflags.U overrides the public one.
90 due to the perl special units
91
e00c5fdc
MB
92 an alias to something like
93 $ metalint |& grep -v -e '^ Your private U/'
94 will make the process silence up on that
95
13b7c768
NIS
96 and
97
98 "End.U": stale ?MAKE: dependency '$W'.
99
100 which is apparently normal ...
101
6475898c
MB
102-- the next steps are in the perl folder
103
104(e) chmod +w Configure config_h.SH
13b7c768
NIS
105
106(f) metaconfig -m to regenerate Configure
107
b15dd5ec
MB
108(g) metaconfig does not deal with depends in config_h.SH, so some
109 reorganization is needed.
110
111 perl Porting/config_h.SH
112
113 will fix the ordering
114
115(h) The messy not-yet-automated part is that the knowledge of the new symbol
974341ad
JH
116 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
117 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
118 heathen lands. Files to take care of are
119 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
120 configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
121 epoc/config.sh (EPOC). Depending on the kind of patch djgpp/config*
122 might also need adjusting (for example when adding/changing the list
123 of extensions)
13b7c768
NIS
124
125 For Win32 the process is semi-automated - if you have a Win32
126 machine to run dmake on ...
127
b15dd5ec 128(i) Edit U/mkglossary (right near the top) to point to where you keep
2eb0fc7c 129 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 130
b15dd5ec 131(j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
2eb0fc7c
MB
132 Adjust the various compile-time options (e.g. 64bit, threads) as
133 you see fit.
134 You can skip this phase, it's not essential, just good housekeeping.
13b7c768 135
6475898c
MB
136(k) make veryclean; sh Configure -des -Dusedevel; make all test
137
138-- the next steps are in the metaconfig folder again
139
140(l) git add U/perl/foo/bar.U when you are ready ...
141
142(m) git commit -m "Your commit description"
13b7c768 143
6475898c
MB
144(n) When all patches are applied, tested and committed, and you are happy,
145 git push
13b7c768 146
6475898c 147 Merijn prefers to do steps (l) through (n) in git-gui