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