This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Remove metaconfig units in sync with upstream
[metaconfig.git] / README
1         Jarkko's How to build Configure tweaked by Nick and Merijn.
2
3 The Configure script and config_h.SH file in the Perl distribution are
4 generated by a program called metaconfig.  Metaconfig was originally 
5 written by Larry Wall, and was subsequently enhanced and maintained
6 by Raphael Manfredi. The binary that invokes the generation of the
7 Configure file is called mconfig.
8
9 As sort order and filenaming are vital in this process, make sure you
10 are working on a case-sensitive file system! (Case preserving is not
11 sufficient).
12
13 You have presumably obtained the metaconfig from the repository e.g.
14
15   $ git clone github.com:perl5-metaconfig/metaconfig metaconfig
16
17 When working with metaconfig you will generally have two git checkouts
18 next to each other:  (1) this metaconfig checkout; and (2) a checkout of
19 the Perl 5 source code in which you will generate a new Configure
20 script. In this README, we will refer to these directories as the
21 'metaconfig' directory and the 'perl' directory.
22
23 Since these two directories are normally next to each other, so ../perl
24 will get you to perl and ../perl/../metaconfig will get you back here.
25 You should establish a symbolic link to the checkout in which Configure
26 is generated such as this:
27
28   $ cd metaconfig
29   $ ln -s ../perl perl
30
31 Contents of this directory:
32
33     README:     This file.
34     U:          Metaconfig units used for building Perl's Configure
35     U.check:    Sample directory used for testing new metaconfig units.
36                 see U.check/README for more information.
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
40     dist:
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.
44
45 (a) You need to have dist installed so that you have metalint and metaconfig
46     in your $PATH. As dist/meta binaries are now included in the git checkout,
47     you do NOT need to install dist/meta itself.
48
49     If you also want to play with or compare to the original meta/dist, you
50     can checkout that too.
51
52     The dist version used for perl is dist-3.5-20 in this directory, which is
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:
57
58     $ git clone https://github.com/rmanfredi/dist.git dist-git
59
60     Unsurprisingly 'dist' uses (its) Configure to generate itself:
61
62     $ cd dist-3.5-20    # or dist-git
63     $ chmod -R +w .     # We have derived files in git :-(
64     $ ./Configure
65     $ make
66     $ make install
67
68     After make install, remove lib/U/d_debugging.U in your target lib, as perl
69     uses its own way to set/define debugging (see INSTALL)
70
71     dist's 'Configure' is similar to perl's but perhaps not quite as polished.
72
73     There are some perl specific "dist units" in the 'U' directory.
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
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
88 (aa)
89
90     If you plan to make changes to mconfig or mlint locally (and you might
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
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
96 (b) You need to be in the 'perl' checkout directory, which you created the symbolic
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:
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
103      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
104
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.)
109
110 (d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
111     are usually serious and need fixing
112
113     Without -O, exceptions are lots of
114       Your private U/modified/issymlink.U overrides the public one.
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
123 -- the next steps are in the perl folder
124
125 (e) chmod +w Configure config_h.SH
126
127     mlint and mconfig will probably die when these are read-only
128
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.
134
135 (g) metaconfig does not deal with depends in config_h.SH, so some
136     reorganization is needed.
137
138     $ cd perl
139     $ perl Porting/config_h.pl
140
141     will fix the ordering
142     
143 (h) The messy semi-automated part is that the knowledge of the new symbol
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),
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
155     $ perl Porting/checkcfgvar.pl
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
162
163     For Win32 the process is semi-automated - if you have a Win32
164     machine to run dmake on ...
165
166 (i) Check if U/mkglossary (right near the top) points to where you keep
167     dist's standard metaconfig units as well as your perl-specific ones.
168
169 (j) Run the perl build chain
170
171     $ cd perl
172     $ make veryclean
173     $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
174
175     The dependency for uconfig.h isn't carved in stone, so you might
176     need to regenerate it
177
178     $ perl regen/uconfig_h.pl
179
180     Then make and make test or make test_harness
181
182     $ make -j12
183     $ env TEST_JOBS=13 make test_harness
184
185     Before you start committing, make sure that the other developers
186     are happy and run
187
188     $ make test_porting
189
190     again
191
192 (k) Run Porting/mksample to freshen the Porting/config*.
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
200 (kk) Run U/mkgloss.pl to freshen Porting/Glossary
201
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
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"
218
219 (n) When all patches are applied, tested and committed, and you are happy,
220     git push
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