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