This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ignore perl symlink
[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 37(a) You need to have dist installed so that you have metalint and metaconfig
14db9c02 38 in your $PATH. As dist/meta binaries are now included in the git checkout,
1bf51bf8
MBT
39 you do NOT need to install dist/meta itself.
40
41 If you also want to play with or compare to the original meta/dit, you can
42 checkout that too.
43
e00c5fdc 44 The dist version used for perl is dist-3.5-20 in this directory, which is
e412846d
MBT
45 a slightly modified version of the original, which you can get at GITHUB
46 repository https://github.com/rmanfredi/dist.git. If you'd like to keep
47 up to date with changes in dist, you can use git to create your own clone.
48 For git, that would be something like:
1e695180 49
e412846d 50 $ git clone https://github.com/rmanfredi/dist.git dist-git
1e695180 51
13b7c768
NIS
52 Unsurprisingly 'dist' uses (its) Configure to generate itself:
53
e412846d 54 $ cd dist-3.5-20 # or dist-git
1e695180
MB
55 $ chmod -R +w . # We have derived files in git :-(
56 $ ./Configure
57 $ make
58 $ make install
13b7c768 59
e00c5fdc 60 After make install, remove lib/U/d_debugging.U in your target lib, as perl
07438c4f 61 uses its own way to set/define debugging (see INSTALL)
e00c5fdc
MB
62
63 the dist-3.5-20 installation as used by Merijn is available on his CPAN as
64 perl-meta-3.5-20.tgz
65
66 dist's 'Configure' is similar to perl's but perhaps not quite as polished.
13b7c768
NIS
67
68 There are some perl specific "dist units" in the 'U' directory.
e00c5fdc
MB
69 The U directory also contains some patches to 'dist' which have already
70 been applied to dist-3.5-20 directory.
71 We have not yet arranged for metaconfig to use perl's versions of the
72 'units' by default so you need some housekeeping in the perl directory...
73
92a8625a 74(aa)
352aa7ee 75
92a8625a
MBT
76 If you plan to make changes to mconfig or mlint locally (and you probably
77 want to, as both are written for perl4), consider installing mconfig and
78 mlint from the cmon subdirectory into your $PATH too. These are the
79 non-autoloading versions and can easily be changed. Here is what I added
80 at the beginning of mconfig:
352aa7ee
MB
81
82 --8<---
83 BEGIN { $ENV{LC_ALL} = "C"; }
84 chdir "/pro/3gl/CPAN/perl";
85 { my @Cc = qw( Configure config_h.SH );
86 system "chown merijn @Cc";
87 chmod 0775, @Cc;
88 #-d "merijn" or mkdir "merijn";
89 #system "cp -f Configure config_h.SH Porting/Glossary Porting/config.sh merijn/";
90 system "ls", "-l", @Cc;
91 }
92 -->8---
93
cf3c5365 94 I also added the first two lines of that patch to mlint
352aa7ee 95
e00c5fdc
MB
96(b) You need to be in a/the Perl directory, i.e. either something from
97 //depot/perl/... or one of its branches
13b7c768
NIS
98 (e.g. Nick I-S is usually in //depot/perlio/...)
99 and you need:
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
352aa7ee
MB
110(d) Run metalint (or mlint) to see nits: as opposed to lint, the gripings
111 of metalint are usually serious :-) and need fixing
13b7c768
NIS
112
113 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
e00c5fdc
MB
117 an alias to something like
118 $ metalint |& grep -v -e '^ Your private U/'
352aa7ee
MB
119 will make the process silence up on that (of course you can add an
120 option to mlint to disable that warning (which is already disabled
121 by the undocumented and forgotten -s option, but that also suppresses
122 other warnings)
e00c5fdc 123
13b7c768
NIS
124 and
125
126 "End.U": stale ?MAKE: dependency '$W'.
127
128 which is apparently normal ...
129
6475898c
MB
130-- the next steps are in the perl folder
131
132(e) chmod +w Configure config_h.SH
13b7c768 133
92a8625a
MBT
134(f) mconfig -m -O to regenerate Configure and config_h.SH
135
136 Make *sure* your mconfig is the correct one in your $PATH, as the mono-web
137 package will install /usr/bin/mconfig which will do something completely
138 different.
13b7c768 139
b15dd5ec
MB
140(g) metaconfig does not deal with depends in config_h.SH, so some
141 reorganization is needed.
142
143 perl Porting/config_h.SH
144
145 will fix the ordering
146
147(h) The messy not-yet-automated part is that the knowledge of the new symbol
974341ad
JH
148 needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
149 VMS, VOS, EPOC, ... see previous Configure changes to see which are these
150 heathen lands. Files to take care of are
151 {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
152 configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
153 epoc/config.sh (EPOC). Depending on the kind of patch djgpp/config*
154 might also need adjusting (for example when adding/changing the list
155 of extensions)
13b7c768
NIS
156
157 For Win32 the process is semi-automated - if you have a Win32
158 machine to run dmake on ...
159
b15dd5ec 160(i) Edit U/mkglossary (right near the top) to point to where you keep
2eb0fc7c 161 dist's standard metaconfig units as well as your perl-specific ones.
13b7c768 162
b15dd5ec 163(j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
2eb0fc7c
MB
164 Adjust the various compile-time options (e.g. 64bit, threads) as
165 you see fit.
166 You can skip this phase, it's not essential, just good housekeeping.
13b7c768 167
cf3c5365
MB
168(k) Run the perl build chain
169
170 make veryclean
171 sh ./Configure -des -Dusedevel
172
173 The dependency for uconfig.h isn't carved in stone, so you might
174 need to regenerate it
175
176 perl regen/uconfig_h.pl
177
178 Then make and make test or make test_harness (with TEST_JOBS=5)
179
180 make all test_harness
181
182 Before you start committing, make sure that the other developers
183 are happy and run
184
185 make test_porting
6475898c
MB
186
187-- the next steps are in the metaconfig folder again
188
189(l) git add U/perl/foo/bar.U when you are ready ...
190
191(m) git commit -m "Your commit description"
13b7c768 192
6475898c
MB
193(n) When all patches are applied, tested and committed, and you are happy,
194 git push
13b7c768 195
6475898c 196 Merijn prefers to do steps (l) through (n) in git-gui