README.cygwin update (from Eric Fifer <EFifer@sanwaint.com>)

p4raw-id: //depot/perl@4924

1 files changed, 452 insertions, 367 deletions

diff --git a/README.cygwin b/README.cygwin
index fb93ac5157..ab60a58a0a 100644
--- a/README.cygwin
+++ b/README.cygwin
@@ -4,502 +4,587 @@ specially designed to be readable as is.
 
 =head1 NAME
 
-README.cygwin - notes about porting Perl to Cygwin
+README.cygwin - Perl for Cygwin
 
 =head1 SYNOPSIS
 
-=over
+This document will help you configure, make, test and install Perl
+on Cygwin.  This document also describes features of Cygwin that will
+affect how Perl behaves at runtime.
 
-=item Cygwin
+B<NOTE:> There are pre-built Perl packages available for Cygwin and a
+version of Perl is provided on the Cygwin CD.  If you have no need to
+customize the configuration, consider using one of these packages:
 
-The Cygwin tools are ports of the popular GNU development tools for
-Windows NT, 95, and 98.  They run thanks to the Cygwin library which
-provides the UNIX system calls and environment these programs expect.
-More info about this project can be found at its home page
-http://sourceware.cygnus.com/cygwin/
+  http://cygutils.netpedia.net/
 
-=item libperl.dll
+=head1 PREREQUISITES
 
-These instructions and the default cygwin hints build a shared
-libperl.dll Perl library and enables dynamically loaded extensions.
+=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
 
-=back
+The Cygwin tools are ports of the popular GNU development tools for Win32
+platforms.  They run thanks to the Cygwin library which provides the UNIX
+system calls and environment these programs expect.  More information
+about this project can be found at:
 
-=head1 BUILDING
-
-=head2 Prerequisites
-
-=over
-
-=item Cygwin b20.1
-
-The latest stable Cygwin suite is beta20.1.  It may be
-downloaded from ftp://go.cygnus.com/pub/sourceware.cygnus.com/cygwin/latest/
-or many mirror sites around the world.
-
-=item egcs-1.1.2
-
-This port was built with egcs-1.1.2 downloaded from
-ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin/egcs-1.1.2/
-
-=item install executable
-
-To make life easier, you should download
-ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Humblet_Pierre_A/install-cygwin-b20.sh,
-and use it as your install "executable." Just follow the instructions
-that are embedded as comments in the .sh file.
-
-=item Windows NT notes
-
-You should execute a 'chmod -R +w *' on the entire perl source directory. 
-The configuration process creates new files (and thus needs write access
-to the directory) and sometimes, especially if you make repeated builds
-in the same directory, overwrites old files. If you do not enable write
-access, you're just asking for trouble. Reminder for B20.1: unless 'ntea' 
-is included in the CYGWIN environment variable settings, chmod has no 
-effect. See "environment," below.
-
-It is best if you build, test, and install as a normal user, not as
-Administrator or as any member of the Administrators group. There is
-a well-known NT-ism that affects Cygwin: all files that are created
-by any member of the Administrators B<group> are B<NOT> owned by 
-that member. The ownership of those files is assigned to the 
-Administrators group, instead. If the default access mode for new files
-is -rw-r--r--, then the original creator of the file cannot overwrite 
-it: he no longer owns the file, no B<user> does. It is owned by the 
-group, but group members don't have write access to it. This causes 
-any number of problems, including make test / perl harness failures, 
-installation failures, etc.
-
-In some cases, however, it is necessary to install as Administrator. For 
-instance, if normal users are not allowed write access to the install 
-directory. My solution, in this case, was to transfer ownership of the 
-install directory tree (/usr/local) to a single, normal user, and 
-set permissions to -rw-r--r-- (drwxr-xr-x for directories, of course). 
-If you read the preceeding paragraph carefully, you might suspect that 
-changing the permissions on the entire tree to -rw-rw-r--, but allowing 
-the Administrators group to keep ownership should solve the problem. 
-However, newly created directories (and the perl install creates a lot 
-of them) will not allow group write access. Setting umask will not 
-fix this problem, because umask is a B<negation> operator; it only 
-specifies the types of accesses that will NOT be allowed on new files. 
-For instance, umask u=rwx,g=rwx,o=rx means that world ('B<o>thers') will 
-never be allowed write access, but owner ('B<u>ser') and B<g>roup B<might> 
-be allowed write access. Everybody (u, g, and o) B<might>be allowed 
-read access.
-
-In any case, Corinna Vinschen's ntsec patches B<may> eventually 
-alleviate this whole mess, and are included in the development 
-snapshots as of 24 May 1999. You will need to include 'ntsec' as 
-one of the items in the CYGWIN variable setting. However, initial 
-tests indicate some incompatibility the 0524 snapshot and this perl
-build.
-
-=item environment
-
-I (csw) found the following steps necessary for a successful build:
-
-=over
-
-=item path
-
-I set my path so that none of the windows directories showed up -
-otherwise Configure found the wrong executables (find, grep, etc).
-It is, however, important that '.' be in the path, because otherwise
-the build process can't execute the ld2 script that is created.
-
-=item mounts
-
-I had to unmount my f: drive. I have cygwin installed under 
-F:\cygnus\cygwin-b20\, which is mounted as \. I also ordinarily 
-have F:\ mounted as /f (i.e. mounted onto the empty directory 
-F:\cygnus\cygwin-b20\f\ ). However, this causes Configure to 
-"locate" the awk, tr, sed, etc. programs at 
-/f/cygnus/cygwin-b20/usr/bin instead of /usr/bin. 
-This ended up causing problems.
-
-I built and tested perl using all binary mounts. However, Eric Fifer 
-has built and tested it using text mounts, but reported more failures
-during make test and perl harness. Based on his findings, and experiments
-performed by Sebastien Barre with the static build of perl, I can 
-report that these test failures are B<not> due to any differences in
-the perl executable. Most of the failures encountered during a make test
-on text mounts can be eliminated by remounting as binary, and re-running
-the tests using the same executable. These test failures are due to 
-problems in the test scripts, not the executable. See Appendix.
-
-One observation from experience with the static build of perl is that
-it's a bad idea to a mix a perl executable that was compiled using binary
-mounts with modules compiled using text mounts, and vice versa. Make
-sure your mount environment matches. This observation has not been
-confirmed with respect to the dynamically linked build of perl. 
-
-=item environment variables
-
-For NT users, the CYGWIN variable should include the 'ntea' setting. 
-However, if you have FAT drives on your system, as opposed to NTFS, 
-please read the Cygwin FAQ concerning ntea before including it in 
-your system settings. If you do not use ntea, you will encounter a 
-few extra make test and/or perl harness failures. These are not 
-indicative of a faulty perl executable, but only that your system 
-settings do not allow the types of file access and ownership checking 
-that the test scripts are attempting to verify. See Appendix.
-
-I unset INCLUDE and LIB (these two variables are set by MSVC5, and 
-inherited from my Windows environment by cygwin). I'm not sure this made 
-a difference, but it has caused problems in the past...
+  http://sourceware.cygnus.com/cygwin/
 
-=back
+A recent net or commercial release of Cygwin is required.
 
-=item crypt library
+At the time this document was written, the port required recent
+development snapshots that were expected to stabilize early in 2000 and
+be released to the net as B21 and commercially as v1.1.
 
-http://miracle.geol.msu.ru/sos/ points to two different crypt
-libraries ported to cygwin.  This has been tested with the libcrypt.tgz
-by Andy Piper. His home page can be found at
-http://www.xemacs.freeserve.co.uk/
+B<NOTE:> At this point, minimal effort has been made to provide
+compatibility with old (beta) Cygwin releases.  The focus has been to
+provide a high quality release and not worry about working around old
+Cygwin bugs.  If you wish to use Perl with Cygwin B20.1 or earlier,
+consider using either perl5.005_03 or perl5.005_62, which are available
+in source and binary form at C<http://cygutils.netpedia.net/> or on the
+Cygwin CD.  If there is significant demand, a patch kit can be developed
+to port back to earlier Cygwin versions.
 
-=item hacks that should be revisited after the next cygwin release
+=head2 Compiler
 
-Some of the failures we encountered when running make test and/or perl harness
-are due to bugs in the cygwin b20.1 distribution. We sometimes found it
-necessary to use dirty little hacks to persuade make test and perl harness
-to play nicely. Since cygwin is in active development, many of these hacks 
-may not be necessary in the future. These include:
+A recent net or commercial release of I<gcc> is required.
 
-=over
+At the time this document was written, I<gcc-2.95.2> was current and
+could be downloaded from:
 
-=item fix for pragma/locale
+  ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin/gcc-2.95.2/
 
-the line '#undef MB_CUR_MAX' was added to ex/POSIX/POSIX.xs. This fixes
-a failure in the pragma/locale.t test, which before this fix resulted in a 
-coredump. It appears that MB_CUR_MAX is #defined __mb_cur_max, and __mb_cur_max
-is declared 'extern' in Cygwin b20.1's stdlib.c, but is never defined. Thus,
-the error.
+=head2 Cygwin Configuration
 
-=item fix for lib/io_sock
+While building Perl some changes may be necessary to your Cygwin setup so
+that Perl builds cleanly.  These changes are B<not> required for normal
+Perl usage.
 
-there is a rather extensive patch to t/lib/io_sock.t which works around
-a failure related to fork() in the cygwin environment. Cygwin b20.1 does not 
-properly remap manually loaded DLLs in the child after a fork.
+B<NOTE:> The binaries that are built will run on all Win32 versions.
+They do not depend on your host system (Win9x, WinNT) or your Cygwin
+configuration (I<ntea>, I<ntsec>, binary/text mounts).  The only
+dependencies come from hardcoded pathnames like C</usr/local>.  However,
+your host system and Cygwin configuration will affect Perl's runtime
+behavior (see L</"TEST">).  Some regression tests may fail in different
+ways depending on your setup.  For now, the test suite does not skip
+tests that do not make sense given a particular setup.  If a test can
+pass in some Cygwin setup, it is left in and explainable test failures
+are documented.
 
-=item fix for lib/filehand
+=over 4
 
-during the make test/perl harness steps, a win32 popup complains about 
-a "perl.exe Application Error - illegal memory access." This is due to to
-a test in t/lib/filehand.t, and is related to the fork + dll problem.
+=item * C<PATH>
 
-=item fix for environ
+Set the C<PATH> environment variable so that Configure finds the Cygwin
+versions of programs.  Any Windows directories should be removed or
+moved to the end of your C<PATH>.
 
-there are a number of changes to miniperlmain.c, util.c, and mg.c that
-are there to work around a Cygwin problem relating to environ.
+=item * F</bin/cat.exe>
 
-=item fix for lib/posix
+There should be an instance of I<cat> in F</bin> (or F</usr/bin>).
+Configure tests C<#!/bin/cat> and if it is not found, you will see
+the error:
 
-the following line was added to t/lib/posix.t to work around a Cygwin bug.
+  Configure: ./try: No such file or directory
 
-=begin text
+=item * F</usr/bin>
 
-kill 'CONT', $$ if($^O =~ /cygwin/); # XXX: Cygwin bug INT signal gets stuck
+If you do not have a F</usr/bin> directory, Configure will B<not> prompt
+you to install I<perl> into F</usr/bin>.
 
-=end text
+=item * I<nroff>
 
-=back
+If you do not have I<nroff> (which is part of the I<groff> package),
+Configure will B<not> prompt you to install man pages.
+
+=item * Permissions
+
+On WinNT with either the I<ntea> or I<ntsec> C<CYGWIN> settings, directory
+and file permissions may not be set correctly.  Since the build process
+creates files and directories, to be safe you may want to run a `C<chmod
+-R +w *>' on the entire Perl source tree.
+
+Also, it is a well known WinNT "feature" that files created by a login
+that is a member of the I<Administrators> group will be owned by the
+I<Administrators> group.  Depending on your umask, you may find that you
+can not write to files that you just created (because you are no longer
+the owner).  When using the I<ntsec> C<CYGWIN> setting, this is not an
+issue because it "corrects" the ownership to what you would expect on
+a UNIX system.
 
 =back
 
-=head2 Configure
+=head1 CONFIGURE
 
-Check hints/cygwin.sh for any system specific settings.  In
-particular change libpth to point to the correct location of
-...../i586-cygwin32/lib.
+The default options gathered by Configure with the assistance of
+F<hints/cygwin.sh> will build a Perl that supports dynamic loading
+(which requires a shared F<libperl.dll>).
 
-run "sh Configure".  
+This will run Configure and keep a record:
 
-When confronted with this prompt:
+  ./Configure 2>&1 | tee log.configure
 
-=begin text
+If you are willing to accept all the defaults add a B<-d> option.
+However, several useful customizations are available.
 
-	First time through, eh?  I have some defaults handy for the
-	following systems:
-	   .
-	   .
-	   .
-	Which of these apply, if any?
+=head2 Strip Binaries
 
-=end text
+It is possible to strip the EXEs and DLLs created by the build process.
+The resulting binaries will be significantly smaller.  If you want the
+binaries to be stripped, you can either add a B<-s> option when Configure
+prompts you,
 
-select "cygwin".
+  Any additional ld flags (NOT including libraries)? [none] -s
+  Any special flags to pass to gcc to use dynamic loading? [none] -s
+  Any special flags to pass to ld2 to create a dynamically loaded library?
+  [none] -s
 
-Do not use the malloc that comes with perl--using the perl malloc
-collides with some cygwin startup routines. 
+or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
+near the end of the file.
 
-=head2 make
+=head2 Optional Libraries
 
-Run "make". If you're really feeling adventurous, type 
-"make 2>&1 | tee make-log.txt".
+Several Perl functions and modules depend on the existence of
+some optional libraries.  Configure will find them if they are
+installed in one of the directories listed as being used for library
+searches.  Pre-built packages for most of these are available at
+C<http://cygutils.netpedia.net/>.
 
-=over
+=over 4
 
-=item ld2
+=item * C<-lcrypt>
 
-The make script will install ld2 into your $installbin directory (i.e.
-wherever you said to put the perl.exe) during the *make* process. It 
-does not wait until the *make install* process to install the ld2 script.
-This is because the remainder of the make refers to ld2 without fully
-specifying its path, and does this from multiple subdirectories (so ./ld2
-won't work.) The assumption here is that $installbin is in your current
-$PATH. If this is not the case, or if you do not have an install 
-executable, the make will fail at some point. Don't panic. Just manually
-copy ld2 from the source directory to someplace in your path.
+The crypt libraries in GNU libc have been ported to Cygwin.
 
-This cannot be done prior to make, because ld2 is created during the
-make process.
+The DES based Ultra Fast Crypt port was done by Alexey Truhan
 
-=back
+  http://dome.weeg.uiowa.edu/pub/domestic/sos/cw32crypt-dist-0.tgz
+
+NOTE: There are various export restrictions on DES implementations,
+see the glibc README for more details.
 
-=head2 make test
+The MD5 port was done by Andy Piper:
 
-Run "make test" to see how stable your system is. I (csw) got the 
-following errors/warnings:
+  http://dome.weeg.uiowa.edu/pub/domestic/sos/libcrypt.tgz
 
-=over
+More information can also be found at:
 
-=item op/taint
+  http://miracle.geol.msu.ru/sos/
 
-Got two "missing cygwin1.dll" warning popups. This is because
-op/taint wants cygwin1.dll to be somewhere in the system path 
-(\WINDOWS\SYSTEM, etc) or in the build directory. Can be ignored.
+=item * C<-lgdbm> (C<use GDBM_File>)
 
-=item lib/filehand
+GDBM is available for Cygwin.  GDBM's ndbm/dbm compatibility feature
+also makes C<NDBM_File> and C<ODBM_File> possible (although they add
+little extra value).
 
-Got an "Application Error - memory could not be read" popup. While 
-this looks alarming, it can be ignored - just click OK. It is 
-because Cygwin B20.1 doesn't properly remap manually loaded DLLs 
-in the child after a fork.
+=item * C<-ldb> (C<use DB_File>)
 
-=item lib/io_sock
+BerkeleyDB is available for Cygwin.  Some details can be found in
+F<ext/DB_File/DB_File.pm>.
 
-Got an "Application Error - memory could not be read" popup. Again,
-just click OK and ignore it.
+=item * C<-lcygipc> (C<use IPC::SysV>)
+
+A port of SysV IPC is available for Cygwin:
+
+  http://www.multione.capgemini.fr/tools/pack_ipc/
+
+The 1.3 release does not include ftok(), but code for ftok() can be
+borrowed from glibc.
 
 =back
 
-=head2 perl harness
+=head2 Configure-time Options
+
+The F<INSTALL> document describes several Configure-time options.
+Some of these will work with Cygwin, others are not yet possible.  Also,
+some of these are experimental.
+
+=over 4
+
+=item * C<-Uusedl>
+
+If you want to force Perl to be compiled statically, you can either
+choose this when Configure prompts you or you can use the Configure
+command line option.
+
+=item * C<-Uusemymalloc>
 
-Once you've run make test, then cd into the t/ subdirectory and
-execute './perl harness'. I (csw) got the following results:
+By default Perl uses the malloc() included with the Perl source.  If you
+want to force Perl to build with the system malloc(), you can either
+choose this when Configure prompts you or you can use the Configure
+command line option.
 
-=over
+=item * C<-Dusemultiplicty>
 
-=item op/taint
+Multiplicity is required when embedding Perl in a C program and using
+more than one interpreter instance.  This works with the Cygwin port.
 
-Got four "missing cygwin1.dll" warning popups. Click OK and
-ignore.
+=item * C<-Duseperlio>
 
-=item lib/filehand
+The PerlIO abstraction works with the Cygwin port.
 
-Got an "Application Error - memory could not be read" popup. Again,
-click OK and ignore.
+=item * C<-Duse64bits -Duselonglong>
 
-=item lib/io_sock
+I<gcc> supports 64-bit integers.  However, several additional long long
+functions are necessary to use them within Perl (I<{atol,strtoul}l>).
+These are B<not> yet available with Cygwin.
 
-Got an "Application Error - memory could not be read" popup. Again,
-clock OK and ignore.
+=item * C<-Duselongdouble>
 
-=item final results
+I<gcc> supports long doubles (12 bytes).  However, several additional
+long double math functions are necessary to use them within Perl
+(I<{sqrt,pow,atan2,exp,fmod,log,cos,frexp,sin,floor,modf,atof}l>).
+These are B<not> yet available with Cygwin.
 
-After the ./perl harness, I got the following results summary.
+=item * C<-Dusethreads>
 
- Failed Test  Status Wstat Total Fail  Failed  List of failed
- -------------------------------------------------------------------------------
- op/taint.t                  149    3   2.01%  1, 3, 31
- 9 tests skipped, plus 35 subtests skipped.
- Failed 1/190 test scripts, 99.47% okay. 3/6452 subtests failed, 99.95% okay.
+POSIX threads are B<not> yet implemented in Cygwin.
+
+=item * C<-Duselargefiles>
+
+Although Win32 supports large files, Cygwin currently uses 32-bit ints
+for internal size and positional calculations.
 
 =back
 
-=head2 make install
+=head2 Suspicious Warnings
 
-Finally, run "make install". In my case, the install process was unable
-to copy the files from <SRCDIR>/pod/* to /usr/local/lib/perl5/5.00503/pod/.
-I (csw) just copied them by hand after the install finished. I believe
-this is because I'm using Sergey Okhapkin's coolview version of the
-cygwin1.dll, which provides case sensitivity. The directory is created
-as "/usr/local/lib/perl5/5.00503/Pod" but the copy is done into
-"/usr/local/lib/perl5/5.00503/pod". This fails -- but probably won't 
-fail if you're using the default cygwin1.dll.
+You may see some messages during Configure that seem suspicious.
 
-=head1 BUGS
+=over 4
 
-A lot of warnings about incompatible pointer types and comparison
-lacking a cast.  This is because of __declspec(dllimport).
+=item * Whoa There
 
-Upon each start, make warns that a rule for perlmain.o is overrided.
-Yes, it is.  In order to use libperl.dll, perlmain needs to import
-symbols from there.  According to alex smishlajev, there seems to be 
-no better solution than adding an explicit define to the rule.
+Cygwin does not yet implement chroot(), setegid() or seteuid()
+functionality, but has stub functions that return C<ENOSYS>.  You will
+see a message when Configure detects that its guess conflicts with the
+hint file.
 
-make clean does not remove library .def and .exe.core files.
+  *** WHOA THERE!!! ***
+      The recommended value for $d_chroot on this machine was "undef"!
+      Keep the recommended value? [y]
 
-ld2 script is installed with reference to source directory.  You should
-change this to /usr/local/bin (or whatever) after install.
+You should keep the recommended value.
 
-.bat wrappers for installed utility scripts are not made during installation.
+=item * Checking how std your stdio is...
 
-=head1 AUTHOR
+Configure reports:
 
-alexander smishlajev <als@turnhere.com>
+  Your stdio doesn't appear very std.
 
-=head1 DISCLAIMER
+This is correct.
 
-I (alex) am not going to maintain this document or this port.  I only wanted
-to make perl porting a bit easier.  If failed, I can't be helpful for you.
-Contact one of the others listed in the history section.
+=head1 MAKE
 
-=head1 HISTORY
+Simply run make and wait:
+
+  make 2>&1 | tee log.make
+
+=head2 Warnings
+
+Warnings like these are normal:
+
+  warning: overriding commands for target <file>
+  warning: ignoring old commands for target <file>
+
+  Warning: no export definition file provided
+  dllwrap will create one, but may not be what you want
+
+=head2 ld2
+
+During `C<make>', I<ld2> will be created and installed in your $installbin
+directory (where you said to put public executables).  It does not
+wait until the `C<make install>' process to install the I<ld2> script,
+this is because the remainder of the `C<make>' refers to I<ld2> without
+fully specifying its path and does this from multiple subdirectories.
+The assumption is that $installbin is in your current C<PATH>.  If this
+is not the case or if you do not have an I<install> program, `C<make>'
+will fail at some point.  If this happens, just manually copy I<ld2>
+from the source directory to someplace in your C<PATH>.
+
+=head1 TEST
+
+There are two steps to running the test suite:
+
+  make test 2>&1 | tee log.make-test
+
+  cd t;./perl harness 2>&1 | tee ../log.harness
+
+The same tests are run both times, but more information is provided when
+running as `C<./perl harness>'.
 
-=over
+Test results vary depending on your host system and your Cygwin
+configuration.  It is possible that Cygwin will pass all the tests, but it
+is more likely that some tests will fail for one of the the reasons below.
 
-=item Release 1.4.1: 28-May-1999
+=head2 File Permissions
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+UNIX file permissions are based on sets of mode bits for
+{read,write,execute} for each {user,group,other}.  By default Cygwin only
+tracks the Win32 readonly attribute represented as the UNIX file user
+write bit (files are always readable, files are executable if they have
+a F<.{com,bat,exe}> extension or begin with C<#!>, directories are always
+readable and executable).  On WinNT with the I<ntea> C<CYGWIN> setting,
+the remaining mode bits are stored as extended attributes.  On WinNT
+with the I<ntsec> C<CYGWIN> setting, permissions use the standard WinNT
+security descriptors and access control lists.  Without one of these
+options, these tests will fail:
 
-   Configure               minor fix for spaces in $PATH
-   documentation updates
+  Failed Test           List of failed
+  ------------------------------------
+  io/fs.t               5, 7, 9-10
+  lib/anydbm.t          2
+  lib/db-btree.t        20
+  lib/db-hash.t         16
+  lib/db-recno.t        18
+  lib/gdbm.t            2
+  lib/glob-basic.t      9 (directory always readable)
+  lib/ndbm.t            2
+  lib/odbm.t            2
+  lib/sdbm.t            2
+  op/stat.t             9, 20 (.tmp not an executable extension)
 
-=item Release 1.4: 26-May-1999
+=head2 Hard Links
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+FAT partitions do not support hard links (whereas NTFS does), in which
+case Cygwin implements link() by copying the file.  These tests will fail:
 
- From Eric Fifer:
-   hints/cygwin32.sh       -L. and --export-dynamic not needed
-   cygwin32/Makefile.SHs   no value needed for -DUSEIMPORTLIB
-   t/lib/io_sock.t         -I../lib so "make test" works
-   t/lib/posix.t           workaround a Cygwin bug so test works
-   doio.c/perl.h           cleanup gcc warning "doio.c:789: warning:
-                                pointer/integer type mismatch in 
-                                conditional expression"
- From Charles Wilson:
-   Configure               changes to findhdr script
-   documentation updates
-   built binary kit for release
+  Failed Test           List of failed
+  ------------------------------------
+  io/fs.t               4
+  op/stat.t             3
 
-=item Release 1.3: 26-May-1999
+=head2 Filetime Granularity
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+On FAT partitions the filetime granularity is 2 seconds.  The following
+test will fail:
 
- Changes to Cwd.pm to correct lib/findbin.t test failure from Eric Fifer
- Changes to t/op/magic.t to correct a test failure from Eric Fifer
- Changes to miniperlmain.c, util.c, and mg.c to correct t/op/magic.t #29
-    test failure, from Eric Fifer
- more documentatino updates, patch merging, and a change to 
-    cygwin/Makefile.SHs -- cw.
- 99.95% okay!!!
+  Failed Test           List of failed
+  ------------------------------------
+  io/fs.t               18
 
-=item Release 1.2: 25-May-1999
+=head2 Tainting Checks
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+When Perl is running in taint mode, C<$ENV{PATH}> is considered tainted
+and not used, so DLLs not in the default system directories will not
+be found.  While the tests are running you will see warnings popup from
+the system with messages like:
 
- fixes for lib/io_sock and pragma/locale from Eric Fifer
- fixes for Configure, Makefile.SH, and cygwin32/Makefile.SHs from
-    alex smishlajev
- documentation updates, and other fixes to the fixes from cw.
- 99.91% okay!!!
+  Win9x
+    Error Starting Program
+    A required .DLL file, CYGWIN1.DLL, was not found
 
-=item Release 1.1: 21-May-1999
+  WinNT
+    perl.exe or sh.exe - Unable to Locate DLL
+    The dynamic link library cygwin1.dll could not be found in the
+      specified path ...
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+Just click OK and ignore them.  When running `C<make test>', 2 popups
+occur.  During `C<./perl harness>', 4 popups occur.  Also, these tests
+will fail:
 
-minor change to Configure script, reversed a few changes made by
-alexander's patch (made DOSISH #undefined again) and moved code
-by alexander from dosish.h to perl.h. Reversed a change in 
-pp_hot.c
+  Failed Test           List of failed
+  ------------------------------------
+  op/taint.t            1, 3, 31, 37
 
-=item Release 1.0: 16-May-1999
+Alternatively, you can copy F<cygwin1.dll> into one of the Windows system
+directories (although, this is B<not> recommended).
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+=head2 /etc/group
 
-Merged alexander's patch and Eric's patch into a single
-monolithic patch. Minor cleanup. Built binary for distribution.
-perl5.005_03-dynamic-patch-v1.0
+Cygwin does not need F</etc/group>, in which case the F<op/grent.t>
+test will be skipped.  The check performed by F<op/grent.t> expects to
+see entries that use the members field, otherwise this test will fail:
 
-=item Pre-release 3: 12-May-1999 
+  Failed Test           List of failed
+  ------------------------------------
+  op/grent.t            1
 
-Eric Fifer  -  efifer@sanwaint.com
+=head2 Unexplained Failures
 
-Removed all references to the impure_ptr hack since it is no longer
-needed.  Some minor cleanup of alexander smishlajev's work and a few
-bug fixes.
+Any additional tests that fail are likely due to bugs in Cygwin.  It is
+expected that by the time of the next net release most of these will
+be solved so they are not described here.  None of the current bugs are
+serious enough that workarounds are needed.
 
-=item Pre-release 2 (initial dynamic build): 17..25-apr-1999
+=head2 Script Portability
 
-alexander smishlajev  -  als@turnher.com
+Cygwin does an outstanding job of providing UNIX-like semantics on top
+of Win32 systems.  However, in addition to the items noted above, there
+are some differences that you should know about.  This is only a very
+brief guide to portability, more information about Cygwin can be found
+in the Cygwin documentation.
 
-perl 5.005_03.  cygwin b20.1  egcs 1.1.2.  far 1.60.  nescafe classic.
+=over 4
 
-=item Pre-release 1 (static build): 5-Mar-1999
+=item * Pathnames
 
-Charles Wilson  -  cwilson@ece.gatech.edu
+Cygwin pathnames can be separated by forward (F</>) or backward (F<\>)
+slashes.  They may also begin with drive letters (F<C:>) or Universal
+Naming Codes (F<//UNC>).  DOS device names (F<aux>, F<con>, F<prn>,
+F<com*>, F<lpt?>) are invalid as base filenames.  However, they can be
+used in extensions (e.g., F<hello.aux>).  Names may not contain these
+characters:
 
-Collected various patches that had been floating around the net, along
-with build instructions.  Original authorship credit for those patches
-goes to:
+  : * ? " < > |
 
- Steven Morlock  -  newspost@morlock.net
- Sebastien Barre -  Sebastien.Barre@utc.fr
- Teun Burgers    -  burgers@ecn.nl
+File names are case insensitive, but case preserving.  With the I<mixed>
+C<CYGWIN> setting, file names are mixed-case (although, directory names
+remain case insensitive).
 
-Created a monolithic patchkit (perl5.005_03-static-patch) and build
-instructions for cygwin (beta 20.1). Also created a binary distribution
-of the resulting static perl build.
+The I<mixed> setting is only available with the "coolview" version of
+F<cygwin1.dll> provided by Sergey Okhapkin at:
+
+  ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/
+
+=item * Text/Binary
+
+When a file is opened it is in either text or binary mode.  In text mode
+it is subject to CR/LF/Ctrl-Z translations.  Perl provides a binmode()
+function to force binary mode on files that otherwise would be treated
+as text.  With Cygwin, the default mode for an open() is determined by the
+mode of the mount that underlies a file.  For binmode() to be effective,
+the underlying mount must be text.  There is no way to force text mode
+on a file underneath a binary mount.  The text/binary issue is covered
+at length in the Cygwin documentation.
+
+lseek() only works with files opened in binary mode.
+
+=item * F<.exe>
+
+The Cygwin stat() makes the F<.exe> extension transparent by looking for
+a F<foo.exe> when you ask for F<foo> (unless a F<foo> also exists).
+Cygwin does not require a F<.exe> extension, but I<gcc> adds it
+automatically when building a program.  However, when accessing an
+executable as a normal file (e.g., I<install> or I<cp> in a makefile)
+the F<.exe> is not transparent.
+
+NOTE: There is a version of I<install> that understands F<.exe>, it can
+be found at:
+
+  ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Humblet_Pierre_A/
+
+=item * chown()
+
+On WinNT with the I<ntsec> C<CYGWIN> setting, chown() can change a file's
+user and group IDs.  In all other configurations chown() is a no-op,
+although this is appropriate on Win9x since there is no security model.
+
+=item * Miscellaneous
+
+File locking using the C<F_GETLK> command to fcntl() is a stub that
+returns C<ENOSYS>.
+
+Win32 can not unlink() an open file (but this is emulated by Cygwin).
+
+Win9x can not rename() an open file (although WinNT can).
 
 =back
 
-=head1 APPENDIX
+=head1 INSTALL
+
+This will install Perl, including man pages.
+
+  make install 2>&1 | tee log.make-install
 
-Perl harness results from Eric Fifer, under various environments. The same
-executable was used in all cases. The last item is a different executable
-on a different machine, built by Charles Wilson.
+You may need to be I<Administrator> to run `C<make install>'.  If you
+are not, you must have write access to the directories in question.
 
-There are a number of very good questions one could ask about anomalies 
-in the test results presented below. "Why do the last two show different
-results?" "Why did op/stat.t #18 pass in the first two tests and fail in
-the third?" Short answer: I don't know. Long answer: I really have no
-idea.
+Information on installing the Perl documentation in HTML format can be
+found in the F<INSTALL> document.
 
-=over
+=head1 MANIFEST
 
-=item text mounts, no 'ntea'
+These are the files in the Perl release that contain references to Cygwin.
+These very brief notes attempt to explain the reason for all conditional
+code.  Hopefully, keeping this up to date will allow the Cygwin port to
+be kept as clean as possible.
 
- Failed Test  Status Wstat Total Fail  Failed  List of failed
- ------------------------------------------------------------
- lib/anydbm.t      2   512    12    8  66.67%  5-12
- lib/sdbm.t        2   512    18   15  83.33%  2, 5-18
- op/split.t                   25    1   4.00%  11
- op/stat.t                    58    3   5.17%  9, 19, 26
- op/taint.t                  149    3   2.01%  1, 3, 31
+=over 4
 
-=item binary mounts, no 'ntea'
+=item Documentation
 
- Failed Test  Status Wstat Total Fail  Failed  List of failed
- ------------------------------------------------------------
- lib/sdbm.t                   18    1   5.56%  2
- op/stat.t                    58    3   5.17%  9, 19, 26
- op/taint.t                  149    3   2.01%  1, 3, 31
+  INSTALL
+  Changes Changes5.005 Changes5.004
+  AUTHORS MAINTAIN MANIFEST
+  README.cygwin README.win32
+  pod/perl.pod pod/perlfaq3.pod pod/perlhist.pod pod/perlmodlib.pod
+  pod/perlport.pod pod/perltoc.pod pod/perl5004delta.pod
 
-=item binary mounts, 'ntea'
+=item Build, Configure, Make, Install
 
- Failed Test  Status Wstat Total Fail  Failed  List of failed
- ------------------------------------------------------------
- op/stat.t                    58    3   5.17%  18-19, 26
- op/taint.t                  149    3   2.01%  1, 3, 31
+  cygwin/Makefile.SHs
+  cygwin/ld2.in
+  cygwin/perlld.in
+  ext/IPC/SysV/hints/cygwin.pl
+  ext/NDBM_File/hints/cygwin.pl
+  ext/ODBM_File/hints/cygwin.pl
+  hints/cygwin.sh
+  Porting/patchls       - cygwin in port list
+  Makefile.SH           - linklibperl, cygwin/Makefile.SHs
+  makedepend.SH         - uwinfix
+  Configure             - help finding hints from uname,
+                          shared libperl required for dynamic loading
+  installman            - man pages with :: translated to .
+  installperl           - install dll, install to pods
 
-=item binary mounts, ntea (csw build)
+=item Tests
 
- Failed Test  Status Wstat Total Fail  Failed  List of failed
- -------------------------------------------------------------------------------
- op/taint.t                  149    3   2.01%  1, 3, 31
+  t/io/tell.t           - binmode
+  t/op/magic.t          - $^X WORKAROUND, s/.exe//
+  t/op/stat.t           - no /dev, no -u (setuid)
+
+=item Compiled Perl Source
+
+  doio.c                - win9x can not rename a file when it is open
+  EXTERN.h              - __declspec(dllimport)
+  XSUB.h                - __declspec(dllexport)
+  perl.h                - binmode
+  mg.c                  - environ WORKAROUND
+  util.c                - environ WORKAROUND
+  unixish.h             - environ WORKAROUND
+
+=item Compiled Module Source
+
+  ext/POSIX/POSIX.xs    - tzname defined externally
+  ext/SDBM_File/sdbm/pair.c
+                        - EXTCONST needs to be redefined from EXTERN.h
+  ext/SDBM_File/sdbm/sdbm.c
+                        - binary open
+
+=item Perl Modules/Scripts
+
+  lib/perl5db.pl        - use stdin not /dev/tty
+  utils/perlcc.PL       - DynaLoader.a in compile, -DUSEIMPORTLIB
+  utils/perldoc.PL      - version comment
+  lib/File/Spec/Unix.pm - preserve //unc
+  lib/ExtUtils/MakeMaker.pm
+                        - require MM_Cygwin.pm
+  lib/ExtUtils/MM_Cygwin.pm
+                        - canonpath, cflags, manifypods, perl_archive
+  lib/Cwd.pm            - `pwd`
 
 =back
 
-=cut
+=head1 BUGS
+
+Upon each start, I<make> warns that a rule for F<perlmain.o> is overridden
+(but there seems to be no better solution than adding an explicit define).
+
+`C<make clean>' does not remove library F<.def> and F<.exe.stackdump>
+files.
+
+The I<ld2> script contains references to the source directory.  You should
+change these to C</usr/local/bin> (or whatever) after install.
+
+=head1 AUTHORS
+
+Charles Wilson E<lt>cwilson@ece.gatech.eduE<gt>,
+Eric Fifer E<lt>efifer@sanwaint.comE<gt>,
+alexander smishlajev E<lt>als@turnhere.comE<gt>,
+Steven Morlock E<lt>newspost@morlock.netE<gt>,
+Sebastien Barre E<lt>Sebastien.Barre@utc.frE<gt>,
+Teun Burgers E<lt>burgers@ecn.nlE<gt>.
+
+=head1 HISTORY
+
+Last updated: 28 January 2000