This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge branch 'generalize_paths'
[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 14
b3647673 15 $ git clone github.com:perl5-metaconfig/metaconfig metaconfig
13b7c768
NIS
16
17Normally this directory and perl directory are next to each other
18so ../perl will get you to perl and ../perl/../metaconfig will get you
b3647673
MBT
19back here. The current setup will require a symbolic link to the folder
20where Configure is generated in:
21
22 $ cd metaconfig
23 $ ln -s ../perl perl
13b7c768 24
2eb0fc7c
MB
25Contents of this directory:
26
27 README: This file.
07438c4f 28 U: Metaconfig units used for building Perl's Configure
2eb0fc7c
MB
29 U.check: Sample directory used for testing new metaconfig units.
30 see U.check/README for more information.
e412846d
MBT
31 dist-git:
32 a git clone of "dist". Optionally present. See (a) below.
33 This is where dist/meta resides as of 2016-04-01
e00c5fdc 34 dist:
b3647673
MBT
35 The folder where the original units from dist are in.
36 These may differ from dist-git, as upstream also moves
37 on and develops.
2eb0fc7c 38
13b7c768 39(a) You need to have dist installed so that you have metalint and metaconfig
14db9c02 40 in your $PATH. As dist/meta binaries are now included in the git checkout,
1bf51bf8
MBT
41 you do NOT need to install dist/meta itself.
42
b3647673
MBT
43 If you also want to play with or compare to the original meta/dist, you
44 can checkout that too.
1bf51bf8 45
e00c5fdc 46 The dist version used for perl is dist-3.5-20 in this directory, which is
e412846d
MBT
47 a slightly modified version of the original, which you can get at GITHUB
48 repository https://github.com/rmanfredi/dist.git. If you'd like to keep
49 up to date with changes in dist, you can use git to create your own clone.
50 For git, that would be something like:
1e695180 51
e412846d 52 $ git clone https://github.com/rmanfredi/dist.git dist-git
1e695180 53
13b7c768
NIS
54 Unsurprisingly 'dist' uses (its) Configure to generate itself:
55
e412846d 56 $ cd dist-3.5-20 # or dist-git
1e695180
MB
57 $ chmod -R +w . # We have derived files in git :-(
58 $ ./Configure
59 $ make
60 $ make install
13b7c768 61
e00c5fdc 62 After make install, remove lib/U/d_debugging.U in your target lib, as perl
07438c4f 63 uses its own way to set/define debugging (see INSTALL)
e00c5fdc 64
e00c5fdc 65 dist's 'Configure' is similar to perl's but perhaps not quite as polished.
13b7c768
NIS
66
67 There are some perl specific "dist units" in the 'U' directory.
e00c5fdc
MB
68 The U directory also contains some patches to 'dist' which have already
69 been applied to dist-3.5-20 directory.
70 We have not yet arranged for metaconfig to use perl's versions of the
71 'units' by default so you need some housekeeping in the perl directory...
72
b3647673
MBT
73 Then add metaconfig/bin to your $PATH or create aliases like
74
75 $ export MC5=/your/path/to/metaconfig
76 $ alias ml="perl $MC5/bin/mlint -O"
77 $ alias mc="perl $MC5/bin/mconfig -m -O"
78
79 examples in the rest of this README will just refer to mlint and mconfig
80 as if they appear in your $PATH
81
92a8625a 82(aa)
352aa7ee 83
b3647673 84 If you plan to make changes to mconfig or mlint locally (and you might
92a8625a
MBT
85 want to, as both are written for perl4), consider installing mconfig and
86 mlint from the cmon subdirectory into your $PATH too. These are the
b3647673
MBT
87 non-autoloading versions and can easily be changed. As these are used by
88 all team members, please communicate changes on github first.
89
90(b) You need to be in a/the Perl directory, which you created the symbolic
91 link for in preparation. In this working directory, you need symbolic
92 links too, which are already known to perl itself to ignore. Assuming
93 you have metaconfig and perl side by side on the same level:
13b7c768
NIS
94 1) have a symlink to ../metaconfig/U called U
95 2) have a symlink to ../metaconfig/.package called .package
96 3) have a symlink to MANIFEST called MANIFEST.new
2eb0fc7c 97 4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
13b7c768 98
6475898c
MB
99(c) Write the new unit as U/perl/d_bar.U ('perl' can also be 'modified',
100 'compline' or any other existing folder, except for 'all'). Choose
101 the best appropriate subdir of U. See U/README for a description of
102 the various subdirectories.)
13b7c768 103
b3647673
MBT
104(d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
105 are usually serious and need fixing
13b7c768 106
b3647673 107 Without -O, exceptions are lots of
cb69034d 108 Your private U/modified/issymlink.U overrides the public one.
13b7c768
NIS
109 due to the perl special units
110
111 and
112
113 "End.U": stale ?MAKE: dependency '$W'.
114
115 which is apparently normal ...
116
6475898c
MB
117-- the next steps are in the perl folder
118
119(e) chmod +w Configure config_h.SH
13b7c768 120
b3647673
MBT
121 mlint and mconfig will probly die when these are read-only
122
92a8625a
MBT
123(f) mconfig -m -O to regenerate Configure and config_h.SH
124
125 Make *sure* your mconfig is the correct one in your $PATH, as the mono-web
126 package will install /usr/bin/mconfig which will do something completely
127 different.
13b7c768 128
b15dd5ec
MB
129(g) metaconfig does not deal with depends in config_h.SH, so some
130 reorganization is needed.
131
b3647673
MBT
132 $ cd perl
133 $ perl Porting/config_h.SH
b15dd5ec
MB
134
135 will fix the ordering
136
b3647673 137(h) The messy semi-automated part is that the knowledge of the new symbol
974341ad
JH
138 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
139 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
140 heathen lands. Files to take care of are
141 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
b3647673
MBT
142 configure.com (VMS), epoc/config.sh (EPOC). Depending on the kind of
143 patch djgpp/config* might also need adjusting (for example when
144 adding/changing the list of extensions)
145
146 Most can be checked and updated by a tool Nicholas provided:
147
148 $ cd perl
149 $ perl Porting/Porting/checkcfgvar.pl
150
151 and if it shows differences,
152
153 $ perl Porting/checkcfgvar.pl --regen --default=define
154
155 (of course "define" can also be "undef" based on the changes you made
13b7c768
NIS
156
157 For Win32 the process is semi-automated - if you have a Win32
158 machine to run dmake on ...
159
b3647673 160(i) Check if U/mkglossary (right near the top) points to where you keep
2eb0fc7c 161 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 162
b3647673 163(j) Run the perl build chain
cf3c5365 164
b3647673
MBT
165 $ cd perl
166 $ make veryclean
167 $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
cf3c5365
MB
168
169 The dependency for uconfig.h isn't carved in stone, so you might
170 need to regenerate it
171
b3647673 172 $ perl regen/uconfig_h.pl
cf3c5365 173
b3647673 174 Then make and make test or make test_harness
cf3c5365 175
b3647673
MBT
176 $ make -j12
177 $ env TEST_JOBS=13 make test_harness
cf3c5365
MB
178
179 Before you start committing, make sure that the other developers
180 are happy and run
181
b3647673
MBT
182 $ make test_porting
183
184 again
185
186(k) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
187 Adjust the various compile-time options (e.g. 64bit, threads) as
188 you see fit.
189 You can skip this phase, it's not essential, just good housekeeping.
190
191 Most of this only works if you have run the core-tests with the new
192 generated files
193
194 You should at least check
195
196 $ perl U/mkgloss.pl | diff Porting/Glossary -
197
198 This will show two warnings that you can ignore:
199
200 U/mkglossary: couldn't find libdb_needs_pthread
201 U/mkglossary: couldn't find libdirs
202
203 all other things need a review
6475898c
MB
204
205-- the next steps are in the metaconfig folder again
206
207(l) git add U/perl/foo/bar.U when you are ready ...
208
209(m) git commit -m "Your commit description"
13b7c768 210
6475898c
MB
211(n) When all patches are applied, tested and committed, and you are happy,
212 git push