Add probe for gai_strerror
[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 git://perl5.git.perl.org/metaconfig.git metaconfig
16
17 or some other way to obtain this file, like a complete compressed archive
18 from the previous pumpkin.
19
20 Normally this directory and perl directory are next to each other
21 so ../perl will get you to perl and ../perl/../metaconfig will get you
22 back here.
23
24 Contents of this directory:
25
26     README:     This file.
27     U:          Metaconfig units used for building Perl's Configure
28     U.check:    Sample directory used for testing new metaconfig units.
29                 see U.check/README for more information.
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
33     dist:
34                 a symlink to the lib you actually use. For Merijn that is
35                 metaconfig/dist -> ../lib/dist
36
37 (a) You need to have dist installed so that you have metalint and metaconfig
38     in your $PATH.
39     The dist version used for perl is dist-3.5-20 in this directory, which is
40     a slightly modified version of the original, which you can get at GITHUB
41     repository https://github.com/rmanfredi/dist.git. If you'd like to keep
42     up to date with changes in dist, you can use git to create your own clone.
43     For git, that would be something like:
44
45     $ git clone https://github.com/rmanfredi/dist.git dist-git
46
47     Unsurprisingly 'dist' uses (its) Configure to generate itself:
48
49     $ cd dist-3.5-20    # or dist-git
50     $ chmod -R +w .     # We have derived files in git :-(
51     $ ./Configure
52     $ make
53     $ make install
54
55     After make install, remove lib/U/d_debugging.U in your target lib, as perl
56     uses its own way to set/define debugging (see INSTALL)
57
58     the dist-3.5-20 installation as used by Merijn is available on his CPAN as
59     perl-meta-3.5-20.tgz
60
61     dist's 'Configure' is similar to perl's but perhaps not quite as polished.
62
63     There are some perl specific "dist units" in the 'U' directory.
64     The U directory also contains some patches to 'dist' which have already
65     been applied to dist-3.5-20 directory.
66     We have not yet arranged for metaconfig to use perl's versions of the
67     'units' by default so you need some housekeeping in the perl directory...
68
69 (aa)
70
71     If you plan to make changes to mconfig or mlint locally (and you probably
72     want to, as both are written for perl4), consider installing mconfig and
73     mlint from the cmon subdirectory into your $PATH too. These are the
74     non-autoloading versions and can easily be changed. Here is what I added
75     at the beginning of mconfig:
76
77     --8<---
78     BEGIN { $ENV{LC_ALL} = "C"; }
79     chdir "/pro/3gl/CPAN/perl";
80     {   my @Cc = qw( Configure config_h.SH );
81         system "chown merijn @Cc";
82         chmod 0775, @Cc;
83         #-d "merijn" or mkdir "merijn";
84         #system "cp -f Configure config_h.SH Porting/Glossary Porting/config.sh merijn/";
85         system "ls", "-l", @Cc;
86         }
87     -->8---
88
89     I also added the first two lines of that patch to mlint
90
91 (b) You need to be in a/the Perl directory, i.e. either something from
92     //depot/perl/... or one of its branches
93     (e.g. Nick I-S is usually in //depot/perlio/...)
94     and you need:
95      1) have a symlink to ../metaconfig/U called U
96      2) have a symlink to ../metaconfig/.package called .package
97      3) have a symlink to MANIFEST called MANIFEST.new
98      4) chmod +w Configure config_h.SH Porting/Glossary Porting/config*
99
100 (c) Write the new unit as U/perl/d_bar.U ('perl' can also be 'modified',
101     'compline' or any other existing folder, except for 'all'). Choose
102     the best appropriate subdir of U.  See U/README for a description of
103     the various subdirectories.)
104
105 (d) Run metalint (or mlint) to see nits: as opposed to lint, the gripings
106     of metalint are usually serious :-) and need fixing
107
108     Exceptions are lots of
109       Your private U/modified/issymlink.U overrides the public one.
110     due to the perl special units
111
112     an alias to something like
113     $ metalint      |& grep -v -e '^    Your private U/'
114     will make the process silence up on that (of course you can add an
115     option to mlint to disable that warning (which is already disabled
116     by the undocumented and forgotten -s option, but that also suppresses
117     other warnings)
118
119     and
120
121     "End.U": stale ?MAKE: dependency '$W'.
122
123     which is apparently normal ...
124
125 -- the next steps are in the perl folder
126
127 (e) chmod +w Configure config_h.SH
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     perl Porting/config_h.SH
139
140     will fix the ordering
141     
142 (h) The messy not-yet-automated part is that the knowledge of the new symbol
143     needs to be propagated to non-Configure lands like Win32, WinCE, Netware,
144     VMS, VOS, EPOC, ...  see previous Configure changes to see which are these
145     heathen lands.  Files to take care of are
146     {win32,wince,NetWare}/config_[hH]*, (Win32, WinCE, NetWare),
147     configure.com (VMS), VOS/config* (since 5.9 VOS uses Configure, though),
148     epoc/config.sh (EPOC).  Depending on the kind of patch djgpp/config*
149     might also need adjusting (for example when adding/changing the list
150     of extensions)
151
152     For Win32 the process is semi-automated - if you have a Win32
153     machine to run dmake on ...
154
155 (i) Edit U/mkglossary (right near the top) to point to where you keep
156     dist's standard metaconfig units as well as your perl-specific ones.
157
158 (j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
159     Adjust the various compile-time options (e.g. 64bit, threads) as
160     you see fit.
161     You can skip this phase, it's not essential, just good housekeeping.
162
163 (k) Run the perl build chain
164
165     make veryclean
166     sh ./Configure -des -Dusedevel
167
168     The dependency for uconfig.h isn't carved in stone, so you might
169     need to regenerate it
170
171     perl regen/uconfig_h.pl
172
173     Then make and make test or make test_harness (with TEST_JOBS=5)
174
175     make all test_harness
176
177     Before you start committing, make sure that the other developers
178     are happy and run
179
180     make test_porting
181
182 -- the next steps are in the metaconfig folder again
183
184 (l) git add U/perl/foo/bar.U when you are ready ...
185
186 (m) git commit -m "Your commit description"
187
188 (n) When all patches are applied, tested and committed, and you are happy,
189     git push
190
191     Merijn prefers to do steps (l) through (n) in git-gui