Commit | Line | Data |
---|---|---|
8736538c AS |
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. | |
5aabfad6 | 4 | |
8736538c | 5 | =head1 NAME |
5aabfad6 | 6 | |
2c2d71f5 | 7 | README.cygwin - notes about porting Perl to Cygwin |
5aabfad6 | 8 | |
8736538c | 9 | =head1 SYNOPSIS |
5aabfad6 | 10 | |
8736538c | 11 | =over |
5aabfad6 | 12 | |
2c2d71f5 | 13 | =item Cygwin |
5aabfad6 | 14 | |
1cab015a | 15 | The Cygwin tools are ports of the popular GNU development tools for |
8736538c AS |
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. | |
1cab015a | 18 | More info about this project can be found at its home page |
8736538c | 19 | http://sourceware.cygnus.com/cygwin/ |
5aabfad6 | 20 | |
f89d6eaa | 21 | =item libperl.dll |
8736538c | 22 | |
2c2d71f5 | 23 | These instructions and the default cygwin hints build a shared |
f89d6eaa | 24 | libperl.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 | 36 | The latest stable Cygwin suite is beta20.1. It may be |
8736538c AS |
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 | ||
f89d6eaa | 42 | This port was built with egcs-1.1.2 downloaded from |
8736538c AS |
43 | ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin/egcs-1.1.2/ |
44 | ||
f89d6eaa | 45 | =item install executable |
8736538c | 46 | |
f89d6eaa EF |
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 | |
1cab015a EF |
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 | |
8736538c AS |
153 | |
154 | =item crypt library | |
155 | ||
f89d6eaa EF |
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/ | |
8736538c | 160 | |
1cab015a EF |
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 | ||
8736538c AS |
208 | =back |
209 | ||
210 | =head2 Configure | |
211 | ||
2c2d71f5 | 212 | Check hints/cygwin.sh for any system specific settings. In |
1cab015a EF |
213 | particular change libpth to point to the correct location of |
214 | ...../i586-cygwin32/lib. | |
f89d6eaa | 215 | |
8736538c AS |
216 | run "sh Configure". |
217 | ||
218 | When confronted with this prompt: | |
219 | ||
220 | =begin text | |
5aabfad6 | 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 | ||
2c2d71f5 | 231 | select "cygwin". |
8736538c | 232 | |
f89d6eaa EF |
233 | Do not use the malloc that comes with perl--using the perl malloc |
234 | collides with some cygwin startup routines. | |
8736538c AS |
235 | |
236 | =head2 make | |
237 | ||
1cab015a EF |
238 | Run "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 EF |
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. | |
8736538c AS |
331 | |
332 | =head1 BUGS | |
333 | ||
f89d6eaa EF |
334 | A lot of warnings about incompatible pointer types and comparison |
335 | lacking a cast. This is because of __declspec(dllimport). | |
8736538c | 336 | |
f89d6eaa EF |
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 | |
1cab015a EF |
339 | symbols from there. According to alex smishlajev, there seems to be |
340 | no better solution than adding an explicit define to the rule. | |
8736538c | 341 | |
f89d6eaa | 342 | make clean does not remove library .def and .exe.core files. |
8736538c | 343 | |
f89d6eaa | 344 | ld2 script is installed with reference to source directory. You should |
8736538c AS |
345 | change 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 | 351 | alexander smishlajev <als@turnhere.com> |
5aabfad6 | 352 | |
8736538c | 353 | =head1 DISCLAIMER |
5aabfad6 | 354 | |
1cab015a | 355 | I (alex) am not going to maintain this document or this port. I only wanted |
f89d6eaa | 356 | to make perl porting a bit easier. If failed, I can't be helpful for you. |
1cab015a | 357 | Contact one of the others listed in the history section. |
5aabfad6 | 358 | |
8736538c | 359 | =head1 HISTORY |
5aabfad6 | 360 | |
1cab015a EF |
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 | |
5aabfad6 | 421 | |
1cab015a EF |
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 | |
f89d6eaa | 425 | |
1cab015a EF |
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 | |
f89d6eaa | 504 | |
8736538c | 505 | =cut |