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