This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Two nits not show by mlint
[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.
07438c4f 22 U: Metaconfig units used for building Perl's Configure
2eb0fc7c
MB
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
6b5a47e4
MBT
40 repository https://svn.code.sf.net/p/dist/code/trunk/dist. If you'd like
41 to keep up to date with changes in dist, you can either use svn or git to
42 create your own clone. For git, that would be something like:
1e695180
MB
43
44 $ git svn clone \
63f38a42 45 svn://svn.code.sf.net/p/dist/code/trunk/dist \
1e695180
MB
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 56 After make install, remove lib/U/d_debugging.U in your target lib, as perl
07438c4f 57 uses its own way to set/define debugging (see INSTALL)
e00c5fdc
MB
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
352aa7ee
MB
70(aa) -- optional --
71
72 If you plan to make changes to metaconfig or metalint locally (and you
73 probably want to, as both are written for perl4), consider installing
74 mconfig and mlint from the cmon subdirectory into your $PATH too. These
75 are the non-autoloading versions and can easily be changed. Here is what
76 I added at the beginning of mconfig:
77
78 --8<---
79 BEGIN { $ENV{LC_ALL} = "C"; }
80 chdir "/pro/3gl/CPAN/perl";
81 { my @Cc = qw( Configure config_h.SH );
82 system "chown merijn @Cc";
83 chmod 0775, @Cc;
84 #-d "merijn" or mkdir "merijn";
85 #system "cp -f Configure config_h.SH Porting/Glossary Porting/config.sh merijn/";
86 system "ls", "-l", @Cc;
87 }
88 -->8---
89
cf3c5365 90 I also added the first two lines of that patch to mlint
352aa7ee 91
e00c5fdc
MB
92(b) You need to be in a/the Perl directory, i.e. either something from
93 //depot/perl/... or one of its branches
13b7c768
NIS
94 (e.g. Nick I-S is usually in //depot/perlio/...)
95 and you need:
96 1) have a symlink to ../metaconfig/U called U
97 2) have a symlink to ../metaconfig/.package called .package
98 3) have a symlink to MANIFEST called MANIFEST.new
2eb0fc7c 99 4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
13b7c768 100
6475898c
MB
101(c) Write the new unit as U/perl/d_bar.U ('perl' can also be 'modified',
102 'compline' or any other existing folder, except for 'all'). Choose
103 the best appropriate subdir of U. See U/README for a description of
104 the various subdirectories.)
13b7c768 105
352aa7ee
MB
106(d) Run metalint (or mlint) to see nits: as opposed to lint, the gripings
107 of metalint are usually serious :-) and need fixing
13b7c768
NIS
108
109 Exceptions are lots of
cb69034d 110 Your private U/modified/issymlink.U overrides the public one.
13b7c768
NIS
111 due to the perl special units
112
e00c5fdc
MB
113 an alias to something like
114 $ metalint |& grep -v -e '^ Your private U/'
352aa7ee
MB
115 will make the process silence up on that (of course you can add an
116 option to mlint to disable that warning (which is already disabled
117 by the undocumented and forgotten -s option, but that also suppresses
118 other warnings)
e00c5fdc 119
13b7c768
NIS
120 and
121
122 "End.U": stale ?MAKE: dependency '$W'.
123
124 which is apparently normal ...
125
6475898c
MB
126-- the next steps are in the perl folder
127
128(e) chmod +w Configure config_h.SH
13b7c768 129
352aa7ee 130(f) metaconfig -m to regenerate Configure (or mconfig -m)
13b7c768 131
b15dd5ec
MB
132(g) metaconfig does not deal with depends in config_h.SH, so some
133 reorganization is needed.
134
135 perl Porting/config_h.SH
136
137 will fix the ordering
138
139(h) The messy not-yet-automated part is that the knowledge of the new symbol
974341ad
JH
140 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
141 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
142 heathen lands. Files to take care of are
143 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
144 configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
145 epoc/config.sh (EPOC). Depending on the kind of patch djgpp/config*
146 might also need adjusting (for example when adding/changing the list
147 of extensions)
13b7c768
NIS
148
149 For Win32 the process is semi-automated - if you have a Win32
150 machine to run dmake on ...
151
b15dd5ec 152(i) Edit U/mkglossary (right near the top) to point to where you keep
2eb0fc7c 153 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 154
b15dd5ec 155(j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
2eb0fc7c
MB
156 Adjust the various compile-time options (e.g. 64bit, threads) as
157 you see fit.
158 You can skip this phase, it's not essential, just good housekeeping.
13b7c768 159
cf3c5365
MB
160(k) Run the perl build chain
161
162 make veryclean
163 sh ./Configure -des -Dusedevel
164
165 The dependency for uconfig.h isn't carved in stone, so you might
166 need to regenerate it
167
168 perl regen/uconfig_h.pl
169
170 Then make and make test or make test_harness (with TEST_JOBS=5)
171
172 make all test_harness
173
174 Before you start committing, make sure that the other developers
175 are happy and run
176
177 make test_porting
6475898c
MB
178
179-- the next steps are in the metaconfig folder again
180
181(l) git add U/perl/foo/bar.U when you are ready ...
182
183(m) git commit -m "Your commit description"
13b7c768 184
6475898c
MB
185(n) When all patches are applied, tested and committed, and you are happy,
186 git push
13b7c768 187
6475898c 188 Merijn prefers to do steps (l) through (n) in git-gui