avoid creating new files during make install
[p5sagit/p5-mst-13.2.git] / README.cygwin
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see pod/perlpod.pod) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 README.cygwin - notes about porting Perl to Cygwin
8
9 =head1 SYNOPSIS
10
11 =over
12
13 =item Cygwin
14
15 The Cygwin tools are ports of the popular GNU development tools for
16 Windows NT, 95, and 98.  They run thanks to the Cygwin library which
17 provides the UNIX system calls and environment these programs expect.
18 More info about this project can be found at its home page
19 http://sourceware.cygnus.com/cygwin/
20
21 =item libperl.dll
22
23 These instructions and the default cygwin hints build a shared
24 libperl.dll Perl library and enables dynamically loaded extensions.
25
26 =back
27
28 =head1 BUILDING
29
30 =head2 Prerequisites
31
32 =over
33
34 =item Cygwin b20.1
35
36 The latest stable Cygwin suite is beta20.1.  It may be
37 downloaded from ftp://go.cygnus.com/pub/sourceware.cygnus.com/cygwin/latest/
38 or many mirror sites around the world.
39
40 =item egcs-1.1.2
41
42 This port was built with egcs-1.1.2 downloaded from
43 ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin/egcs-1.1.2/
44
45 =item install executable
46
47 To make life easier, you should download
48 ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Humblet_Pierre_A/install-cygwin-b20.sh,
49 and use it as your install "executable." Just follow the instructions
50 that are embedded as comments in the .sh file.
51
52 =item Windows NT notes
53
54 You should execute a 'chmod -R +w *' on the entire perl source directory. 
55 The configuration process creates new files (and thus needs write access
56 to the directory) and sometimes, especially if you make repeated builds
57 in the same directory, overwrites old files. If you do not enable write
58 access, you're just asking for trouble. Reminder for B20.1: unless 'ntea' 
59 is included in the CYGWIN environment variable settings, chmod has no 
60 effect. See "environment," below.
61
62 It is best if you build, test, and install as a normal user, not as
63 Administrator or as any member of the Administrators group. There is
64 a well-known NT-ism that affects Cygwin: all files that are created
65 by any member of the Administrators B<group> are B<NOT> owned by 
66 that member. The ownership of those files is assigned to the 
67 Administrators group, instead. If the default access mode for new files
68 is -rw-r--r--, then the original creator of the file cannot overwrite 
69 it: he no longer owns the file, no B<user> does. It is owned by the 
70 group, but group members don't have write access to it. This causes 
71 any number of problems, including make test / perl harness failures, 
72 installation failures, etc.
73
74 In some cases, however, it is necessary to install as Administrator. For 
75 instance, if normal users are not allowed write access to the install 
76 directory. My solution, in this case, was to transfer ownership of the 
77 install directory tree (/usr/local) to a single, normal user, and 
78 set permissions to -rw-r--r-- (drwxr-xr-x for directories, of course). 
79 If you read the preceeding paragraph carefully, you might suspect that 
80 changing the permissions on the entire tree to -rw-rw-r--, but allowing 
81 the Administrators group to keep ownership should solve the problem. 
82 However, newly created directories (and the perl install creates a lot 
83 of them) will not allow group write access. Setting umask will not 
84 fix this problem, because umask is a B<negation> operator; it only 
85 specifies the types of accesses that will NOT be allowed on new files. 
86 For instance, umask u=rwx,g=rwx,o=rx means that world ('B<o>thers') will 
87 never be allowed write access, but owner ('B<u>ser') and B<g>roup B<might> 
88 be allowed write access. Everybody (u, g, and o) B<might>be allowed 
89 read access.
90
91 In any case, Corinna Vinschen's ntsec patches B<may> eventually 
92 alleviate this whole mess, and are included in the development 
93 snapshots as of 24 May 1999. You will need to include 'ntsec' as 
94 one of the items in the CYGWIN variable setting. However, initial 
95 tests indicate some incompatibility the 0524 snapshot and this perl
96 build.
97
98 =item environment
99
100 I (csw) found the following steps necessary for a successful build:
101
102 =over
103
104 =item path
105
106 I set my path so that none of the windows directories showed up -
107 otherwise Configure found the wrong executables (find, grep, etc).
108 It is, however, important that '.' be in the path, because otherwise
109 the build process can't execute the ld2 script that is created.
110
111 =item mounts
112
113 I had to unmount my f: drive. I have cygwin installed under 
114 F:\cygnus\cygwin-b20\, which is mounted as \. I also ordinarily 
115 have F:\ mounted as /f (i.e. mounted onto the empty directory 
116 F:\cygnus\cygwin-b20\f\ ). However, this causes Configure to 
117 "locate" the awk, tr, sed, etc. programs at 
118 /f/cygnus/cygwin-b20/usr/bin instead of /usr/bin. 
119 This ended up causing problems.
120
121 I built and tested perl using all binary mounts. However, Eric Fifer 
122 has built and tested it using text mounts, but reported more failures
123 during make test and perl harness. Based on his findings, and experiments
124 performed by Sebastien Barre with the static build of perl, I can 
125 report that these test failures are B<not> due to any differences in
126 the perl executable. Most of the failures encountered during a make test
127 on text mounts can be eliminated by remounting as binary, and re-running
128 the tests using the same executable. These test failures are due to 
129 problems in the test scripts, not the executable. See Appendix.
130
131 One observation from experience with the static build of perl is that
132 it's a bad idea to a mix a perl executable that was compiled using binary
133 mounts with modules compiled using text mounts, and vice versa. Make
134 sure your mount environment matches. This observation has not been
135 confirmed with respect to the dynamically linked build of perl. 
136
137 =item environment variables
138
139 For NT users, the CYGWIN variable should include the 'ntea' setting. 
140 However, if you have FAT drives on your system, as opposed to NTFS, 
141 please read the Cygwin FAQ concerning ntea before including it in 
142 your system settings. If you do not use ntea, you will encounter a 
143 few extra make test and/or perl harness failures. These are not 
144 indicative of a faulty perl executable, but only that your system 
145 settings do not allow the types of file access and ownership checking 
146 that the test scripts are attempting to verify. See Appendix.
147
148 I unset INCLUDE and LIB (these two variables are set by MSVC5, and 
149 inherited from my Windows environment by cygwin). I'm not sure this made 
150 a difference, but it has caused problems in the past...
151
152 =back
153
154 =item crypt library
155
156 http://miracle.geol.msu.ru/sos/ points to two different crypt
157 libraries ported to cygwin.  This has been tested with the libcrypt.tgz
158 by Andy Piper. His home page can be found at
159 http://www.xemacs.freeserve.co.uk/
160
161 =item hacks that should be revisited after the next cygwin release
162
163 Some of the failures we encountered when running make test and/or perl harness
164 are due to bugs in the cygwin b20.1 distribution. We sometimes found it
165 necessary to use dirty little hacks to persuade make test and perl harness
166 to play nicely. Since cygwin is in active development, many of these hacks 
167 may not be necessary in the future. These include:
168
169 =over
170
171 =item fix for pragma/locale
172
173 the line '#undef MB_CUR_MAX' was added to ex/POSIX/POSIX.xs. This fixes
174 a failure in the pragma/locale.t test, which before this fix resulted in a 
175 coredump. It appears that MB_CUR_MAX is #defined __mb_cur_max, and __mb_cur_max
176 is declared 'extern' in Cygwin b20.1's stdlib.c, but is never defined. Thus,
177 the error.
178
179 =item fix for lib/io_sock
180
181 there is a rather extensive patch to t/lib/io_sock.t which works around
182 a failure related to fork() in the cygwin environment. Cygwin b20.1 does not 
183 properly remap manually loaded DLLs in the child after a fork.
184
185 =item fix for lib/filehand
186
187 during the make test/perl harness steps, a win32 popup complains about 
188 a "perl.exe Application Error - illegal memory access." This is due to to
189 a test in t/lib/filehand.t, and is related to the fork + dll problem.
190
191 =item fix for environ
192
193 there are a number of changes to miniperlmain.c, util.c, and mg.c that
194 are there to work around a Cygwin problem relating to environ.
195
196 =item fix for lib/posix
197
198 the following line was added to t/lib/posix.t to work around a Cygwin bug.
199
200 =begin text
201
202 kill 'CONT', $$ if($^O =~ /cygwin/); # XXX: Cygwin bug INT signal gets stuck
203
204 =end text
205
206 =back
207
208 =back
209
210 =head2 Configure
211
212 Check hints/cygwin.sh for any system specific settings.  In
213 particular change libpth to point to the correct location of
214 ...../i586-cygwin32/lib.
215
216 run "sh Configure".  
217
218 When confronted with this prompt:
219
220 =begin text
221
222         First time through, eh?  I have some defaults handy for the
223         following systems:
224            .
225            .
226            .
227         Which of these apply, if any?
228
229 =end text
230
231 select "cygwin".
232
233 Do not use the malloc that comes with perl--using the perl malloc
234 collides with some cygwin startup routines. 
235
236 =head2 make
237
238 Run "make". If you're really feeling adventurous, type 
239 "make 2>&1 | tee make-log.txt".
240
241 =over
242
243 =item ld2
244
245 The make script will install ld2 into your $installbin directory (i.e.
246 wherever you said to put the perl.exe) during the *make* process. It 
247 does not wait until the *make install* process to install the ld2 script.
248 This is because the remainder of the make refers to ld2 without fully
249 specifying its path, and does this from multiple subdirectories (so ./ld2
250 won't work.) The assumption here is that $installbin is in your current
251 $PATH. If this is not the case, or if you do not have an install 
252 executable, the make will fail at some point. Don't panic. Just manually
253 copy ld2 from the source directory to someplace in your path.
254
255 This cannot be done prior to make, because ld2 is created during the
256 make process.
257
258 =back
259
260 =head2 make test
261
262 Run "make test" to see how stable your system is. I (csw) got the 
263 following errors/warnings:
264
265 =over
266
267 =item op/taint
268
269 Got two "missing cygwin1.dll" warning popups. This is because
270 op/taint wants cygwin1.dll to be somewhere in the system path 
271 (\WINDOWS\SYSTEM, etc) or in the build directory. Can be ignored.
272
273 =item lib/filehand
274
275 Got an "Application Error - memory could not be read" popup. While 
276 this looks alarming, it can be ignored - just click OK. It is 
277 because Cygwin B20.1 doesn't properly remap manually loaded DLLs 
278 in the child after a fork.
279
280 =item lib/io_sock
281
282 Got an "Application Error - memory could not be read" popup. Again,
283 just click OK and ignore it.
284
285 =back
286
287 =head2 perl harness
288
289 Once you've run make test, then cd into the t/ subdirectory and
290 execute './perl harness'. I (csw) got the following results:
291
292 =over
293
294 =item op/taint
295
296 Got four "missing cygwin1.dll" warning popups. Click OK and
297 ignore.
298
299 =item lib/filehand
300
301 Got an "Application Error - memory could not be read" popup. Again,
302 click OK and ignore.
303
304 =item lib/io_sock
305
306 Got an "Application Error - memory could not be read" popup. Again,
307 clock OK and ignore.
308
309 =item final results
310
311 After the ./perl harness, I got the following results summary.
312
313  Failed Test  Status Wstat Total Fail  Failed  List of failed
314  -------------------------------------------------------------------------------
315  op/taint.t                  149    3   2.01%  1, 3, 31
316  9 tests skipped, plus 35 subtests skipped.
317  Failed 1/190 test scripts, 99.47% okay. 3/6452 subtests failed, 99.95% okay.
318
319 =back
320
321 =head2 make install
322
323 Finally, run "make install". In my case, the install process was unable
324 to copy the files from <SRCDIR>/pod/* to /usr/local/lib/perl5/5.00503/pod/.
325 I (csw) just copied them by hand after the install finished. I believe
326 this is because I'm using Sergey Okhapkin's coolview version of the
327 cygwin1.dll, which provides case sensitivity. The directory is created
328 as "/usr/local/lib/perl5/5.00503/Pod" but the copy is done into
329 "/usr/local/lib/perl5/5.00503/pod". This fails -- but probably won't 
330 fail if you're using the default cygwin1.dll.
331
332 =head1 BUGS
333
334 A lot of warnings about incompatible pointer types and comparison
335 lacking a cast.  This is because of __declspec(dllimport).
336
337 Upon each start, make warns that a rule for perlmain.o is overrided.
338 Yes, it is.  In order to use libperl.dll, perlmain needs to import
339 symbols from there.  According to alex smishlajev, there seems to be 
340 no better solution than adding an explicit define to the rule.
341
342 make clean does not remove library .def and .exe.core files.
343
344 ld2 script is installed with reference to source directory.  You should
345 change this to /usr/local/bin (or whatever) after install.
346
347 .bat wrappers for installed utility scripts are not made during installation.
348
349 =head1 AUTHOR
350
351 alexander smishlajev <als@turnhere.com>
352
353 =head1 DISCLAIMER
354
355 I (alex) am not going to maintain this document or this port.  I only wanted
356 to make perl porting a bit easier.  If failed, I can't be helpful for you.
357 Contact one of the others listed in the history section.
358
359 =head1 HISTORY
360
361 =over
362
363 =item Release 1.4.1: 28-May-1999
364
365 Charles Wilson  -  cwilson@ece.gatech.edu
366
367    Configure               minor fix for spaces in $PATH
368    documentation updates
369
370 =item Release 1.4: 26-May-1999
371
372 Charles Wilson  -  cwilson@ece.gatech.edu
373
374  From Eric Fifer:
375    hints/cygwin32.sh       -L. and --export-dynamic not needed
376    cygwin32/Makefile.SHs   no value needed for -DUSEIMPORTLIB
377    t/lib/io_sock.t         -I../lib so "make test" works
378    t/lib/posix.t           workaround a Cygwin bug so test works
379    doio.c/perl.h           cleanup gcc warning "doio.c:789: warning:
380                                 pointer/integer type mismatch in 
381                                 conditional expression"
382  From Charles Wilson:
383    Configure               changes to findhdr script
384    documentation updates
385    built binary kit for release
386
387 =item Release 1.3: 26-May-1999
388
389 Charles Wilson  -  cwilson@ece.gatech.edu
390
391  Changes to Cwd.pm to correct lib/findbin.t test failure from Eric Fifer
392  Changes to t/op/magic.t to correct a test failure from Eric Fifer
393  Changes to miniperlmain.c, util.c, and mg.c to correct t/op/magic.t #29
394     test failure, from Eric Fifer
395  more documentatino updates, patch merging, and a change to 
396     cygwin/Makefile.SHs -- cw.
397  99.95% okay!!!
398
399 =item Release 1.2: 25-May-1999
400
401 Charles Wilson  -  cwilson@ece.gatech.edu
402
403  fixes for lib/io_sock and pragma/locale from Eric Fifer
404  fixes for Configure, Makefile.SH, and cygwin32/Makefile.SHs from
405     alex smishlajev
406  documentation updates, and other fixes to the fixes from cw.
407  99.91% okay!!!
408
409 =item Release 1.1: 21-May-1999
410
411 Charles Wilson  -  cwilson@ece.gatech.edu
412
413 minor change to Configure script, reversed a few changes made by
414 alexander's patch (made DOSISH #undefined again) and moved code
415 by alexander from dosish.h to perl.h. Reversed a change in 
416 pp_hot.c
417
418 =item Release 1.0: 16-May-1999
419
420 Charles Wilson  -  cwilson@ece.gatech.edu
421
422 Merged alexander's patch and Eric's patch into a single
423 monolithic patch. Minor cleanup. Built binary for distribution.
424 perl5.005_03-dynamic-patch-v1.0
425
426 =item Pre-release 3: 12-May-1999 
427
428 Eric Fifer  -  efifer@sanwaint.com
429
430 Removed all references to the impure_ptr hack since it is no longer
431 needed.  Some minor cleanup of alexander smishlajev's work and a few
432 bug fixes.
433
434 =item Pre-release 2 (initial dynamic build): 17..25-apr-1999
435
436 alexander smishlajev  -  als@turnher.com
437
438 perl 5.005_03.  cygwin b20.1  egcs 1.1.2.  far 1.60.  nescafe classic.
439
440 =item Pre-release 1 (static build): 5-Mar-1999
441
442 Charles Wilson  -  cwilson@ece.gatech.edu
443
444 Collected various patches that had been floating around the net, along
445 with build instructions.  Original authorship credit for those patches
446 goes to:
447
448  Steven Morlock  -  newspost@morlock.net
449  Sebastien Barre -  Sebastien.Barre@utc.fr
450  Teun Burgers    -  burgers@ecn.nl
451
452 Created a monolithic patchkit (perl5.005_03-static-patch) and build
453 instructions for cygwin (beta 20.1). Also created a binary distribution
454 of the resulting static perl build.
455
456 =back
457
458 =head1 APPENDIX
459
460 Perl harness results from Eric Fifer, under various environments. The same
461 executable was used in all cases. The last item is a different executable
462 on a different machine, built by Charles Wilson.
463
464 There are a number of very good questions one could ask about anomalies 
465 in the test results presented below. "Why do the last two show different
466 results?" "Why did op/stat.t #18 pass in the first two tests and fail in
467 the third?" Short answer: I don't know. Long answer: I really have no
468 idea.
469
470 =over
471
472 =item text mounts, no 'ntea'
473
474  Failed Test  Status Wstat Total Fail  Failed  List of failed
475  ------------------------------------------------------------
476  lib/anydbm.t      2   512    12    8  66.67%  5-12
477  lib/sdbm.t        2   512    18   15  83.33%  2, 5-18
478  op/split.t                   25    1   4.00%  11
479  op/stat.t                    58    3   5.17%  9, 19, 26
480  op/taint.t                  149    3   2.01%  1, 3, 31
481
482 =item binary mounts, no 'ntea'
483
484  Failed Test  Status Wstat Total Fail  Failed  List of failed
485  ------------------------------------------------------------
486  lib/sdbm.t                   18    1   5.56%  2
487  op/stat.t                    58    3   5.17%  9, 19, 26
488  op/taint.t                  149    3   2.01%  1, 3, 31
489
490 =item binary mounts, 'ntea'
491
492  Failed Test  Status Wstat Total Fail  Failed  List of failed
493  ------------------------------------------------------------
494  op/stat.t                    58    3   5.17%  18-19, 26
495  op/taint.t                  149    3   2.01%  1, 3, 31
496
497 =item binary mounts, ntea (csw build)
498
499  Failed Test  Status Wstat Total Fail  Failed  List of failed
500  -------------------------------------------------------------------------------
501  op/taint.t                  149    3   2.01%  1, 3, 31
502
503 =back
504
505 =cut