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