Zero out high bytes of 80-bit ldnan
[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. As dist/meta binaries are now included in the git chackout,
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
44     The dist version used for perl is dist-3.5-20 in this directory, which is
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:
49
50     $ git clone https://github.com/rmanfredi/dist.git dist-git
51
52     Unsurprisingly 'dist' uses (its) Configure to generate itself:
53
54     $ cd dist-3.5-20    # or dist-git
55     $ chmod -R +w .     # We have derived files in git :-(
56     $ ./Configure
57     $ make
58     $ make install
59
60     After make install, remove lib/U/d_debugging.U in your target lib, as perl
61     uses its own way to set/define debugging (see INSTALL)
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.
67
68     There are some perl specific "dist units" in the 'U' directory.
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
74 (aa)
75
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:
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
94     I also added the first two lines of that patch to mlint
95
96 (b) You need to be in a/the Perl directory, i.e. either something from
97     //depot/perl/... or one of its branches
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
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 metalint (or mlint) to see nits: as opposed to lint, the gripings
111     of metalint are usually serious :-) and need fixing
112
113     Exceptions are lots of
114       Your private U/modified/issymlink.U overrides the public one.
115     due to the perl special units
116
117     an alias to something like
118     $ metalint      |& grep -v -e '^    Your private U/'
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)
123
124     and
125
126     "End.U": stale ?MAKE: dependency '$W'.
127
128     which is apparently normal ...
129
130 -- the next steps are in the perl folder
131
132 (e) chmod +w Configure config_h.SH
133
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.
139
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
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)
156
157     For Win32 the process is semi-automated - if you have a Win32
158     machine to run dmake on ...
159
160 (i) Edit U/mkglossary (right near the top) to point to where you keep
161     dist's standard metaconfig units as well as your perl-specific ones.
162
163 (j) Run U/mksample to freshen the Porting/config* and Porting/Glossary.
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.
167
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
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"
192
193 (n) When all patches are applied, tested and committed, and you are happy,
194     git push
195
196     Merijn prefers to do steps (l) through (n) in git-gui