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
1   Jarkko's How to build Configure tweaked by Nick and Merijn, and now
2                  maintained by perl5-metaconfig
3
4 The Configure script and config_h.SH file in the Perl distribution are
5 generated by a program called metaconfig.  Metaconfig was originally
6 written by Larry Wall, and was subsequently enhanced and maintained
7 by Raphael Manfredi. The binary that invokes the generation of the
8 Configure file is called mconfig.
9
10 As sort order and filenaming are vital in this process, make sure you
11 are working on a case-sensitive file system! (Case preserving is not
12 sufficient).
13
14 You have presumably obtained the metaconfig from the repository e.g.
15
16   $ git clone github.com:perl5-metaconfig/metaconfig metaconfig
17
18 When working with metaconfig you will generally have two git checkouts
19 next to each other:  (1) this metaconfig checkout; and (2) a checkout of
20 the Perl 5 source code in which you will generate a new Configure
21 script. In this README, we will refer to these directories as the
22 'metaconfig' directory and the 'perl' directory.
23
24 Since these two directories are normally next to each other, so ../perl
25 will get you to perl and ../perl/../metaconfig will get you back here.
26 You should establish a symbolic link to the checkout in which Configure
27 is generated such as this:
28
29   $ cd metaconfig
30   $ ln -s ../perl perl
31
32 We will do the reverse symlinks later.
33
34 Contents of this directory:
35
36     README:     This file.
37     U:          Metaconfig units used for building Perl's Configure
38     U.check:    Sample directory used for testing new metaconfig units.
39                 see U.check/README for more information.
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
43     dist:
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.
47
48 (a) You need to have dist installed so that you have metalint and metaconfig
49     in your $PATH. As dist/meta binaries are now included in the git checkout,
50     you do NOT need to install dist/meta itself.
51
52     If you also want to play with or compare to the original meta/dist, you
53     can checkout that too.
54
55     The dist version used for perl is dist-3.5-20 in this directory, which is
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:
60
61     $ git clone https://github.com/rmanfredi/dist.git dist-git
62
63     Unsurprisingly 'dist' uses (its) Configure to generate itself:
64
65     $ cd dist-3.5-20    # or dist-git
66     $ chmod -R +w .     # We have derived files in git :-(
67     $ ./Configure
68     $ make
69     $ make install
70
71     After make install, remove lib/U/d_debugging.U in your target lib, as perl
72     uses its own way to set/define debugging (see INSTALL)
73
74     dist's 'Configure' is similar to perl's but perhaps not quite as polished.
75
76     There are some perl specific "dist units" in the 'U' directory.
77     The U directory also contains some patches to 'dist' which have already
78     been applied to dist-3.5-20 directory.
79
80 (aa) We have not yet arranged for metaconfig to use perl's versions of the
81     'units' by default so you need some housekeeping in the perl directory...
82
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
92 (aaa)
93
94     If you plan to make changes to mconfig or mlint locally (and you might
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
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
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.
119
120 (d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
121     are usually serious and need fixing
122
123     Without -O, exceptions are lots of
124       Your private U/modified/issymlink.U overrides the public one.
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
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.
136
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.
142
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.
148
149 (g) metaconfig does not deal with depends in config_h.SH, so some
150     reorganization is needed.
151
152     $ cd perl
153     $ perl Porting/config_h.pl
154
155     will fix the ordering
156
157 (h) The messy semi-automated part is that the knowledge of the new symbol
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),
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
169     $ perl Porting/checkcfgvar.pl
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
176
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.
184
185 (i) Check if U/mkglossary (right near the top) points to where you keep
186     dist's standard metaconfig units as well as your perl-specific ones.
187
188 (j) Run the perl build chain
189
190     $ cd perl
191     $ make veryclean    # Only if Configure already has been run
192     $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
193     $ perl regen/uconfig_h.pl
194
195     Then make and make test or make test_harness
196
197     $ make -j12
198     $ env TEST_JOBS=13 make test_harness
199
200     Before you start committing, make sure that the other developers
201     are happy and run
202
203     $ make test_porting
204
205     again
206
207 (k) Optionally, run Porting/mksample to freshen the Porting/config*.
208     Adjust the various compile-time options (e.g. 64bit, threads) as
209     you see fit.
210     You can skip this step, it's not essential, just good housekeeping.
211
212     Most of this only works if you have run the core-tests with the new
213     generated files
214
215 (kk) Run U/mkgloss.pl to freshen Porting/Glossary
216
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
227
228 -- the next steps are in the metaconfig folder again
229
230 (l) git add U/foo/bar.U when you are ready ...
231
232 (m) git commit -m "Your commit description"
233
234 (n) When all patches are applied, tested and committed, and you are happy,
235     git push
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