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