This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
add Cygwin::sync_winenv [perl #110190]
[perl5.git] / README.cygwin
CommitLineData
8736538c 1If you read this file _as_is_, just ignore the funny characters you
5bc802de 2see. It is written in the POD format (see F<pod/perlpod.pod>) which is
8736538c 3specially designed to be readable as is.
5aabfad6 4
8736538c 5=head1 NAME
5aabfad6 6
de2902a6 7perlcygwin - Perl for Cygwin
5aabfad6 8
8736538c 9=head1 SYNOPSIS
5aabfad6 10
f8dbba82
GS
11This document will help you configure, make, test and install Perl
12on Cygwin. This document also describes features of Cygwin that will
13affect how Perl behaves at runtime.
5aabfad6 14
f8dbba82 15B<NOTE:> There are pre-built Perl packages available for Cygwin and a
37a78d01
JH
16version of Perl is provided in the normal Cygwin install. If you do
17not need to customize the configuration, consider using one of those
18packages.
5aabfad6 19
5aabfad6 20
a83b6f46 21=head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN
8736538c 22
f8dbba82 23=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
8736538c 24
f8dbba82
GS
25The Cygwin tools are ports of the popular GNU development tools for Win32
26platforms. They run thanks to the Cygwin library which provides the UNIX
27system calls and environment these programs expect. More information
28about this project can be found at:
8736538c 29
adb873e1 30L<http://www.cygwin.com/>
1cab015a 31
f8dbba82 32A recent net or commercial release of Cygwin is required.
8736538c 33
5bc802de 34At the time this document was last updated, Cygwin 1.7.10 was current.
8736538c 35
1cab015a 36
f8dbba82 37=head2 Cygwin Configuration
1cab015a 38
f8dbba82
GS
39While building Perl some changes may be necessary to your Cygwin setup so
40that Perl builds cleanly. These changes are B<not> required for normal
41Perl usage.
1cab015a 42
f8dbba82 43B<NOTE:> The binaries that are built will run on all Win32 versions.
5bc802de
RU
44They do not depend on your host system (WinXP/Win2K/Win7) or your
45Cygwin configuration (binary/text mounts, cvgserver).
125a13ce
EF
46The only dependencies come from hard-coded pathnames like C</usr/local>.
47However, your host system and Cygwin configuration will affect Perl's
48runtime behavior (see L</"TEST">).
1cab015a 49
f8dbba82 50=over 4
1cab015a 51
f8dbba82 52=item * C<PATH>
1cab015a 53
f8dbba82 54Set the C<PATH> environment variable so that Configure finds the Cygwin
5bc802de 55versions of programs. Any not-needed Windows directories should be removed or
f8dbba82 56moved to the end of your C<PATH>.
1cab015a 57
f8dbba82 58=item * I<nroff>
1cab015a 59
f8dbba82 60If you do not have I<nroff> (which is part of the I<groff> package),
b4bcd662 61Configure will B<not> prompt you to install I<man> pages.
f8dbba82 62
8736538c
AS
63=back
64
a83b6f46 65=head1 CONFIGURE PERL ON CYGWIN
8736538c 66
f8dbba82
GS
67The default options gathered by Configure with the assistance of
68F<hints/cygwin.sh> will build a Perl that supports dynamic loading
5bc802de 69(which requires a shared F<cygperl5_16.dll>).
f89d6eaa 70
f8dbba82 71This will run Configure and keep a record:
8736538c 72
f8dbba82 73 ./Configure 2>&1 | tee log.configure
8736538c 74
b4bcd662 75If you are willing to accept all the defaults run Configure with B<-de>.
f8dbba82 76However, several useful customizations are available.
5aabfad6 77
a83b6f46 78=head2 Stripping Perl Binaries on Cygwin
5aabfad6 79
f8dbba82
GS
80It is possible to strip the EXEs and DLLs created by the build process.
81The resulting binaries will be significantly smaller. If you want the
82binaries to be stripped, you can either add a B<-s> option when Configure
83prompts you,
8736538c 84
f8dbba82 85 Any additional ld flags (NOT including libraries)? [none] -s
4de3a274 86 Any special flags to pass to g++ to create a dynamically loaded library?
f8dbba82 87 [none] -s
4de3a274 88 Any special flags to pass to gcc to use dynamic linking? [none] -s
8736538c 89
f8dbba82
GS
90or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
91near the end of the file.
8736538c 92
a83b6f46 93=head2 Optional Libraries for Perl on Cygwin
8736538c 94
f8dbba82
GS
95Several Perl functions and modules depend on the existence of
96some optional libraries. Configure will find them if they are
97installed in one of the directories listed as being used for library
37a78d01
JH
98searches. Pre-built packages for most of these are available from
99the Cygwin installer.
8736538c 100
f8dbba82 101=over 4
8736538c 102
f8dbba82 103=item * C<-lcrypt>
8736538c 104
125a13ce
EF
105The crypt package distributed with Cygwin is a Linux compatible 56-bit
106DES crypt port by Corinna Vinschen.
107
108Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.
1cab015a 109
4de3a274 110=item * C<-lgdbm_compat> (C<use GDBM_File>)
1cab015a 111
a0457be1 112GDBM is available for Cygwin.
125a13ce 113
be238d52
JH
114NOTE: The GDBM library only works on NTFS partitions.
115
f8dbba82 116=item * C<-ldb> (C<use DB_File>)
1cab015a 117
be238d52 118BerkeleyDB is available for Cygwin.
1cab015a 119
5bc802de 120NOTE: The BerkeleyDB library only completely works on NTFS partitions.
125a13ce 121
15414d2b 122=item * C<cygserver> (C<use IPC::SysV>)
f8dbba82 123
6b49d266
EF
124A port of SysV IPC is available for Cygwin.
125
126NOTE: This has B<not> been extensively tested. In particular,
b4bcd662
GS
127C<d_semctl_semun> is undefined because it fails a Configure test
128and on Win9x the I<shm*()> functions seem to hang. It also creates
129a compile time dependency because F<perl.h> includes F<<sys/ipc.h>>
130and F<<sys/sem.h>> (which will be required in the future when compiling
be238d52 131CPAN modules). CURRENTLY NOT SUPPORTED!
47f4f673
GH
132
133=item * C<-lutil>
134
4de3a274 135Included with the standard Cygwin netrelease is the inetutils package
47f4f673 136which includes libutil.a.
1cab015a
EF
137
138=back
139
a83b6f46 140=head2 Configure-time Options for Perl on Cygwin
f8dbba82 141
0a110db2
GS
142The F<INSTALL> document describes several Configure-time options. Some of
143these will work with Cygwin, others are not yet possible. Also, some of
144these are experimental. You can either select an option when Configure
145prompts you or you can define (undefine) symbols on the command line.
f8dbba82
GS
146
147=over 4
148
149=item * C<-Uusedl>
150
0a110db2 151Undefining this symbol forces Perl to be compiled statically.
f8dbba82 152
5bc802de 153=item * C<-Dusemymalloc>
1cab015a 154
5bc802de
RU
155By default Perl does not use the C<malloc()> included with the Perl source,
156because it was slower and not entirely thread-safe. If you want to force
157Perl to build with the old -Dusemymalloc define this.
1cab015a 158
33bf3ba1
RGS
159=item * C<-Uuseperlio>
160
bbebedce
YST
161Undefining this symbol disables the PerlIO abstraction. PerlIO is now the
162default; it is not recommended to disable PerlIO.
33bf3ba1 163
6b49d266 164=item * C<-Dusemultiplicity>
1cab015a 165
f8dbba82 166Multiplicity is required when embedding Perl in a C program and using
5bc802de
RU
167more than one interpreter instance. This is only required when you build
168a not-threaded perl with C<-Uuseithreads>.
1cab015a 169
5bc802de 170=item * C<-Uuse64bitint>
1cab015a 171
5bc802de
RU
172By default Perl uses 64 bit integers. If you want to use smaller 32 bit
173integers, define this symbol.
1cab015a 174
f8dbba82 175=item * C<-Duselongdouble>
1cab015a 176
f8dbba82
GS
177I<gcc> supports long doubles (12 bytes). However, several additional
178long double math functions are necessary to use them within Perl
4de3a274 179(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
5cb3728c 180strtold>).
5bc802de 181These are B<not> yet available with newlib, the Cygwin libc.
1cab015a 182
5bc802de 183=item * C<-Uuseithreads>
1cab015a 184
5bc802de 185Define this symbol if you want not-threaded faster perl.
f8dbba82
GS
186
187=item * C<-Duselargefiles>
188
4de3a274 189Cygwin uses 64-bit integers for internal size and position calculations,
be238d52 190this will be correctly detected and defined by Configure.
1cab015a 191
a0457be1
GH
192=item * C<-Dmksymlinks>
193
5bc802de
RU
194Use this to build perl outside of the source tree. Details can be
195found in the F<INSTALL> document. This is the recommended way to
196build perl from sources.
a0457be1 197
1cab015a
EF
198=back
199
a83b6f46 200=head2 Suspicious Warnings on Cygwin
1cab015a 201
f8dbba82 202You may see some messages during Configure that seem suspicious.
8736538c 203
f8dbba82 204=over 4
8736538c 205
b4bcd662 206=item * Win9x and C<d_eofnblk>
5db16f6a
EF
207
208Win9x does not correctly report C<EOF> with a non-blocking read on a
209closed pipe. You will see the following messages:
210
211 But it also returns -1 to signal EOF, so be careful!
212 WARNING: you can't distinguish between EOF and no data!
213
214 *** WHOA THERE!!! ***
215 The recommended value for $d_eofnblk on this machine was "define"!
216 Keep the recommended value? [y]
217
218At least for consistency with WinNT, you should keep the recommended
219value.
220
0a110db2
GS
221=item * Compiler/Preprocessor defines
222
223The following error occurs because of the Cygwin C<#define> of
224C<_LONG_DOUBLE>:
225
226 Guessing which symbols your C compiler and preprocessor define...
fb652349 227 try.c:<line#>: missing binary operator
0a110db2 228
fb652349
YST
229This failure does not seem to cause any problems. With older gcc
230versions, "parse error" is reported instead of "missing binary
231operator".
0a110db2 232
5db16f6a
EF
233=back
234
a83b6f46 235=head1 MAKE ON CYGWIN
5aabfad6 236
b4bcd662 237Simply run I<make> and wait:
f8dbba82
GS
238
239 make 2>&1 | tee log.make
240
a83b6f46 241=head1 TEST ON CYGWIN
f8dbba82
GS
242
243There are two steps to running the test suite:
244
245 make test 2>&1 | tee log.make-test
246
15414d2b 247 cd t; ./perl harness 2>&1 | tee ../log.harness
f8dbba82
GS
248
249The same tests are run both times, but more information is provided when
b432a672 250running as C<./perl harness>.
5aabfad6 251
f8dbba82 252Test results vary depending on your host system and your Cygwin
b4bcd662
GS
253configuration. If a test can pass in some Cygwin setup, it is always
254attempted and explainable test failures are documented. It is possible
125a13ce
EF
255for Perl to pass all the tests, but it is more likely that some tests
256will fail for one of the reasons listed below.
1cab015a 257
a83b6f46 258=head2 File Permissions on Cygwin
1cab015a 259
f8dbba82 260UNIX file permissions are based on sets of mode bits for
b4bcd662
GS
261{read,write,execute} for each {user,group,other}. By default Cygwin
262only tracks the Win32 read-only attribute represented as the UNIX file
263user write bit (files are always readable, files are executable if they
264have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are
265always readable and executable). On WinNT with the I<ntea> C<CYGWIN>
266setting, the additional mode bits are stored as extended file attributes.
4de3a274 267On WinNT with the default I<ntsec> C<CYGWIN> setting, permissions use the
15414d2b 268standard WinNT security descriptors and access control lists. Without one of
47f4f673 269these options, these tests will fail (listing not updated yet):
1cab015a 270
f8dbba82
GS
271 Failed Test List of failed
272 ------------------------------------
273 io/fs.t 5, 7, 9-10
274 lib/anydbm.t 2
275 lib/db-btree.t 20
276 lib/db-hash.t 16
277 lib/db-recno.t 18
278 lib/gdbm.t 2
f8dbba82
GS
279 lib/ndbm.t 2
280 lib/odbm.t 2
281 lib/sdbm.t 2
282 op/stat.t 9, 20 (.tmp not an executable extension)
1cab015a 283
fb652349
YST
284=head2 NDBM_File and ODBM_File do not work on FAT filesystems
285
286Do not use NDBM_File or ODBM_File on FAT filesystem. They can be
287built on a FAT filesystem, but many tests will fail:
288
289 ../ext/NDBM_File/ndbm.t 13 3328 71 59 83.10% 1-2 4 16-71
290 ../ext/ODBM_File/odbm.t 255 65280 ?? ?? % ??
291 ../lib/AnyDBM_File.t 2 512 12 2 16.67% 1 4
292 ../lib/Memoize/t/errors.t 0 139 11 5 45.45% 7-11
293 ../lib/Memoize/t/tie_ndbm.t 13 3328 4 4 100.00% 1-4
294 run/fresh_perl.t 97 1 1.03% 91
295
296If you intend to run only on FAT (or if using AnyDBM_File on FAT),
297run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
298NDBM_File and ODBM_File being built.
299
15414d2b 300With NTFS (and no CYGWIN=nontsec), there should be no problems even if
fb652349
YST
301perl was built on FAT.
302
538204d5 303=head2 C<fork()> failures in io_* tests
0be9fa5d 304
538204d5 305A C<fork()> failure may result in the following tests failing:
fb652349
YST
306
307 ext/IO/lib/IO/t/io_multihomed.t
308 ext/IO/lib/IO/t/io_sock.t
309 ext/IO/lib/IO/t/io_unix.t
310
fd161f2c 311See comment on fork in L</Miscellaneous> below.
0be9fa5d 312
49fd6edc
YST
313=head1 Specific features of the Cygwin port
314
a83b6f46 315=head2 Script Portability on Cygwin
1cab015a 316
b4bcd662
GS
317Cygwin does an outstanding job of providing UNIX-like semantics on top of
318Win32 systems. However, in addition to the items noted above, there are
319some differences that you should know about. This is a very brief guide
320to portability, more information can be found in the Cygwin documentation.
1cab015a 321
f8dbba82 322=over 4
1cab015a 323
f8dbba82 324=item * Pathnames
1cab015a 325
5bc802de
RU
326Cygwin pathnames are separated by forward (F</>) slashes, Universal
327Naming Codes (F<//UNC>) are also supported Since cygwin-1.7 non-POSIX
328pathnames are disencouraged. Names may contain all printable
329characters.
1cab015a 330
125a13ce 331File names are case insensitive, but case preserving. A pathname that
5bc802de
RU
332contains a backslash or drive letter is a Win32 pathname, and not
333subject to the translations applied to POSIX style pathnames, but
334cygwin will warn you, so better convert them to POSIX.
f8dbba82 335
4de3a274 336For conversion we have C<Cygwin::win_to_posix_path()> and
15414d2b
RU
337C<Cygwin::posix_to_win_path()>.
338
5bc802de 339Since cygwin-1.7 pathnames are UTF-8 encoded.
15414d2b 340
f8dbba82
GS
341=item * Text/Binary
342
5bc802de
RU
343Since cywgin-1.7 textmounts are deprecated and stronlgy discouraged.
344
f8dbba82 345When a file is opened it is in either text or binary mode. In text mode
5db16f6a 346a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default
538204d5 347mode for an C<open()> is determined by the mode of the mount that underlies
5fc51037 348the file. See L</Cygwin::is_binmount>(). Perl provides a C<binmode()> function
7b7dcf5a
RGS
349to set binary mode on files that otherwise would be treated as text.
350C<sysopen()> with the C<O_TEXT> flag sets text mode on files that otherwise
351would be treated as binary:
5db16f6a
EF
352
353 sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
f8dbba82 354
538204d5
GH
355C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
356mode.
5db16f6a
EF
357
358The text/binary issue is covered at length in the Cygwin documentation.
f8dbba82 359
538204d5
GH
360=item * PerlIO
361
4de3a274
RGS
362PerlIO overrides the default Cygwin Text/Binary behaviour. A file will
363always be treated as binary, regardless of the mode of the mount it lives
364on, just like it is in UNIX. So CR/LF translation needs to be requested in
538204d5
GH
365either the C<open()> call like this:
366
367 open(FH, ">:crlf", "out.txt");
368
4de3a274 369which will do conversion from LF to CR/LF on the output, or in the
538204d5
GH
370environment settings (add this to your .bashrc):
371
372 export PERLIO=crlf
373
4de3a274 374which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
538204d5
GH
375on every output generated by perl.
376
f8dbba82
GS
377=item * F<.exe>
378
538204d5 379The Cygwin C<stat()>, C<lstat()> and C<readlink()> functions make the F<.exe>
497711e7
GS
380extension transparent by looking for F<foo.exe> when you ask for F<foo>
381(unless a F<foo> also exists). Cygwin does not require a F<.exe>
382extension, but I<gcc> adds it automatically when building a program.
383However, when accessing an executable as a normal file (e.g., I<cp>
5bc802de
RU
384in a makefile) the F<.exe> is not transparent. The I<install> program
385included with Cygwin automatically appends a F<.exe> when necessary.
f8dbba82 386
e3988807 387=item * Cygwin vs. Windows process ids
75e109ec
RGS
388
389Cygwin processes have their own pid, which is different from the
390underlying windows pid. Most posix compliant Proc functions expect
391the cygwin pid, but several Win32::Process functions expect the
392winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not
4de3a274 393the winpid. Use C<Cygwin::winpid_to_pid()> and C<Cygwin::winpid_to_pid()>
75e109ec
RGS
394to translate between them.
395
e3988807
JH
396=item * Cygwin vs. Windows errors
397
398Under Cygwin, $^E is the same as $!. When using L<Win32 API Functions|Win32>,
399use C<Win32::GetLastError()> to get the last Windows error.
400
5bc802de
RU
401=item * rebase errors on fork or system
402
403Using C<fork()> or C<system()> out to another perl after loading multiple dlls
404may result on a DLL baseaddress conflict. The internal cygwin error
405looks like like the following:
406
407 0 [main] perl 8916 child_info_fork::abort: data segment start: parent
408 (0xC1A000) != child(0xA6A000)
409
410or:
411
412 183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error - unable to remap C:\cygwin\bin\cygsvn_subr-1-0.dll to same address as parent(0x6FB30000) != 0x6FE60000
413 46 [main] perl 3488 fork: child 3588 - died waiting for dll loading, errno11
414
415See L<http://cygwin.com/faq/faq-nochunks.html#faq.using.fixing-fork-failures>
416It helps if not too many DLLs are loaded in memory so the available address space is larger,
417e.g. stopping the MS Internet Explorer might help.
418
419Use the perlrebase or rebase utilities to resolve the conflicting dll addresses.
420The rebase package is included in the Cygwin setup. Use F<setup.exe>
421from L<http://www.cygwin.com/setup.exe> to install it.
422
4231. kill all perl processes and run C<perlrebase> or
424
4252. kill all cygwin processes and services, start dash from cmd.exe and run C<rebaseall>.
426
538204d5 427=item * C<chown()>
f8dbba82 428
538204d5 429On WinNT C<chown()> can change a file's user and group IDs. On Win9x C<chown()>
b4bcd662 430is a no-op, although this is appropriate since there is no security model.
f8dbba82
GS
431
432=item * Miscellaneous
433
538204d5 434File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
f8dbba82
GS
435returns C<ENOSYS>.
436
538204d5 437Win9x can not C<rename()> an open file (although WinNT can).
1cab015a 438
538204d5 439The Cygwin C<chroot()> implementation has holes (it can not restrict file
125a13ce
EF
440access by native Win32 programs).
441
4de3a274 442Inplace editing C<perl -i> of files doesn't work without doing a backup
c030f24b 443of the file being edited C<perl -i.bak> because of windowish restrictions,
4de3a274 444therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
27008580 445without specifying a backup extension.
818c4caa 446
1cab015a
EF
447=back
448
49fd6edc
YST
449=head2 Prebuilt methods:
450
451=over 4
452
453=item C<Cwd::cwd>
454
15414d2b 455Returns the current working directory.
49fd6edc
YST
456
457=item C<Cygwin::pid_to_winpid>
458
459Translates a cygwin pid to the corresponding Windows pid (which may or
460may not be the same).
461
462=item C<Cygwin::winpid_to_pid>
463
464Translates a Windows pid to the corresponding cygwin pid (if any).
465
15414d2b
RU
466=item C<Cygwin::win_to_posix_path>
467
468Translates a Windows path to the corresponding cygwin path respecting
469the current mount points. With a second non-null argument returns an
470absolute path. Double-byte characters will not be translated.
471
472=item C<Cygwin::posix_to_win_path>
473
474Translates a cygwin path to the corresponding cygwin path respecting
475the current mount points. With a second non-null argument returns an
476absolute path. Double-byte characters will not be translated.
477
a25ce5f3
RU
478=item C<Cygwin::mount_table()>
479
480Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].
481
482 perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}'
483 /bin c:\cygwin\bin system binmode,cygexec
484 /usr/bin c:\cygwin\bin system binmode
485 /usr/lib c:\cygwin\lib system binmode
486 / c:\cygwin system binmode
487 /cygdrive/c c: system binmode,noumount
488 /cygdrive/d d: system binmode,noumount
4de3a274 489 /cygdrive/e e: system binmode,noumount
a25ce5f3
RU
490
491=item C<Cygwin::mount_flags>
492
493Returns the mount type and flags for a specified mount point.
4de3a274 494A comma-separated string of mntent->mnt_type (always
a25ce5f3
RU
495"system" or "user"), then the mntent->mnt_opts, where
496the first is always "binmode" or "textmode".
497
498 system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
499 notexec,managed,nosuid,devfs,proc,noumount
500
74dc058d
JH
501If the argument is "/cygdrive", then just the volume mount settings,
502and the cygdrive mount prefix are returned.
a25ce5f3
RU
503
504User mounts override system mounts.
505
506 $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
507 system,binmode,cygexec
508 $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
74dc058d 509 binmode,cygdrive,/cygdrive
a25ce5f3 510
15414d2b
RU
511=item C<Cygwin::is_binmount>
512
513Returns true if the given cygwin path is binary mounted, false if the
514path is mounted in textmode.
515
286f8194
RU
516=item C<Cygwin::sync_winenv>
517
518Cygwin does not initialize all original Win32 environment variables.
519See the bottom of this page L<http://cygwin.com/cygwin-ug-net/setup-env.html>
520for "Restricted Win32 environment".
521
522Certain Win32 programs called from cygwin programs might need some environment
523variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%.
524Call Cygwin::sync_winenv() to copy all Win32 environment variables to your
525process and note that cygwin will warn on every encounter of non-POSIX paths.
526
49fd6edc
YST
527=back
528
a83b6f46 529=head1 INSTALL PERL ON CYGWIN
f8dbba82 530
b4bcd662 531This will install Perl, including I<man> pages.
f8dbba82 532
a0457be1 533 make install 2>&1 | tee log.make-install
5db16f6a 534
b432a672 535NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
5db16f6a 536you to install I<perl> into F</usr/bin>.
1cab015a 537
b432a672 538You may need to be I<Administrator> to run C<make install>. If you
f8dbba82 539are not, you must have write access to the directories in question.
1cab015a 540
f8dbba82
GS
541Information on installing the Perl documentation in HTML format can be
542found in the F<INSTALL> document.
1cab015a 543
a83b6f46 544=head1 MANIFEST ON CYGWIN
1cab015a 545
f8dbba82
GS
546These are the files in the Perl release that contain references to Cygwin.
547These very brief notes attempt to explain the reason for all conditional
548code. Hopefully, keeping this up to date will allow the Cygwin port to
4de3a274 549be kept as clean as possible.
1cab015a 550
f8dbba82 551=over 4
1cab015a 552
f8dbba82 553=item Documentation
1cab015a 554
47dafe4d 555 INSTALL README.cygwin README.win32 MANIFEST
47dafe4d
EF
556 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
557 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
4de3a274
RGS
558 pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
559 pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
560 pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
0aef0fe5 561 pod/perltoc.pod Porting/Glossary pod/perlgit.pod
4de3a274 562 Porting/checkAUTHORS.pl
2a6dc374
FR
563 dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
564 ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
565 ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
566 ext/Time-HiRes/Changes ext/Win32API-File/Changes lib/CGI/Changes
567 lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES
568 lib/ExtUtils/PATCHING lib/ExtUtils/README lib/Module/Build/Changes
569 lib/Net/Ping/Changes lib/Test/Harness/Changes
570 lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian
571 symbian/TODO
1cab015a 572
f8dbba82 573=item Build, Configure, Make, Install
1cab015a 574
f8dbba82 575 cygwin/Makefile.SHs
f8dbba82
GS
576 ext/IPC/SysV/hints/cygwin.pl
577 ext/NDBM_File/hints/cygwin.pl
578 ext/ODBM_File/hints/cygwin.pl
579 hints/cygwin.sh
f8dbba82
GS
580 Configure - help finding hints from uname,
581 shared libperl required for dynamic loading
4de3a274
RGS
582 Makefile.SH Cross/Makefile-cross-SH
583 - linklibperl
6b49d266 584 Porting/patchls - cygwin in port list
f8dbba82 585 installman - man pages with :: translated to .
4de3a274 586 installperl - install dll, install to 'pods'
6b49d266 587 makedepend.SH - uwinfix
4de3a274
RGS
588 regen_lib.pl - file permissions
589
590 NetWare/Makefile
591 plan9/mkfile
592 symbian/sanity.pl symbian/sisify.pl
593 hints/uwin.sh
594 vms/descrip_mms.template
595 win32/Makefile win32/makefile.mk
1cab015a 596
f8dbba82 597=item Tests
1cab015a 598
4de3a274
RGS
599 t/io/fs.t - no file mode checks if not ntsec
600 skip rename() check when not check_case:relaxed
f8dbba82 601 t/io/tell.t - binmode
4de3a274
RGS
602 t/lib/cygwin.t - builtin cygwin function tests
603 t/op/groups.t - basegroup has ID = 0
5db16f6a
EF
604 t/op/magic.t - $^X/symlink WORKAROUND, s/.exe//
605 t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk
606 (cache manager sometimes preserves ctime of file
607 previously created and deleted), no -u (setuid)
4de3a274
RGS
608 t/op/taint.t - can't use empty path under Cygwin Perl
609 t/op/time.t - no tzset()
f8dbba82
GS
610
611=item Compiled Perl Source
612
f8dbba82
GS
613 EXTERN.h - __declspec(dllimport)
614 XSUB.h - __declspec(dllexport)
a25ce5f3 615 cygwin/cygwin.c - os_extras (getcwd, spawn, and several Cygwin:: functions)
4de3a274 616 perl.c - os_extras, -i.bak
f8dbba82 617 perl.h - binmode
6b49d266 618 doio.c - win9x can not rename a file when it is open
4de3a274 619 pp_sys.c - do not define h_errno, init _pwent_struct.pw_comment
47dafe4d 620 util.c - use setenv
4de3a274
RGS
621 util.h - PERL_FILE_IS_ABSOLUTE macro
622 pp.c - Comment about Posix vs IEEE math under Cygwin
623 perlio.c - CR/LF mode
624 perliol.c - Comment about EXTCONST under Cygwin
f8dbba82
GS
625
626=item Compiled Module Source
627
dc539f3d 628 ext/Compress-Raw-Zlib/Makefile.PL
4de3a274 629 - Can't install via CPAN shell under Cygwin
dc539f3d 630 ext/Compress-Raw-Zlib/zlib-src/zutil.h
4de3a274
RGS
631 - Cygwin is Unix-like and has vsnprintf
632 ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin
f8dbba82
GS
633 ext/POSIX/POSIX.xs - tzname defined externally
634 ext/SDBM_File/sdbm/pair.c
635 - EXTCONST needs to be redefined from EXTERN.h
636 ext/SDBM_File/sdbm/sdbm.c
637 - binary open
4de3a274
RGS
638 ext/Sys/Syslog/Syslog.xs
639 - Cygwin has syslog.h
640 ext/Sys/Syslog/win32/compile.pl
641 - Convert paths to Windows paths
40d04ec4 642 ext/Time-HiRes/HiRes.xs
4de3a274 643 - Various timers not available
40d04ec4 644 ext/Time-HiRes/Makefile.PL
4de3a274
RGS
645 - Find w32api/windows.h
646 ext/Win32/Makefile.PL - Use various libraries under Cygwin
647 ext/Win32/Win32.xs - Child dir and child env under Cygwin
4282a474 648 ext/Win32API-File/File.xs
4de3a274
RGS
649 - _open_osfhandle not implemented under Cygwin
650 ext/Win32CORE/Win32CORE.c
651 - __declspec(dllexport)
f8dbba82
GS
652
653=item Perl Modules/Scripts
654
4de3a274 655 ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin
12fc04c9 656 ext/Digest-SHA/bin/shasum
4de3a274
RGS
657 - Use binary mode under Cygwin
658 ext/Sys/Syslog/win32/Win32.pm
659 - Convert paths to Windows paths
40d04ec4 660 ext/Time-HiRes/HiRes.pm
4de3a274 661 - Comment about various timers not available
4282a474 662 ext/Win32API-File/File.pm
4de3a274
RGS
663 - _open_osfhandle not implemented under Cygwin
664 ext/Win32CORE/Win32CORE.pm
665 - History of Win32CORE under Cygwin
666 lib/CGI.pm - binmode and path separator
667 lib/CPANPLUS/Dist/MM.pm - Commented out code that fails under Win32/Cygwin
668 lib/CPANPLUS/Internals/Constants/Report.pm
669 - OS classifications
670 lib/CPANPLUS/Internals/Constants.pm
f858446f 671 - Constants for Cygwin
4de3a274
RGS
672 lib/CPANPLUS/Internals/Report.pm
673 - Example of Cygwin report
674 lib/CPANPLUS/Module.pm
675 - Abort if running on old Cygwin version
6b49d266 676 lib/Cwd.pm - hook to internal Cwd::cwd
4de3a274
RGS
677 lib/ExtUtils/CBuilder/Platform/cygwin.pm
678 - use gcc for ld, and link to libperl.dll.a
679 lib/ExtUtils/CBuilder.pm
680 - Cygwin is Unix-like
681 lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
682 lib/ExtUtils/MM.pm - OS classifications
683 lib/ExtUtils/MM_Any.pm - Example for Cygwin
f8dbba82
GS
684 lib/ExtUtils/MakeMaker.pm
685 - require MM_Cygwin.pm
686 lib/ExtUtils/MM_Cygwin.pm
687 - canonpath, cflags, manifypods, perl_archive
4de3a274 688 lib/File/Fetch.pm - Comment about quotes using a Cygwin example
497711e7 689 lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1
a25ce5f3 690 lib/File/Spec/Cygwin.pm - case_tolerant
6b49d266 691 lib/File/Spec/Unix.pm - preserve //unc
4de3a274
RGS
692 lib/File/Spec/Win32.pm - References a message on cygwin.com
693 lib/File/Spec.pm - Pulls in lib/File/Spec/Cygwin.pm
5d129265 694 lib/File/Temp.pm - no directory sticky bit
4de3a274
RGS
695 lib/Module/Build/Compat.pm - Comment references 'make' under Cygwin
696 lib/Module/Build/Platform/cygwin.pm
697 - Use '.' for man page separator
698 lib/Module/Build.pm - Cygwin is Unix-like
699 lib/Module/CoreList.pm - List of all module files and versions
700 lib/Net/Domain.pm - No domainname command under Cygwin
701 lib/Net/Netrc.pm - Bypass using stat() under Cygwin
702 lib/Net/Ping.pm - ECONREFUSED is EAGAIN under Cygwin
703 lib/Pod/Find.pm - Set 'pods' dir
704 lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
705 lib/Pod/Perldoc.pm - Use 'less' pager, and use .exe extension
706 lib/Term/ANSIColor.pm - Cygwin terminal info
6b49d266 707 lib/perl5db.pl - use stdin not /dev/tty
4de3a274
RGS
708 utils/perlbug.PL - Add CYGWIN environment variable to report
709
710=item Perl Module Tests
711
2a6dc374 712 dist/Cwd/t/cwd.t
32592041 713 ext/Compress-Zlib/t/14gzopen.t
4de3a274
RGS
714 ext/DB_File/t/db-btree.t
715 ext/DB_File/t/db-hash.t
716 ext/DB_File/t/db-recno.t
717 ext/DynaLoader/t/DynaLoader.t
005c4f26 718 ext/File-Glob/t/basic.t
4de3a274
RGS
719 ext/GDBM_File/t/gdbm.t
720 ext/POSIX/t/sysconf.t
721 ext/POSIX/t/time.t
722 ext/SDBM_File/t/sdbm.t
723 ext/Sys/Syslog/t/syslog.t
40d04ec4 724 ext/Time-HiRes/t/HiRes.t
4de3a274 725 ext/Win32/t/Unicode.t
4282a474 726 ext/Win32API-File/t/file.t
4de3a274
RGS
727 ext/Win32CORE/t/win32core.t
728 lib/AnyDBM_File.t
729 lib/Archive/Extract/t/01_Archive-Extract.t
730 lib/Archive/Tar/t/02_methods.t
731 lib/CPANPLUS/t/05_CPANPLUS-Internals-Fetch.t
732 lib/CPANPLUS/t/20_CPANPLUS-Dist-MM.t
733 lib/ExtUtils/t/Embed.t
734 lib/ExtUtils/t/eu_command.t
735 lib/ExtUtils/t/MM_Cygwin.t
736 lib/ExtUtils/t/MM_Unix.t
737 lib/File/Compare.t
738 lib/File/Copy.t
739 lib/File/Find/t/find.t
740 lib/File/Path.t
741 lib/File/Spec/t/crossplatform.t
742 lib/File/Spec/t/Spec.t
743 lib/Module/Build/t/destinations.t
744 lib/Net/hostent.t
745 lib/Net/Ping/t/110_icmp_inst.t
746 lib/Net/Ping/t/500_ping_icmp.t
747 lib/Net/t/netrc.t
748 lib/Pod/Simple/t/perlcyg.pod
749 lib/Pod/Simple/t/perlcygo.txt
750 lib/Pod/Simple/t/perlfaq.pod
751 lib/Pod/Simple/t/perlfaqo.txt
752 lib/User/grent.t
753 lib/User/pwent.t
1cab015a
EF
754
755=back
f89d6eaa 756
a83b6f46 757=head1 BUGS ON CYGWIN
f8dbba82 758
125a13ce 759Support for swapping real and effective user and group IDs is incomplete.
538204d5 760On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
125a13ce
EF
761However, additional Cygwin calls for manipulating WinNT access tokens
762and security contexts are required.
763
f8dbba82
GS
764=head1 AUTHORS
765
b4bcd662 766Charles Wilson <cwilson@ece.gatech.edu>,
47dafe4d 767Eric Fifer <egf7@columbia.edu>,
b4bcd662
GS
768alexander smishlajev <als@turnhere.com>,
769Steven Morlock <newspost@morlock.net>,
770Sebastien Barre <Sebastien.Barre@utc.fr>,
a0457be1 771Teun Burgers <burgers@ecn.nl>,
a25ce5f3
RU
772Gerrit P. Haase <gp@familiehaase.de>,
773Reini Urban <rurban@cpan.org>,
4de3a274
RGS
774Jan Dubois <jand@activestate.com>,
775Jerry D. Hedden <jdhedden@cpan.org>.
f8dbba82
GS
776
777=head1 HISTORY
778
5bc802de 779Last updated: 2012-02-08