This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge pull request #36 from perl5-metaconfig/docs
[metaconfig.git] / README
CommitLineData
496e2020
KW
1 Jarkko's How to build Configure tweaked by Nick and Merijn, and now
2 maintained by perl5-metaconfig
2eb0fc7c
MB
3
4The Configure script and config_h.SH file in the Perl distribution are
496e2020 5generated by a program called metaconfig. Metaconfig was originally
2eb0fc7c 6written by Larry Wall, and was subsequently enhanced and maintained
92a8625a
MBT
7by Raphael Manfredi. The binary that invokes the generation of the
8Configure file is called mconfig.
9
10As sort order and filenaming are vital in this process, make sure you
11are working on a case-sensitive file system! (Case preserving is not
12sufficient).
13b7c768
NIS
13
14You have presumably obtained the metaconfig from the repository e.g.
6475898c 15
b3647673 16 $ git clone github.com:perl5-metaconfig/metaconfig metaconfig
13b7c768 17
bb6fc91c
JK
18When working with metaconfig you will generally have two git checkouts
19next to each other: (1) this metaconfig checkout; and (2) a checkout of
20the Perl 5 source code in which you will generate a new Configure
21script. In this README, we will refer to these directories as the
22'metaconfig' directory and the 'perl' directory.
23
24Since these two directories are normally next to each other, so ../perl
25will get you to perl and ../perl/../metaconfig will get you back here.
26You should establish a symbolic link to the checkout in which Configure
27is generated such as this:
b3647673
MBT
28
29 $ cd metaconfig
30 $ ln -s ../perl perl
13b7c768 31
496e2020
KW
32We will do the reverse symlinks later.
33
2eb0fc7c
MB
34Contents of this directory:
35
36 README: This file.
07438c4f 37 U: Metaconfig units used for building Perl's Configure
2eb0fc7c
MB
38 U.check: Sample directory used for testing new metaconfig units.
39 see U.check/README for more information.
e412846d
MBT
40 dist-git:
41 a git clone of "dist". Optionally present. See (a) below.
42 This is where dist/meta resides as of 2016-04-01
e00c5fdc 43 dist:
b3647673
MBT
44 The folder where the original units from dist are in.
45 These may differ from dist-git, as upstream also moves
46 on and develops.
2eb0fc7c 47
13b7c768 48(a) You need to have dist installed so that you have metalint and metaconfig
14db9c02 49 in your $PATH. As dist/meta binaries are now included in the git checkout,
1bf51bf8
MBT
50 you do NOT need to install dist/meta itself.
51
b3647673
MBT
52 If you also want to play with or compare to the original meta/dist, you
53 can checkout that too.
1bf51bf8 54
e00c5fdc 55 The dist version used for perl is dist-3.5-20 in this directory, which is
e412846d
MBT
56 a slightly modified version of the original, which you can get at GITHUB
57 repository https://github.com/rmanfredi/dist.git. If you'd like to keep
58 up to date with changes in dist, you can use git to create your own clone.
59 For git, that would be something like:
1e695180 60
e412846d 61 $ git clone https://github.com/rmanfredi/dist.git dist-git
1e695180 62
13b7c768
NIS
63 Unsurprisingly 'dist' uses (its) Configure to generate itself:
64
e412846d 65 $ cd dist-3.5-20 # or dist-git
1e695180
MB
66 $ chmod -R +w . # We have derived files in git :-(
67 $ ./Configure
68 $ make
69 $ make install
13b7c768 70
e00c5fdc 71 After make install, remove lib/U/d_debugging.U in your target lib, as perl
07438c4f 72 uses its own way to set/define debugging (see INSTALL)
e00c5fdc 73
e00c5fdc 74 dist's 'Configure' is similar to perl's but perhaps not quite as polished.
13b7c768
NIS
75
76 There are some perl specific "dist units" in the 'U' directory.
e00c5fdc
MB
77 The U directory also contains some patches to 'dist' which have already
78 been applied to dist-3.5-20 directory.
496e2020
KW
79
80(aa) We have not yet arranged for metaconfig to use perl's versions of the
e00c5fdc
MB
81 'units' by default so you need some housekeeping in the perl directory...
82
b3647673
MBT
83 Then add metaconfig/bin to your $PATH or create aliases like
84
85 $ export MC5=/your/path/to/metaconfig
86 $ alias ml="perl $MC5/bin/mlint -O"
87 $ alias mc="perl $MC5/bin/mconfig -m -O"
88
89 examples in the rest of this README will just refer to mlint and mconfig
90 as if they appear in your $PATH
91
496e2020 92(aaa)
352aa7ee 93
b3647673 94 If you plan to make changes to mconfig or mlint locally (and you might
92a8625a
MBT
95 want to, as both are written for perl4), consider installing mconfig and
96 mlint from the cmon subdirectory into your $PATH too. These are the
b3647673
MBT
97 non-autoloading versions and can easily be changed. As these are used by
98 all team members, please communicate changes on github first.
99
496e2020
KW
100(b) You need to be in the 'perl' checkout directory, which you created the
101 symbolic link to, in preparation. In this working directory, you need
102 symbolic links too, which are already known to perl itself to ignore.
103 Assuming you have metaconfig and perl side by side on the same level:
104 ln -s ../metaconfig/U U
105 ln -s ../metaconfig/.package .package
106 ln -s MANIFEST MANIFEST.new
107 chmod +w Configure config_h.SH Porting/Glossary Porting/config*
108
109(c) Create a new file for the new unit as U/foo/d_bar.U
110 ('foo' is one of the existing folders in U except for 'all'. It most
111 likely will be 'perl', but it could also be 'modified', 'compline' or any
112 other existing folder). Choose the best appropriate subdir of U. See
113 U/README for a description of the various subdirectories.) You should
114 choose the closest existing unit file as a starting point, and first copy
115 it to the new file. For example, the unit for seeing if strtold_l() exists
116 was created as U/threads/d_strtold_l.U, copied from perl/d_strtold.U, then
117 adjusted. It goes under 'threads' because it is used only on threaded
118 perls.
13b7c768 119
b3647673
MBT
120(d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
121 are usually serious and need fixing
13b7c768 122
b3647673 123 Without -O, exceptions are lots of
cb69034d 124 Your private U/modified/issymlink.U overrides the public one.
13b7c768
NIS
125 due to the perl special units
126
127 and
128
129 "End.U": stale ?MAKE: dependency '$W'.
130
131 which is apparently normal ...
132
496e2020
KW
133-- the next steps are in the perl folder, though the instructions below include
134 a 'cd perl' at each step, as a reminder. If you already are in 'perl',
135 disregard the reminders.
13b7c768 136
496e2020
KW
137(e) There is a chicken and egg problem for newly created units. To get around
138 this, for such a unit, edit the file metaconfig.h and add to the comment
139 the appropropriate name. To continue the example above, we would add the
140 string HAS_STRTOLD_L at the end of the comment. This can be removed once
141 the code base has actual uses of the unit.
b3647673 142
92a8625a
MBT
143(f) mconfig -m -O to regenerate Configure and config_h.SH
144
145 Make *sure* your mconfig is the correct one in your $PATH, as the mono-web
146 package will install /usr/bin/mconfig which will do something completely
147 different.
13b7c768 148
b15dd5ec
MB
149(g) metaconfig does not deal with depends in config_h.SH, so some
150 reorganization is needed.
151
b3647673 152 $ cd perl
430b74fe 153 $ perl Porting/config_h.pl
b15dd5ec
MB
154
155 will fix the ordering
496e2020 156
b3647673 157(h) The messy semi-automated part is that the knowledge of the new symbol
974341ad
JH
158 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
159 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
160 heathen lands. Files to take care of are
161 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
b3647673
MBT
162 configure.com (VMS), epoc/config.sh (EPOC). Depending on the kind of
163 patch djgpp/config* might also need adjusting (for example when
164 adding/changing the list of extensions)
165
166 Most can be checked and updated by a tool Nicholas provided:
167
168 $ cd perl
96f3f726 169 $ perl Porting/checkcfgvar.pl
b3647673
MBT
170
171 and if it shows differences,
172
173 $ perl Porting/checkcfgvar.pl --regen --default=define
174
175 (of course "define" can also be "undef" based on the changes you made
13b7c768 176
496e2020
KW
177 For Win32 the process is semi-automated -- if you have a Win32
178 machine to run dmake on
179
180 For vms, ('configure.com'), you likely will have to hand-edit in the
181 changes, using a similar unit as a starting point. There likely will be at
182 least 2 groups of changes. Rerun the tool until you've fixed everything it
183 finds.
13b7c768 184
b3647673 185(i) Check if U/mkglossary (right near the top) points to where you keep
2eb0fc7c 186 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 187
b3647673 188(j) Run the perl build chain
cf3c5365 189
b3647673 190 $ cd perl
496e2020 191 $ make veryclean # Only if Configure already has been run
b3647673 192 $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
b3647673 193 $ perl regen/uconfig_h.pl
cf3c5365 194
b3647673 195 Then make and make test or make test_harness
cf3c5365 196
b3647673
MBT
197 $ make -j12
198 $ env TEST_JOBS=13 make test_harness
cf3c5365
MB
199
200 Before you start committing, make sure that the other developers
201 are happy and run
202
b3647673
MBT
203 $ make test_porting
204
205 again
206
496e2020 207(k) Optionally, run Porting/mksample to freshen the Porting/config*.
b3647673
MBT
208 Adjust the various compile-time options (e.g. 64bit, threads) as
209 you see fit.
496e2020 210 You can skip this step, it's not essential, just good housekeeping.
b3647673
MBT
211
212 Most of this only works if you have run the core-tests with the new
213 generated files
214
82e3f9e4
DH
215(kk) Run U/mkgloss.pl to freshen Porting/Glossary
216
b3647673
MBT
217 You should at least check
218
219 $ perl U/mkgloss.pl | diff Porting/Glossary -
220
221 This will show two warnings that you can ignore:
222
223 U/mkglossary: couldn't find libdb_needs_pthread
224 U/mkglossary: couldn't find libdirs
225
226 all other things need a review
6475898c
MB
227
228-- the next steps are in the metaconfig folder again
229
496e2020 230(l) git add U/foo/bar.U when you are ready ...
6475898c
MB
231
232(m) git commit -m "Your commit description"
13b7c768 233
6475898c
MB
234(n) When all patches are applied, tested and committed, and you are happy,
235 git push
b69b99d9
JK
236
237(o) Documentation on 'dist' may be found at these locations:
238 https://github.com/rmanfredi/dist/blob/master/mcon/man/mconfig.SH
239 https://manpages.debian.org/stretch/dist/metaconfig.1.en.html