This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
extend PL_veto_cleanup to all platforms
[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
5db16f6a 101 Any special flags to pass to gcc to use dynamic linking? [none] -s
f8dbba82
GS
102 Any special flags to pass to ld2 to create a dynamically loaded library?
103 [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
f8dbba82 136=item * C<-lgdbm> (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
15414d2b
RU
146NOTE: The BerkeleyDB library only completely works on NTFS partitions
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
162Included with the standard Cygwin netrelease is the inetutils package
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
5cb3728c
RB
204(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
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
be238d52
JH
215Cygwin uses 64-bit integers for internal size and position calculations,
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.
538204d5 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.
15414d2b
RU
293On WinNT with the default I<ntsec> C<CYGWIN> setting, permissions use the
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
15414d2b
RU
365For conversion we have C<Cygwin::win_to_posix_path()> and
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.
370There's an unofficial unicode patch for cygwin at
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
392PerlIO overrides the default Cygwin Text/Binary behaviour. A file will
393always treated as binary, regardless which mode of the mount it lives on,
394just like it is in UNIX. So CR/LF translation needs to be requested in
395either the C<open()> call like this:
396
397 open(FH, ">:crlf", "out.txt");
398
399which will do conversion from LF to CR/LF on the output, or in the
400environment settings (add this to your .bashrc):
401
402 export PERLIO=crlf
403
404which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
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
423the winpid. Use C<Cygwin::winpid_to_pid()> and C<Cygwin::winpid_to_pid()>
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
c030f24b
GH
446Inplace editing C<perl -i> of files doesn't work without doing a backup
447of the file being edited C<perl -i.bak> because of windowish restrictions,
538204d5 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
505 /cygdrive/e e: system binmode,noumount
506
507=item C<Cygwin::mount_flags>
508
509Returns the mount type and flags for a specified mount point.
510A comma-seperated string of mntent->mnt_type (always
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
517If the argument is "/cygdrive", just the volume mount settings are returned.
518
519User mounts override system mounts.
520
521 $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
522 system,binmode,cygexec
523 $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
524 binmode,cygdrive
525
15414d2b
RU
526=item C<Cygwin::is_binmount>
527
528Returns true if the given cygwin path is binary mounted, false if the
529path is mounted in textmode.
530
49fd6edc
YST
531=back
532
a83b6f46 533=head1 INSTALL PERL ON CYGWIN
f8dbba82 534
b4bcd662 535This will install Perl, including I<man> pages.
f8dbba82 536
a0457be1 537 make install 2>&1 | tee log.make-install
5db16f6a 538
b432a672 539NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
5db16f6a 540you to install I<perl> into F</usr/bin>.
1cab015a 541
b432a672 542You may need to be I<Administrator> to run C<make install>. If you
f8dbba82 543are not, you must have write access to the directories in question.
1cab015a 544
f8dbba82
GS
545Information on installing the Perl documentation in HTML format can be
546found in the F<INSTALL> document.
1cab015a 547
a83b6f46 548=head1 MANIFEST ON CYGWIN
1cab015a 549
f8dbba82
GS
550These are the files in the Perl release that contain references to Cygwin.
551These very brief notes attempt to explain the reason for all conditional
552code. Hopefully, keeping this up to date will allow the Cygwin port to
47f4f673 553be kept as clean as possible (listing not updated yet).
1cab015a 554
f8dbba82 555=over 4
1cab015a 556
f8dbba82 557=item Documentation
1cab015a 558
47dafe4d 559 INSTALL README.cygwin README.win32 MANIFEST
5d129265 560 Changes Changes5.005 Changes5.004 Changes5.6
47dafe4d
FE
561 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
562 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
9f7e07ec 563 pod/perlhist.pod pod/perlmodlib.pod perl/buildtoc pod/perltoc.pod
1cab015a 564
f8dbba82 565=item Build, Configure, Make, Install
1cab015a 566
f8dbba82
GS
567 cygwin/Makefile.SHs
568 cygwin/ld2.in
569 cygwin/perlld.in
570 ext/IPC/SysV/hints/cygwin.pl
571 ext/NDBM_File/hints/cygwin.pl
572 ext/ODBM_File/hints/cygwin.pl
573 hints/cygwin.sh
f8dbba82
GS
574 Configure - help finding hints from uname,
575 shared libperl required for dynamic loading
6b49d266
FE
576 Makefile.SH - linklibperl
577 Porting/patchls - cygwin in port list
f8dbba82 578 installman - man pages with :: translated to .
5db16f6a 579 installperl - install dll/ld2/perlld, install to pods
6b49d266 580 makedepend.SH - uwinfix
1cab015a 581
f8dbba82 582=item Tests
1cab015a 583
f8dbba82 584 t/io/tell.t - binmode
5d129265 585 t/lib/b.t - ignore Cwd from os_extras
5db16f6a
FE
586 t/lib/glob-basic.t - Win32 directory list access differs from read mode
587 t/op/magic.t - $^X/symlink WORKAROUND, s/.exe//
588 t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk
589 (cache manager sometimes preserves ctime of file
590 previously created and deleted), no -u (setuid)
75e109ec 591 t/lib/cygwin.t - builtin cygwin function tests
f8dbba82
GS
592
593=item Compiled Perl Source
594
f8dbba82
GS
595 EXTERN.h - __declspec(dllimport)
596 XSUB.h - __declspec(dllexport)
a25ce5f3 597 cygwin/cygwin.c - os_extras (getcwd, spawn, and several Cygwin:: functions)
6b49d266 598 perl.c - os_extras
f8dbba82 599 perl.h - binmode
6b49d266 600 doio.c - win9x can not rename a file when it is open
b4bcd662 601 pp_sys.c - do not define h_errno, pp_system with spawn
47dafe4d 602 util.c - use setenv
f8dbba82
GS
603
604=item Compiled Module Source
605
606 ext/POSIX/POSIX.xs - tzname defined externally
607 ext/SDBM_File/sdbm/pair.c
608 - EXTCONST needs to be redefined from EXTERN.h
609 ext/SDBM_File/sdbm/sdbm.c
610 - binary open
611
612=item Perl Modules/Scripts
613
6b49d266 614 lib/Cwd.pm - hook to internal Cwd::cwd
f8dbba82
GS
615 lib/ExtUtils/MakeMaker.pm
616 - require MM_Cygwin.pm
617 lib/ExtUtils/MM_Cygwin.pm
618 - canonpath, cflags, manifypods, perl_archive
497711e7 619 lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1
a25ce5f3 620 lib/File/Spec/Cygwin.pm - case_tolerant
6b49d266 621 lib/File/Spec/Unix.pm - preserve //unc
5d129265 622 lib/File/Temp.pm - no directory sticky bit
6b49d266 623 lib/perl5db.pl - use stdin not /dev/tty
6b49d266 624 utils/perldoc.PL - version comment
1cab015a
FE
625
626=back
f89d6eaa 627
a83b6f46 628=head1 BUGS ON CYGWIN
f8dbba82 629
125a13ce 630Support for swapping real and effective user and group IDs is incomplete.
538204d5 631On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
125a13ce
FE
632However, additional Cygwin calls for manipulating WinNT access tokens
633and security contexts are required.
634
f8dbba82
GS
635=head1 AUTHORS
636
b4bcd662 637Charles Wilson <cwilson@ece.gatech.edu>,
47dafe4d 638Eric Fifer <egf7@columbia.edu>,
b4bcd662
GS
639alexander smishlajev <als@turnhere.com>,
640Steven Morlock <newspost@morlock.net>,
641Sebastien Barre <Sebastien.Barre@utc.fr>,
a0457be1 642Teun Burgers <burgers@ecn.nl>,
a25ce5f3
RU
643Gerrit P. Haase <gp@familiehaase.de>,
644Reini Urban <rurban@cpan.org>,
645Jan Dubois <jand@activestate.com>.
f8dbba82
GS
646
647=head1 HISTORY
648
a25ce5f3 649Last updated: 2007-08-12