1 Jarkko's How to build Configure tweaked by Nick and Merijn, and now
2 maintained by perl5-metaconfig
4 The Configure script and config_h.SH file in the Perl distribution are
5 generated by a program called metaconfig. Metaconfig was originally
6 written by Larry Wall, and was subsequently enhanced and maintained
7 by Raphael Manfredi. The binary that invokes the generation of the
8 Configure file is called mconfig.
10 As sort order and filenaming are vital in this process, make sure you
11 are working on a case-sensitive file system! (Case preserving is not
14 You have presumably obtained the metaconfig from the repository e.g.
16 $ git clone github.com:perl5-metaconfig/metaconfig metaconfig
18 When working with metaconfig you will generally have two git checkouts
19 next to each other: (1) this metaconfig checkout; and (2) a checkout of
20 the Perl 5 source code in which you will generate a new Configure
21 script. In this README, we will refer to these directories as the
22 'metaconfig' directory and the 'perl' directory.
24 Since these two directories are normally next to each other, so ../perl
25 will get you to perl and ../perl/../metaconfig will get you back here.
26 You should establish a symbolic link to the checkout in which Configure
27 is generated such as this:
32 We will do the reverse symlinks later.
34 Contents of this directory:
37 U: Metaconfig units used for building Perl's Configure
39 a git clone of "dist". Optionally present. See (a) below.
40 This is where dist/meta resides as of 2016-04-01
42 The folder where the original units from dist are in.
43 These may differ from dist-git, as upstream also moves
48 (a) In order to assemble Configure from its units, you need mlint/metaline and
49 mconfig/metaconfig from the "dist" package installed and available in your
50 $PATH. You can either use the version that comes with your OS (Debian ships
51 it) or the versions that are included in this checkout: just add the full
52 name of this folder/bin to your $PATH. If you are not planning to analyse
53 differences of the current state with upstream dist, you can skip the rest
56 If you also want to play with or compare to the original meta/dist, you
57 can checkout that too.
59 The dist version used for perl is dist-3.5-20 in this directory, which is
60 a slightly modified version of the original, which you can get at GITHUB
61 repository https://github.com/rmanfredi/dist.git. If you'd like to keep
62 up to date with changes in dist, you can use git to create your own clone.
63 For git, that would be something like:
65 $ git clone https://github.com/rmanfredi/dist.git dist-git
67 Unsurprisingly 'dist' uses (its) Configure to generate itself:
69 $ cd dist-3.5-20 # or dist-git
70 $ chmod -R +w . # We have derived files in git :-(
75 After make install, remove lib/U/d_debugging.U in your target lib, as perl
76 uses its own way to set/define debugging (see INSTALL)
78 dist's 'Configure' is similar to perl's but perhaps not quite as polished.
80 There are some perl specific "dist units" in the 'U' directory.
81 The U directory also contains some patches to 'dist' which have already
82 been applied to dist-3.5-20 directory.
84 (aa) We have not yet arranged for metaconfig to use perl's versions of the
85 'units' by default so you need some housekeeping in the perl directory...
87 Then add metaconfig/bin to your $PATH or create aliases like
89 $ export MC5=/your/path/to/metaconfig
90 $ alias ml="perl $MC5/bin/mlint -O"
91 $ alias mc="perl $MC5/bin/mconfig -m -O"
93 examples in the rest of this README will just refer to mlint and mconfig
94 as if they appear in your $PATH
98 If you plan to make changes to mconfig or mlint locally (and you might
99 want to, as both are written for perl4), consider installing mconfig and
100 mlint from the cmon subdirectory into your $PATH too. These are the
101 non-autoloading versions and can easily be changed. As these are used by
102 all team members, please communicate changes on github first.
104 (b) You need to be in the 'perl' checkout directory, which you created the
105 symbolic link to, in preparation. In this working directory, you need
106 symbolic links too, which are already known to perl itself to ignore.
107 Assuming you have metaconfig and perl side by side on the same level:
108 ln -s ../metaconfig/U U
109 ln -s ../metaconfig/.package .package
110 ln -s MANIFEST MANIFEST.new
111 chmod +w Configure config_h.SH Porting/Glossary Porting/config*
113 (c) Create a new file for the new unit as U/foo/d_bar.U
114 ('foo' is one of the existing folders in U except for 'all'. It most
115 likely will be 'perl', but it could also be 'modified', 'compline' or any
116 other existing folder). Choose the best appropriate subdir of U. See
117 U/README for a description of the various subdirectories.) You should
118 choose the closest existing unit file as a starting point, and first copy
119 it to the new file. For example, the unit for seeing if strtold_l() exists
120 was created as U/threads/d_strtold_l.U, copied from perl/d_strtold.U, then
121 adjusted. It goes under 'threads' because it is used only on threaded
124 (d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
125 are usually serious and need fixing
127 Without -O, exceptions are lots of
128 Your private U/modified/issymlink.U overrides the public one.
129 due to the perl special units
133 "End.U": stale ?MAKE: dependency '$W'.
135 which is apparently normal ...
137 -- the next steps are in the perl folder, though the instructions below include
138 a 'cd perl' at each step, as a reminder. If you already are in 'perl',
139 disregard the reminders.
141 (e) There is a chicken and egg problem for newly created units. To get around
142 this, for such a unit, edit the file metaconfig.h and add to the comment
143 the appropropriate name. To continue the example above, we would add the
144 string HAS_STRTOLD_L at the end of the comment. This can be removed once
145 the code base has actual uses of the unit.
147 (f) "mconfig -m -O" to regenerate Configure and config_h.SH
149 Make *sure* your mconfig is the correct one in your $PATH, as the mono-web
150 package will install /usr/bin/mconfig which will do something completely
153 (g) metaconfig does not deal with depends in config_h.SH, so some
154 reorganization is needed.
157 $ perl Porting/config_h.pl
159 will fix the ordering
161 (h) The messy semi-automated part is that the knowledge of the new symbol
162 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
163 VMS, VOS, ... see previous Configure changes to see which are these
164 heathen lands. Files to take care of are
165 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
166 configure.com (VMS). Depending on the kind of patch djgpp/config* might
167 also need adjusting (for example when adding/changing the list of
170 Most can be checked and updated by a tool Nicholas provided:
173 $ perl Porting/checkcfgvar.pl
175 and if it shows differences, use one of:
177 $ perl Porting/checkcfgvar.pl --regen --default=undef
178 $ perl Porting/checkcfgvar.pl --regen --default=define
180 based on the changes you made. For safety, probes should probably be
181 'undef', whereas some other things unconditionally should default to
182 'define'. For example, 'default_inc_excludes_dot' should be 'define'
183 except in very limited circumstances, because it closes a security hole.
185 For Win32 the process is semi-automated. You have to have a Win32
186 machine to run dmake on to complete the process, but that can be done
187 later by someone with such access.
189 For VMS, ('configure.com'), it may be best to add the units as 'undef' and
190 let the VMS experts deal with them later. However, you can set them to
191 'define' if they are non-tricky (such as being basic functions having
192 standard signatures across architectures), and are in the oldest release of
193 VMS that perl can be compiled on, which is 7.3-2. Appendix A of "HP C
194 Run-Time Library Reference Manual for OpenVMS Systems" gives you that
195 information. As of October 2017, the latest version online is available
196 at: http://h41379.www4.hpe.com/doc/84final/5763/5763profile.html
198 In configure.com, if there is an existing probe that is essentially the
199 same (except for the names) as the one you're adding, you can copy, paste,
200 and adjust to create a new one, but note that it's easy to run afoul of the
201 quoting rules in configure.com. New probed-for units likely will require
202 at least 2 groups of changes.
204 Rerun checkcfgvar.pl until you've fixed everything it finds.
206 (i) Check if U/mkglossary (right near the top) points to where you keep
207 dist's standard metaconfig units as well as your perl-specific ones.
209 (j) Run the perl build chain
212 $ make veryclean # Only if Configure already has been run
213 $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
214 $ perl regen/uconfig_h.pl
216 Then make and make test or make test_harness
219 $ env TEST_JOBS=13 make test_harness
221 Before you start committing, make sure that
227 (k) Optionally, run Porting/mksample to freshen the Porting/config*.
228 Adjust the various compile-time options (e.g. 64bit, threads) as
230 You can skip this step, it's not essential, just good housekeeping.
232 Most of this only works if you have run the core-tests with the new
235 (kk) Run U/mkgloss.pl to freshen Porting/Glossary
237 You should at least check
239 $ perl U/mkgloss.pl | diff Porting/Glossary -
241 This will show two warnings that you can ignore:
243 U/mkglossary: couldn't find libdb_needs_pthread
244 U/mkglossary: couldn't find libdirs
246 all other things need a review
248 -- the next steps are in the metaconfig folder again
250 (l) git add U/foo/bar.U when you are ready ...
252 (m) git commit -m "Your commit description"
254 (n) When all patches are applied, tested and committed, and you are happy,
259 Documentation on 'dist' may be found at these locations:
260 https://github.com/rmanfredi/dist/blob/master/mcon/man/mconfig.SH
261 https://manpages.debian.org/stretch/dist/metaconfig.1.en.html
265 Tags are maintained in this git repository mapping the version of the
266 units that were used for the Configure in a given release of perl,
267 named simply after the version of perl in question (for example, at
268 the time of writing the current stable release is 5.26.1). This provides
269 a stable reference for downstreams wishing to import the metaconfig units
270 into their own packaging. Therefore, at minimum tags for each stable
271 release should be made (adding tags for development releases being an