This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
inline.h: Fix comment
[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
940a0b6a 34At the time this document was last updated, Cygwin 1.7.16 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).
f703fc96 46The only dependencies come from hard-coded pathnames like F</usr/local>.
125a13ce
FE
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
FE
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
FE
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
FE
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
FE
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
FE
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
FE
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
FE
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
940a0b6a 328pathnames are discouraged. Names may contain all printable
5bc802de 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
95ccf9d5 343Since cygwin-1.7 textmounts are deprecated and strongly discouraged.
5bc802de 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
FE
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
FE
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
f15c31c1 393the winpid. Use C<Cygwin::pid_to_winpid()> 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
1dcc3c19
DG
412 183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error - unable to remap
413 C:\cygwin\bin\cygsvn_subr-1-0.dll to same address as parent(0x6FB30000) != 0x6FE60000
5bc802de
RU
414 46 [main] perl 3488 fork: child 3588 - died waiting for dll loading, errno11
415
416See L<http://cygwin.com/faq/faq-nochunks.html#faq.using.fixing-fork-failures>
417It helps if not too many DLLs are loaded in memory so the available address space is larger,
418e.g. stopping the MS Internet Explorer might help.
419
420Use the perlrebase or rebase utilities to resolve the conflicting dll addresses.
421The rebase package is included in the Cygwin setup. Use F<setup.exe>
422from L<http://www.cygwin.com/setup.exe> to install it.
423
4241. kill all perl processes and run C<perlrebase> or
425
4262. kill all cygwin processes and services, start dash from cmd.exe and run C<rebaseall>.
427
538204d5 428=item * C<chown()>
f8dbba82 429
538204d5 430On WinNT C<chown()> can change a file's user and group IDs. On Win9x C<chown()>
b4bcd662 431is a no-op, although this is appropriate since there is no security model.
f8dbba82
GS
432
433=item * Miscellaneous
434
538204d5 435File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
f8dbba82
GS
436returns C<ENOSYS>.
437
538204d5 438Win9x can not C<rename()> an open file (although WinNT can).
1cab015a 439
538204d5 440The Cygwin C<chroot()> implementation has holes (it can not restrict file
125a13ce
FE
441access by native Win32 programs).
442
4de3a274 443Inplace editing C<perl -i> of files doesn't work without doing a backup
c030f24b 444of the file being edited C<perl -i.bak> because of windowish restrictions,
4de3a274 445therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
27008580 446without specifying a backup extension.
818c4caa 447
1cab015a
FE
448=back
449
49fd6edc
YST
450=head2 Prebuilt methods:
451
452=over 4
453
454=item C<Cwd::cwd>
455
15414d2b 456Returns the current working directory.
49fd6edc
YST
457
458=item C<Cygwin::pid_to_winpid>
459
460Translates a cygwin pid to the corresponding Windows pid (which may or
461may not be the same).
462
463=item C<Cygwin::winpid_to_pid>
464
465Translates a Windows pid to the corresponding cygwin pid (if any).
466
15414d2b
RU
467=item C<Cygwin::win_to_posix_path>
468
469Translates a Windows path to the corresponding cygwin path respecting
470the current mount points. With a second non-null argument returns an
471absolute path. Double-byte characters will not be translated.
472
473=item C<Cygwin::posix_to_win_path>
474
475Translates a cygwin path to the corresponding cygwin path respecting
476the current mount points. With a second non-null argument returns an
477absolute path. Double-byte characters will not be translated.
478
a25ce5f3
RU
479=item C<Cygwin::mount_table()>
480
481Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].
482
483 perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}'
484 /bin c:\cygwin\bin system binmode,cygexec
485 /usr/bin c:\cygwin\bin system binmode
486 /usr/lib c:\cygwin\lib system binmode
487 / c:\cygwin system binmode
488 /cygdrive/c c: system binmode,noumount
489 /cygdrive/d d: system binmode,noumount
4de3a274 490 /cygdrive/e e: system binmode,noumount
a25ce5f3
RU
491
492=item C<Cygwin::mount_flags>
493
494Returns the mount type and flags for a specified mount point.
4de3a274 495A comma-separated string of mntent->mnt_type (always
a25ce5f3
RU
496"system" or "user"), then the mntent->mnt_opts, where
497the first is always "binmode" or "textmode".
498
499 system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
500 notexec,managed,nosuid,devfs,proc,noumount
501
74dc058d
JH
502If the argument is "/cygdrive", then just the volume mount settings,
503and the cygdrive mount prefix are returned.
a25ce5f3
RU
504
505User mounts override system mounts.
506
507 $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
508 system,binmode,cygexec
509 $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
74dc058d 510 binmode,cygdrive,/cygdrive
a25ce5f3 511
15414d2b
RU
512=item C<Cygwin::is_binmount>
513
514Returns true if the given cygwin path is binary mounted, false if the
515path is mounted in textmode.
516
286f8194
RU
517=item C<Cygwin::sync_winenv>
518
519Cygwin does not initialize all original Win32 environment variables.
520See the bottom of this page L<http://cygwin.com/cygwin-ug-net/setup-env.html>
521for "Restricted Win32 environment".
522
523Certain Win32 programs called from cygwin programs might need some environment
524variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%.
525Call Cygwin::sync_winenv() to copy all Win32 environment variables to your
526process and note that cygwin will warn on every encounter of non-POSIX paths.
527
49fd6edc
YST
528=back
529
a83b6f46 530=head1 INSTALL PERL ON CYGWIN
f8dbba82 531
b4bcd662 532This will install Perl, including I<man> pages.
f8dbba82 533
a0457be1 534 make install 2>&1 | tee log.make-install
5db16f6a 535
b432a672 536NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
5db16f6a 537you to install I<perl> into F</usr/bin>.
1cab015a 538
b432a672 539You may need to be I<Administrator> to run C<make install>. If you
f8dbba82 540are not, you must have write access to the directories in question.
1cab015a 541
f8dbba82
GS
542Information on installing the Perl documentation in HTML format can be
543found in the F<INSTALL> document.
1cab015a 544
a83b6f46 545=head1 MANIFEST ON CYGWIN
1cab015a 546
f8dbba82
GS
547These are the files in the Perl release that contain references to Cygwin.
548These very brief notes attempt to explain the reason for all conditional
549code. Hopefully, keeping this up to date will allow the Cygwin port to
4de3a274 550be kept as clean as possible.
1cab015a 551
f8dbba82 552=over 4
1cab015a 553
f8dbba82 554=item Documentation
1cab015a 555
f185f654
KW
556 INSTALL README.cygwin README.win32 MANIFEST
557 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
558 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
559 pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
560 pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
561 pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
562 pod/perltoc.pod Porting/Glossary pod/perlgit.pod
563 Porting/checkAUTHORS.pl
564 dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
d0b0e707 565 dist/Time-HiRes/Changes
f185f654
KW
566 ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
567 ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
d0b0e707 568 ext/Win32API-File/Changes
f185f654
KW
569 lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES
570 lib/ExtUtils/PATCHING lib/ExtUtils/README
571 lib/Net/Ping/Changes lib/Test/Harness/Changes
572 lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian
573 symbian/TODO
1cab015a 574
f8dbba82 575=item Build, Configure, Make, Install
1cab015a 576
f185f654
KW
577 cygwin/Makefile.SHs
578 ext/IPC/SysV/hints/cygwin.pl
579 ext/NDBM_File/hints/cygwin.pl
580 ext/ODBM_File/hints/cygwin.pl
581 hints/cygwin.sh
582 Configure - help finding hints from uname,
583 shared libperl required for dynamic loading
584 Makefile.SH Cross/Makefile-cross-SH
585 - linklibperl
586 Porting/patchls - cygwin in port list
587 installman - man pages with :: translated to .
588 installperl - install dll, install to 'pods'
589 makedepend.SH - uwinfix
590 regen_lib.pl - file permissions
591
592 NetWare/Makefile
593 plan9/mkfile
594 symbian/sanity.pl symbian/sisify.pl
595 hints/uwin.sh
596 vms/descrip_mms.template
597 win32/Makefile win32/makefile.mk
1cab015a 598
f8dbba82 599=item Tests
1cab015a 600
f185f654
KW
601 t/io/fs.t - no file mode checks if not ntsec
602 skip rename() check when not check_case:relaxed
603 t/io/tell.t - binmode
604 t/lib/cygwin.t - builtin cygwin function tests
605 t/op/groups.t - basegroup has ID = 0
606 t/op/magic.t - $^X/symlink WORKAROUND, s/.exe//
607 t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk
608 (cache manager sometimes preserves ctime of file
609 previously created and deleted), no -u (setuid)
610 t/op/taint.t - can't use empty path under Cygwin Perl
611 t/op/time.t - no tzset()
f8dbba82
GS
612
613=item Compiled Perl Source
614
f185f654
KW
615 EXTERN.h - __declspec(dllimport)
616 XSUB.h - __declspec(dllexport)
617 cygwin/cygwin.c - os_extras (getcwd, spawn, and several Cygwin:: functions)
618 perl.c - os_extras, -i.bak
619 perl.h - binmode
620 doio.c - win9x can not rename a file when it is open
621 pp_sys.c - do not define h_errno, init _pwent_struct.pw_comment
622 util.c - use setenv
623 util.h - PERL_FILE_IS_ABSOLUTE macro
624 pp.c - Comment about Posix vs IEEE math under Cygwin
625 perlio.c - CR/LF mode
626 perliol.c - Comment about EXTCONST under Cygwin
f8dbba82
GS
627
628=item Compiled Module Source
629
f185f654
KW
630 ext/Compress-Raw-Zlib/Makefile.PL
631 - Can't install via CPAN shell under Cygwin
632 ext/Compress-Raw-Zlib/zlib-src/zutil.h
633 - Cygwin is Unix-like and has vsnprintf
634 ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin
635 ext/POSIX/POSIX.xs - tzname defined externally
636 ext/SDBM_File/sdbm/pair.c
637 - EXTCONST needs to be redefined from EXTERN.h
638 ext/SDBM_File/sdbm/sdbm.c
639 - binary open
640 ext/Sys/Syslog/Syslog.xs
641 - Cygwin has syslog.h
642 ext/Sys/Syslog/win32/compile.pl
643 - Convert paths to Windows paths
644 ext/Time-HiRes/HiRes.xs
645 - Various timers not available
646 ext/Time-HiRes/Makefile.PL
647 - Find w32api/windows.h
648 ext/Win32/Makefile.PL - Use various libraries under Cygwin
649 ext/Win32/Win32.xs - Child dir and child env under Cygwin
650 ext/Win32API-File/File.xs
651 - _open_osfhandle not implemented under Cygwin
652 ext/Win32CORE/Win32CORE.c
653 - __declspec(dllexport)
f8dbba82
GS
654
655=item Perl Modules/Scripts
656
f185f654
KW
657 ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin
658 ext/Digest-SHA/bin/shasum
659 - Use binary mode under Cygwin
660 ext/Sys/Syslog/win32/Win32.pm
661 - Convert paths to Windows paths
662 ext/Time-HiRes/HiRes.pm
663 - Comment about various timers not available
664 ext/Win32API-File/File.pm
665 - _open_osfhandle not implemented under Cygwin
666 ext/Win32CORE/Win32CORE.pm
667 - History of Win32CORE under Cygwin
668 lib/Cwd.pm - hook to internal Cwd::cwd
669 lib/ExtUtils/CBuilder/Platform/cygwin.pm
670 - use gcc for ld, and link to libperl.dll.a
671 lib/ExtUtils/CBuilder.pm
672 - Cygwin is Unix-like
673 lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
674 lib/ExtUtils/MM.pm - OS classifications
675 lib/ExtUtils/MM_Any.pm - Example for Cygwin
676 lib/ExtUtils/MakeMaker.pm
677 - require MM_Cygwin.pm
678 lib/ExtUtils/MM_Cygwin.pm
679 - canonpath, cflags, manifypods, perl_archive
680 lib/File/Fetch.pm - Comment about quotes using a Cygwin example
681 lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1
682 lib/File/Spec/Cygwin.pm - case_tolerant
683 lib/File/Spec/Unix.pm - preserve //unc
684 lib/File/Spec/Win32.pm - References a message on cygwin.com
685 lib/File/Spec.pm - Pulls in lib/File/Spec/Cygwin.pm
686 lib/File/Temp.pm - no directory sticky bit
687 lib/Module/CoreList.pm - List of all module files and versions
688 lib/Net/Domain.pm - No domainname command under Cygwin
689 lib/Net/Netrc.pm - Bypass using stat() under Cygwin
690 lib/Net/Ping.pm - ECONREFUSED is EAGAIN under Cygwin
691 lib/Pod/Find.pm - Set 'pods' dir
692 lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
693 lib/Pod/Perldoc.pm - Use 'less' pager, and use .exe extension
694 lib/Term/ANSIColor.pm - Cygwin terminal info
695 lib/perl5db.pl - use stdin not /dev/tty
696 utils/perlbug.PL - Add CYGWIN environment variable to report
4de3a274
RGS
697
698=item Perl Module Tests
699
f185f654
KW
700 dist/Cwd/t/cwd.t
701 ext/Compress-Zlib/t/14gzopen.t
702 ext/DB_File/t/db-btree.t
703 ext/DB_File/t/db-hash.t
704 ext/DB_File/t/db-recno.t
705 ext/DynaLoader/t/DynaLoader.t
706 ext/File-Glob/t/basic.t
707 ext/GDBM_File/t/gdbm.t
708 ext/POSIX/t/sysconf.t
709 ext/POSIX/t/time.t
710 ext/SDBM_File/t/sdbm.t
711 ext/Sys/Syslog/t/syslog.t
712 ext/Time-HiRes/t/HiRes.t
713 ext/Win32/t/Unicode.t
714 ext/Win32API-File/t/file.t
715 ext/Win32CORE/t/win32core.t
716 lib/AnyDBM_File.t
717 lib/Archive/Extract/t/01_Archive-Extract.t
718 lib/Archive/Tar/t/02_methods.t
719 lib/ExtUtils/t/Embed.t
720 lib/ExtUtils/t/eu_command.t
721 lib/ExtUtils/t/MM_Cygwin.t
722 lib/ExtUtils/t/MM_Unix.t
723 lib/File/Compare.t
724 lib/File/Copy.t
725 lib/File/Find/t/find.t
726 lib/File/Path.t
727 lib/File/Spec/t/crossplatform.t
728 lib/File/Spec/t/Spec.t
729 lib/Net/hostent.t
730 lib/Net/Ping/t/110_icmp_inst.t
731 lib/Net/Ping/t/500_ping_icmp.t
732 lib/Net/t/netrc.t
733 lib/Pod/Simple/t/perlcyg.pod
734 lib/Pod/Simple/t/perlcygo.txt
735 lib/Pod/Simple/t/perlfaq.pod
736 lib/Pod/Simple/t/perlfaqo.txt
737 lib/User/grent.t
738 lib/User/pwent.t
1cab015a
FE
739
740=back
f89d6eaa 741
a83b6f46 742=head1 BUGS ON CYGWIN
f8dbba82 743
125a13ce 744Support for swapping real and effective user and group IDs is incomplete.
538204d5 745On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
125a13ce
FE
746However, additional Cygwin calls for manipulating WinNT access tokens
747and security contexts are required.
748
f8dbba82
GS
749=head1 AUTHORS
750
b4bcd662 751Charles Wilson <cwilson@ece.gatech.edu>,
47dafe4d 752Eric Fifer <egf7@columbia.edu>,
b4bcd662
GS
753alexander smishlajev <als@turnhere.com>,
754Steven Morlock <newspost@morlock.net>,
755Sebastien Barre <Sebastien.Barre@utc.fr>,
a0457be1 756Teun Burgers <burgers@ecn.nl>,
a25ce5f3
RU
757Gerrit P. Haase <gp@familiehaase.de>,
758Reini Urban <rurban@cpan.org>,
4de3a274
RGS
759Jan Dubois <jand@activestate.com>,
760Jerry D. Hedden <jdhedden@cpan.org>.
f8dbba82
GS
761
762=head1 HISTORY
763
5bc802de 764Last updated: 2012-02-08