Penguin
Recent Changes
Blame: perlcygwin(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of perlcygwin(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLCYGWIN
2 !!!PERLCYGWIN
3 NAME
4 SYNOPSIS
5 PREREQUISITES
6 CONFIGURE
7 MAKE
8 TEST
9 INSTALL
10 MANIFEST
11 BUGS
12 AUTHORS
13 HISTORY
14 ----
15 !!NAME
16
17
18 README .cygwin - Perl for Cygwin
19 !!SYNOPSIS
20
21
22 This document will help you configure, make, test and
23 install Perl on Cygwin. This document also describes
24 features of Cygwin that will affect how Perl behaves at
25 runtime.
26
27
28 __NOTE:__ There are pre-built Perl packages
29 available for Cygwin and a version of Perl is provided on
30 the Cygwin CD . If you do not need to customize
31 the configuration, consider using one of these
32 packages:
33
34
35 http://cygutils.netpedia.net/
36 !!PREREQUISITES
37
38
39 __Cygwin = GNU+Cygnus+Windows (Don't leave__
40 __UNIX without it)__
41
42
43 The Cygwin tools are ports of the popular GNU
44 development tools for Win32 platforms. They run thanks
45 to the Cygwin library which provides the UNIX
46 system calls and environment these programs expect.
47 More information about this project can be found
48 at:
49
50
51 http://www.cygwin.com/
52 A recent net or commercial release of Cygwin is required.
53
54
55 At the time this document was last updated, Cygwin
56 1.1.5 was current.
57
58
59 __NOTE:__ At this point, minimal effort has been
60 made to provide compatibility with old (beta) Cygwin
61 releases. The focus has been to provide a high quality
62 release and not worry about working around old bugs. If you
63 wish to use Perl with Cygwin B20.1 or earlier, consider
64 using perl5.005_03, which is available in source and binary
65 form at http://cygutils.netpedia.net/. If there is
66 significant demand, a patch kit can be developed to port
67 back to earlier Cygwin versions.
68
69
70 __Cygwin Configuration__
71
72
73 While building Perl some changes may be necessary to
74 your Cygwin setup so that Perl builds cleanly. These changes
75 are __not__ required for normal Perl
76 usage.
77
78
79 __NOTE:__ The binaries that are built will run on
80 all Win32 versions. They do not depend on your host system
81 (Win9x/WinME, WinNT/Win2K) or your Cygwin configuration
82 (''ntea'', ''ntsec'', binary/text mounts). The only
83 dependencies come from hard-coded pathnames like
84 /usr/local. However, your host system and Cygwin
85 configuration will affect Perl's runtime behavior (see
86 `` TEST '').
87
88
89 PATH
90
91
92 Set the PATH environment variable so that
93 Configure finds the Cygwin versions of programs. Any Windows
94 directories should be removed or moved to the end of your
95 PATH.
96
97
98 ''nroff''
99
100
101 If you do not have ''nroff'' (which is part of the
102 ''groff'' package), Configure will __not__ prompt you
103 to install ''man'' pages.
104
105
106 Permissions
107
108
109 On WinNT with either the ''ntea'' or ''ntsec''
110 CYGWIN settings, directory and file permissions may
111 not be set correctly. Since the build process creates
112 directories and files, to be safe you may want to run a
113 `chmod -R +w *' on the entire Perl source
114 tree.
115
116
117 Also, it is a well known WinNT ``feature'' that files
118 created by a login that is a member of the
119 ''Administrators'' group will be owned by the
120 ''Administrators'' group. Depending on your umask, you
121 may find that you can not write to files that you just
122 created (because you are no longer the owner). When using
123 the ''ntsec'' CYGWIN setting, this is not an
124 issue because it ``corrects'' the ownership to what you
125 would expect on a UNIX system.
126 !!CONFIGURE
127
128
129 The default options gathered by Configure with the
130 assistance of ''hints/cygwin.sh'' will build a Perl that
131 supports dynamic loading (which requires a shared
132 ''libperl.dll'').
133
134
135 This will run Configure and keep a
136 record:
137
138
139 ./Configure 2
140 If you are willing to accept all the defaults run Configure with __-de__. However, several useful customizations are available.
141
142
143 __Strip Binaries__
144
145
146 It is possible to strip the EXEs and DLLs created by
147 the build process. The resulting binaries will be
148 significantly smaller. If you want the binaries to be
149 stripped, you can either add a __-s__ option when
150 Configure prompts you,
151
152
153 Any additional ld flags (NOT including libraries)? [[none] -s
154 Any special flags to pass to gcc to use dynamic linking? [[none] -s
155 Any special flags to pass to ld2 to create a dynamically loaded library?
156 [[none] -s
157 or you can edit ''hints/cygwin.sh'' and uncomment the relevant variables near the end of the file.
158
159
160 __Optional Libraries__
161
162
163 Several Perl functions and modules depend on the
164 existence of some optional libraries. Configure will find
165 them if they are installed in one of the directories listed
166 as being used for library searches. Pre-built packages for
167 most of these are available at
168 http://cygutils.netpedia.net/.
169
170
171 -lcrypt
172
173
174 The crypt package distributed with Cygwin is a Linux
175 compatible 56-bit DES crypt port by Corinna
176 Vinschen.
177
178
179 Alternatively, the crypt libraries in GNU
180 libc have been ported to Cygwin.
181
182
183 The DES based Ultra Fast Crypt port was done
184 by Alexey Truhan:
185
186
187 ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz
188 NOTE: There are various export restrictions on DES implementations, see the glibc README for more details.
189
190
191 The MD5 port was done by Andy
192 Piper:
193
194
195 ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz
196
197
198 -lgdbm (use GDBM_File)
199
200
201 GDBM is available for Cygwin. GDBM 's
202 ndbm/dbm compatibility feature also makes NDBM_File
203 and ODBM_File possible (although they add little
204 extra value).
205
206
207 NOTE: The ndbm/dbm emulations only completely work
208 on NTFS partitions.
209
210
211 -ldb (use DB_File)
212
213
214 BerkeleyDB is available for Cygwin. Some details can be
215 found in ''ext/DB_File/DB_File.pm''.
216
217
218 NOTE: The BerkeleyDB library only completely works
219 on NTFS partitions.
220
221
222 -lcygipc (use
223 IPC::SysV)
224
225
226 A port of SysV IPC is available for
227 Cygwin.
228
229
230 NOTE: This has __not__ been extensively tested. In
231 particular, d_semctl_semun is undefined because it
232 fails a Configure test and on Win9x the ''shm*()''
233 functions seem to hang. It also creates a compile time
234 dependency because ''perl.h'' includes
235 ''''''''
236 '' CPAN
237 modules).
238
239
240 __Configure-time Options__
241
242
243 The ''INSTALL'' document describes
244 several Configure-time options. Some of these will work with
245 Cygwin, others are not yet possible. Also, some of these are
246 experimental. You can either select an option when Configure
247 prompts you or you can define (undefine) symbols on the
248 command line.
249
250
251 -Uusedl
252
253
254 Undefining this symbol forces Perl to be compiled
255 statically.
256
257
258 -Uusemymalloc
259
260
261 By default Perl uses the ''malloc()'' included with
262 the Perl source. If you want to force Perl to build with the
263 system ''malloc()'' undefine this
264 symbol.
265
266
267 -Dusemultiplicity
268
269
270 Multiplicity is required when embedding Perl in a C
271 program and using more than one interpreter instance. This
272 works with the Cygwin port.
273
274
275 -Duseperlio
276
277
278 The PerlIO abstraction works with the Cygwin
279 port.
280
281
282 -Duse64bitint
283
284
285 ''gcc'' supports 64-bit integers. However, several
286 additional long long functions are necessary to use them
287 within Perl (''{strtol,strtoul}l''). These are __not__
288 yet available with Cygwin.
289
290
291 -Duselongdouble
292
293
294 ''gcc'' supports long doubles (12 bytes). However,
295 several additional long double math functions are necessary
296 to use them within Perl
297 (''{atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold'').
298 These are __not__ yet available with
299 Cygwin.
300
301
302 -Dusethreads
303
304
305 POSIX threads are __not__ yet implemented in
306 Cygwin.
307
308
309 -Duselargefiles
310
311
312 Although Win32 supports large files, Cygwin currently
313 uses 32-bit integers for internal size and position
314 calculations.
315
316
317 __Suspicious Warnings__
318
319
320 You may see some messages during Configure that seem
321 suspicious.
322
323
324 ''dlsym()''
325
326
327 ''ld2'' is needed to build dynamic libraries, but it
328 does not exist when ''dlsym()'' checking occurs (it is
329 not created until `make' runs). You will see the
330 following message:
331
332
333 Checking whether your dlsym() needs a leading underscore ...
334 ld2: not found
335 I can't compile and run the test program.
336 I'm guessing that dlsym doesn't need a leading underscore.
337 Since the guess is correct, this is not a problem.
338
339
340 Win9x and d_eofnblk
341
342
343 Win9x does not correctly report EOF with a
344 non-blocking read on a closed pipe. You will see the
345 following messages:
346
347
348 But it also returns -1 to signal EOF, so be careful!
349 WARNING: you can't distinguish between EOF and no data!
350 *** WHOA THERE!!! ***
351 The recommended value for $d_eofnblk on this machine was
352 At least for consistency with WinNT, you should keep the recommended value.
353
354
355 Compiler/Preprocessor defines
356
357
358 The following error occurs because of the Cygwin
359 #define of
360 _LONG_DOUBLE:
361
362
363 Guessing which symbols your C compiler and preprocessor define...
364 try.c:
365 This failure does not seem to cause any problems.
366 !!MAKE
367
368
369 Simply run ''make'' and wait:
370
371
372 make 2
373
374
375 __Warnings__
376
377
378 Warnings like these are normal:
379
380
381 warning: overriding commands for target
382 dllwrap: no export definition file provided
383 dllwrap: creating one, but that may not be what you want
384
385
386 __ld2__
387
388
389 During `make', ''ld2'' will be created and
390 installed in your $installbin directory (where you
391 said to put public executables). It does not wait until the
392 `make install' process to install the ''ld2''
393 script, this is because the remainder of the `make'
394 refers to ''ld2'' without fully specifying its path and
395 does this from multiple subdirectories. The assumption is
396 that $installbin is in your current PATH.
397 If this is not the case `make' will fail at some
398 point. If this happens, just manually copy ''ld2'' from
399 the source directory to somewhere in your
400 PATH.
401 !!TEST
402
403
404 There are two steps to running the test
405 suite:
406
407
408 make test 2
409 cd t;./perl harness 2
410 The same tests are run both times, but more information is provided when running as `./perl harness'.
411
412
413 Test results vary depending on your host system and
414 your Cygwin configuration. If a test can pass in some Cygwin
415 setup, it is always attempted and explainable test failures
416 are documented. It is possible for Perl to pass all the
417 tests, but it is more likely that some tests will fail for
418 one of the reasons listed below.
419
420
421 __File Permissions__
422
423
424 UNIX file permissions are based on sets of mode bits
425 for {read,write,execute} for each {user,group,other}. By
426 default Cygwin only tracks the Win32 read-only attribute
427 represented as the UNIX file user write bit
428 (files are always readable, files are executable if they
429 have a ''.{com,bat,exe}'' extension or begin with
430 #!, directories are always readable and
431 executable). On WinNT with the ''ntea'' CYGWIN
432 setting, the additional mode bits are stored as extended
433 file attributes. On WinNT with the ''ntsec''
434 CYGWIN setting, permissions use the standard WinNT
435 security descriptors and access control lists. Without one
436 of these options, these tests will fail:
437
438
439 Failed Test List of failed
440 ------------------------------------
441 io/fs.t 5, 7, 9-10
442 lib/anydbm.t 2
443 lib/db-btree.t 20
444 lib/db-hash.t 16
445 lib/db-recno.t 18
446 lib/gdbm.t 2
447 lib/ndbm.t 2
448 lib/odbm.t 2
449 lib/sdbm.t 2
450 op/stat.t 9, 20 (.tmp not an executable extension)
451
452
453 __Hard Links__
454
455
456 FAT partitions do not support hard links (whereas
457 NTFS does), in which case Cygwin implements
458 ''link()'' by copying the file. On remote (network)
459 drives Cygwin's ''stat()'' always sets st_nlink
460 to 1, so the link count for remote directories and files is
461 not available. In either case, these tests will
462 fail:
463
464
465 Failed Test List of failed
466 ------------------------------------
467 io/fs.t 4
468 op/stat.t 3
469
470
471 __Filetime Granularity__
472
473
474 On FAT partitions the filetime granularity
475 is 2 seconds. The following test will
476 fail:
477
478
479 Failed Test List of failed
480 ------------------------------------
481 io/fs.t 18
482
483
484 __Tainting Checks__
485
486
487 When Perl is running in taint mode, $ENV{PATH}
488 is considered tainted and not used, so DLLs not in the
489 default system directories will not be found. While the
490 tests are running you will see warnings popup from the
491 system with messages like:
492
493
494 Win9x
495 Error Starting Program
496 A required .DLL file, CYGWIN1.DLL, was not found
497 WinNT
498 perl.exe - Unable to Locate DLL
499 The dynamic link library cygwin1.dll could not be found in the
500 specified path ...
501 Just click OK and ignore them. When running `make test', 2 popups occur. During `./perl harness', 4 popups occur. Also, these tests will fail:
502
503
504 Failed Test List of failed
505 ------------------------------------
506 op/taint.t 1, 3, 31, 37
507 Alternatively, you can copy ''cygwin1.dll'' into the directory where the tests run:
508
509
510 cp /bin/cygwin1.dll t
511 or one of the Windows system directories (although, this is __not__ recommended).
512
513
514 __/etc/group__
515
516
517 Cygwin does not require ''/etc/group'', in which
518 case the ''op/grent.t'' test will be skipped. The check
519 performed by ''op/grent.t'' expects to see entries that
520 use the members field, otherwise this test will
521 fail:
522
523
524 Failed Test List of failed
525 ------------------------------------
526 op/grent.t 1
527
528
529 __Script Portability__
530
531
532 Cygwin does an outstanding job of providing UNIX-like
533 semantics on top of Win32 systems. However, in addition to
534 the items noted above, there are some differences that you
535 should know about. This is a very brief guide to
536 portability, more information can be found in the Cygwin
537 documentation.
538
539
540 Pathnames
541
542
543 Cygwin pathnames can be separated by forward (''/'')
544 or backward (''\'') slashes. They may also begin with
545 drive letters (''C:'') or Universal Naming Codes
546 (''//UNC''). DOS device names (''aux'',
547 ''con'', ''prn'', ''com*'', ''lpt?'',
548 ''nul'') are invalid as base filenames. However, they can
549 be used in extensions (e.g., ''hello.aux''). Names may
550 contain all printable characters except
551 these:
552
553
554 : * ?
555 File names are case insensitive, but case preserving. A pathname that contains a backslash or drive letter is a Win32 pathname (and not subject to the translations applied to POSIX style pathnames).
556
557
558 Text/Binary
559
560
561 When a file is opened it is in either text or binary
562 mode. In text mode a file is subject to CR/LF/Ctrl-Z
563 translations. With Cygwin, the default mode for an
564 ''open()'' is determined by the mode of the mount that
565 underlies the file. Perl provides a ''binmode()''
566 function to set binary mode on files that otherwise would be
567 treated as text. ''sysopen()'' with the O_TEXT
568 flag sets text mode on files that otherwise would be treated
569 as binary:
570
571
572 sysopen(FOO,
573 ''lseek()'', ''tell()'' and ''sysseek()'' only work with files opened in binary mode.
574
575
576 The text/binary issue is covered at length in the
577 Cygwin documentation.
578
579
580 ''.exe''
581
582
583 The Cygwin ''stat()'', ''lstat()'' and
584 ''readlink()'' functions make the ''.exe'' extension
585 transparent by looking for ''foo.exe'' when you ask for
586 ''foo'' (unless a ''foo'' also exists). Cygwin does
587 not require a ''.exe'' extension, but ''gcc'' adds it
588 automatically when building a program. However, when
589 accessing an executable as a normal file (e.g., ''cp'' in
590 a makefile) the ''.exe'' is not transparent. The
591 ''install'' included with Cygwin automatically appends a
592 ''.exe'' when necessary.
593
594
595 ''chown()''
596
597
598 On WinNT ''chown()'' can change a file's user and
599 group IDs. On Win9x ''chown()'' is a no-op, although this
600 is appropriate since there is no security
601 model.
602
603
604 Miscellaneous
605
606
607 File locking using the F_GETLK command to
608 ''fcntl()'' is a stub that returns
609 ENOSYS.
610
611
612 Win9x can not ''rename()'' an open file (although
613 WinNT can).
614
615
616 The Cygwin ''chroot()'' implementation has holes (it
617 can not restrict file access by native Win32
618 programs).
619 !!INSTALL
620
621
622 This will install Perl, including ''man''
623 pages.
624
625
626 make install tee log.make-install
627 NOTE: If STDERR is redirected `make install' will __not__ prompt you to install ''perl'' into ''/usr/bin''.
628
629
630 You may need to be ''Administrator'' to run
631 `make install'. If you are not, you must have write
632 access to the directories in question.
633
634
635 Information on installing the Perl documentation
636 in HTML format can be found in the
637 ''INSTALL'' document.
638 !!MANIFEST
639
640
641 These are the files in the Perl release that contain
642 references to Cygwin. These very brief notes attempt to
643 explain the reason for all conditional code. Hopefully,
644 keeping this up to date will allow the Cygwin port to be
645 kept as clean as possible.
646
647
648 Documentation
649
650
651 INSTALL README.cygwin README.win32 MANIFEST
652 Changes Changes5.005 Changes5.004 Changes5.6
653 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
654 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
655 pod/perlhist.pod pod/perlmodlib.pod pod/buildtoc.PL pod/perltoc.pod
656
657
658 Build, Configure, Make, Install
659
660
661 cygwin/Makefile.SHs
662 cygwin/ld2.in
663 cygwin/perlld.in
664 ext/IPC/SysV/hints/cygwin.pl
665 ext/NDBM_File/hints/cygwin.pl
666 ext/ODBM_File/hints/cygwin.pl
667 hints/cygwin.sh
668 Configure - help finding hints from uname,
669 shared libperl required for dynamic loading
670 Makefile.SH - linklibperl
671 Porting/patchls - cygwin in port list
672 installman - man pages with :: translated to .
673 installperl - install dll/ld2/perlld, install to pods
674 makedepend.SH - uwinfix
675
676
677 Tests
678
679
680 t/io/tell.t - binmode
681 t/lib/b.t - ignore Cwd from os_extras
682 t/lib/glob-basic.t - Win32 directory list access differs from read mode
683 t/op/magic.t - $^X/symlink WORKAROUND, s/.exe//
684 t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk
685 (cache manager sometimes preserves ctime of file
686 previously created and deleted), no -u (setuid)
687
688
689 Compiled Perl Source
690
691
692 EXTERN.h - __declspec(dllimport)
693 XSUB.h - __declspec(dllexport)
694 cygwin/cygwin.c - os_extras (getcwd, spawn)
695 perl.c - os_extras
696 perl.h - binmode
697 doio.c - win9x can not rename a file when it is open
698 pp_sys.c - do not define h_errno, pp_system with spawn
699 util.c - use setenv
700
701
702 Compiled Module Source
703
704
705 ext/POSIX/POSIX.xs - tzname defined externally
706 ext/SDBM_File/sdbm/pair.c
707 - EXTCONST needs to be redefined from EXTERN.h
708 ext/SDBM_File/sdbm/sdbm.c
709 - binary open
710
711
712 Perl Modules/Scripts
713
714
715 lib/Cwd.pm - hook to internal Cwd::cwd
2 perry 716 lib/!ExtUtils/!MakeMaker.pm
1 perry 717 - require MM_Cygwin.pm
2 perry 718 lib/!ExtUtils/MM_Cygwin.pm
1 perry 719 - canonpath, cflags, manifypods, perl_archive
720 lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1
721 lib/File/Spec/Unix.pm - preserve //unc
722 lib/File/Temp.pm - no directory sticky bit
723 lib/perl5db.pl - use stdin not /dev/tty
724 utils/perldoc.PL - version comment
725 !!BUGS
726
727
728 When ''make'' starts, it warns about overriding
729 commands for ''perlmain.o''.
730
731
732 `make clean' does not remove library
733 ''.def'' or ''.exe.stackdump''
734 files.
735
736
737 The ''ld2'' script contains references to the source
738 directory. You should change these to $installbin
739 after `make install'.
740
741
742 Support for swapping real and effective user and group
743 IDs is incomplete. On WinNT Cygwin provides ''setuid()'',
744 ''seteuid()'', ''setgid()'' and ''setegid()''.
745 However, additional Cygwin calls for manipulating WinNT
746 access tokens and security contexts are
747 required.
748
749
750 When building DLLs, `dllwrap
751 --export-all-symbols' is used to export global symbols.
752 It might be better to generate an explicit ''.def'' file
753 (see ''makedef.pl''). Also, DLLs can now be build with
754 `gcc -shared'.
755 !!AUTHORS
756
757
758 Charles Wilson
759 !!HISTORY
760
761
762 Last updated: 9 November 2000
763 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.