This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update documentation
[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 Normally this directory and perl directory are next to each other
18 so ../perl will get you to perl and ../perl/../metaconfig will get you
19 back here. The current setup will require a symbolic link to the folder
20 where Configure is generated in:
21
22   $ cd metaconfig
23   $ ln -s ../perl perl
24
25 Contents of this directory:
26
27     README:     This file.
28     U:          Metaconfig units used for building Perl's Configure
29     U.check:    Sample directory used for testing new metaconfig units.
30                 see U.check/README for more information.
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
34     dist:
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.
38
39 (a) You need to have dist installed so that you have metalint and metaconfig
40     in your $PATH. As dist/meta binaries are now included in the git checkout,
41     you do NOT need to install dist/meta itself.
42
43     If you also want to play with or compare to the original meta/dist, you
44     can checkout that too.
45
46     The dist version used for perl is dist-3.5-20 in this directory, which is
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:
51
52     $ git clone https://github.com/rmanfredi/dist.git dist-git
53
54     Unsurprisingly 'dist' uses (its) Configure to generate itself:
55
56     $ cd dist-3.5-20    # or dist-git
57     $ chmod -R +w .     # We have derived files in git :-(
58     $ ./Configure
59     $ make
60     $ make install
61
62     After make install, remove lib/U/d_debugging.U in your target lib, as perl
63     uses its own way to set/define debugging (see INSTALL)
64
65     dist's 'Configure' is similar to perl's but perhaps not quite as polished.
66
67     There are some perl specific "dist units" in the 'U' directory.
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
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
82 (aa)
83
84     If you plan to make changes to mconfig or mlint locally (and you might
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
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:
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
97      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
98
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.)
103
104 (d) Run "mlint -O" to see nits: as opposed to lint, the gripings of mlint
105     are usually serious and need fixing
106
107     Without -O, exceptions are lots of
108       Your private U/modified/issymlink.U overrides the public one.
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
117 -- the next steps are in the perl folder
118
119 (e) chmod +w Configure config_h.SH
120
121     mlint and mconfig will probly die when these are read-only
122
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.
128
129 (g) metaconfig does not deal with depends in config_h.SH, so some
130     reorganization is needed.
131
132     $ cd perl
133     $ perl Porting/config_h.SH
134
135     will fix the ordering
136     
137 (h) The messy semi-automated part is that the knowledge of the new symbol
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),
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
156
157     For Win32 the process is semi-automated - if you have a Win32
158     machine to run dmake on ...
159
160 (i) Check if U/mkglossary (right near the top) points to where you keep
161     dist's standard metaconfig units as well as your perl-specific ones.
162
163 (j) Run the perl build chain
164
165     $ cd perl
166     $ make veryclean
167     $ ./Configure -Duse64bitall -Dusethreads -Dusedevel -des
168
169     The dependency for uconfig.h isn't carved in stone, so you might
170     need to regenerate it
171
172     $ perl regen/uconfig_h.pl
173
174     Then make and make test or make test_harness
175
176     $ make -j12
177     $ env TEST_JOBS=13 make test_harness
178
179     Before you start committing, make sure that the other developers
180     are happy and run
181
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
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"
210
211 (n) When all patches are applied, tested and committed, and you are happy,
212     git push