--- /dev/null
+If you read this file _as_is_, just ignore the funny characters you
+see. It is written in the POD format (see pod/perlpod.pod) which is
+specially designed to be readable as is.
+
+=head1 NAME
+
+README.cygwin - Perl for Cygwin
+
+=head1 SYNOPSIS
+
+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.
+
+B<NOTE:> There are pre-built Perl packages available for Cygwin and a
+version of Perl is provided on the Cygwin CD. If you do not need to
+customize the configuration, consider using one of these packages:
+
+ http://cygutils.netpedia.net/
+
+=head1 PREREQUISITES
+
+=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
+
+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:
+
+ http://www.cygwin.com/
+
+A recent net or commercial release of Cygwin is required.
+
+At the time this document was last updated, Cygwin 1.1.5 was current.
+
+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
+bugs. If you wish to use Perl with Cygwin B20.1 or earlier, consider
+using perl5.005_03, which is available in source and binary form at
+C<http://cygutils.netpedia.net/>. If there is significant demand,
+a patch kit can be developed to port back to earlier Cygwin versions.
+
+=head2 Cygwin Configuration
+
+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.
+
+B<NOTE:> The binaries that are built will run on all Win32 versions.
+They do not depend on your host system (Win9x/WinME, WinNT/Win2K)
+or your Cygwin configuration (I<ntea>, I<ntsec>, binary/text mounts).
+The only dependencies come from hard-coded pathnames like C</usr/local>.
+However, your host system and Cygwin configuration will affect Perl's
+runtime behavior (see L</"TEST">).
+
+=over 4
+
+=item * C<PATH>
+
+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>.
+
+=item * I<nroff>
+
+If you do not have I<nroff> (which is part of the I<groff> package),
+Configure will B<not> prompt you to install I<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 directories and files, 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
+
+=head1 CONFIGURE
+
+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>).
+
+This will run Configure and keep a record:
+
+ ./Configure 2>&1 | tee log.configure
+
+If you are willing to accept all the defaults run Configure with B<-de>.
+However, several useful customizations are available.
+
+=head2 Strip Binaries
+
+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,
+
+ Any additional ld flags (NOT including libraries)? [none] -s
+ Any special flags to pass to gcc to use dynamic linking? [none] -s
+ Any special flags to pass to ld2 to create a dynamically loaded library?
+ [none] -s
+
+or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
+near the end of the file.
+
+=head2 Optional Libraries
+
+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 4
+
+=item * C<-lcrypt>
+
+The crypt package distributed with Cygwin is a Linux compatible 56-bit
+DES crypt port by Corinna Vinschen.
+
+Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.
+
+The DES based Ultra Fast Crypt port was done by Alexey Truhan:
+
+ ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz
+
+NOTE: There are various export restrictions on DES implementations,
+see the glibc README for more details.
+
+The MD5 port was done by Andy Piper:
+
+ ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz
+
+=item * C<-lgdbm> (C<use GDBM_File>)
+
+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).
+
+NOTE: The ndbm/dbm emulations only completely work on NTFS partitions.
+
+=item * C<-ldb> (C<use DB_File>)
+
+BerkeleyDB is available for Cygwin. Some details can be found in
+F<ext/DB_File/DB_File.pm>.
+
+NOTE: The BerkeleyDB library only completely works on NTFS partitions.
+
+=item * C<-lcygipc> (C<use IPC::SysV>)
+
+A port of SysV IPC is available for Cygwin.
+
+NOTE: This has B<not> been extensively tested. In particular,
+C<d_semctl_semun> is undefined because it fails a Configure test
+and on Win9x the I<shm*()> functions seem to hang. It also creates
+a compile time dependency because F<perl.h> includes F<<sys/ipc.h>>
+and F<<sys/sem.h>> (which will be required in the future when compiling
+CPAN modules).
+
+=back
+
+=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. You can either select an option when Configure
+prompts you or you can define (undefine) symbols on the command line.
+
+=over 4
+
+=item * C<-Uusedl>
+
+Undefining this symbol forces Perl to be compiled statically.
+
+=item * C<-Uusemymalloc>
+
+By default Perl uses the malloc() included with the Perl source. If you
+want to force Perl to build with the system malloc() undefine this symbol.
+
+=item * C<-Dusemultiplicity>
+
+Multiplicity is required when embedding Perl in a C program and using
+more than one interpreter instance. This works with the Cygwin port.
+
+=item * C<-Duseperlio>
+
+The PerlIO abstraction works with the Cygwin port.
+
+=item * C<-Duse64bitint>
+
+I<gcc> supports 64-bit integers. However, several additional long long
+functions are necessary to use them within Perl (I<{strtol,strtoul}l>).
+These are B<not> yet available with Cygwin.
+
+=item * C<-Duselongdouble>
+
+I<gcc> supports long doubles (12 bytes). However, several additional
+long double math functions are necessary to use them within Perl
+(I<{atan2,cos,exp,floor,fmod,frexp,isnan,log,modf,pow,sin,sqrt}l,strtold>).
+These are B<not> yet available with Cygwin.
+
+=item * C<-Dusethreads>
+
+POSIX threads are B<not> yet implemented in Cygwin.
+
+=item * C<-Duselargefiles>
+
+Although Win32 supports large files, Cygwin currently uses 32-bit integers
+for internal size and position calculations.
+
+=back
+
+=head2 Suspicious Warnings
+
+You may see some messages during Configure that seem suspicious.
+
+=over 4
+
+=item * I<dlsym()>
+
+I<ld2> is needed to build dynamic libraries, but it does not exist
+when dlsym() checking occurs (it is not created until `C<make>' runs).
+You will see the following message:
+
+ Checking whether your dlsym() needs a leading underscore ...
+ ld2: not found
+ I can't compile and run the test program.
+ I'm guessing that dlsym doesn't need a leading underscore.
+
+Since the guess is correct, this is not a problem.
+
+=item * Win9x and C<d_eofnblk>
+
+Win9x does not correctly report C<EOF> with a non-blocking read on a
+closed pipe. You will see the following messages:
+
+ But it also returns -1 to signal EOF, so be careful!
+ WARNING: you can't distinguish between EOF and no data!
+
+ *** WHOA THERE!!! ***
+ The recommended value for $d_eofnblk on this machine was "define"!
+ Keep the recommended value? [y]
+
+At least for consistency with WinNT, you should keep the recommended
+value.
+
+=item * Compiler/Preprocessor defines
+
+The following error occurs because of the Cygwin C<#define> of
+C<_LONG_DOUBLE>:
+
+ Guessing which symbols your C compiler and preprocessor define...
+ try.c:<line#>: parse error
+
+This failure does not seem to cause any problems.
+
+=back
+
+=head1 MAKE
+
+Simply run I<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>
+
+ dllwrap: no export definition file provided
+ dllwrap: creating one, but that 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 `C<make>' will fail at some point. If this happens,
+just manually copy I<ld2> from the source directory to somewhere 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>'.
+
+Test results vary depending on your host system and your Cygwin
+configuration. If a test can pass in some Cygwin setup, it is always
+attempted and explainable test failures are documented. It is possible
+for Perl to pass all the tests, but it is more likely that some tests
+will fail for one of the reasons listed below.
+
+=head2 File Permissions
+
+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 read-only 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 additional mode bits are stored as extended file 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:
+
+ 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/ndbm.t 2
+ lib/odbm.t 2
+ lib/sdbm.t 2
+ op/stat.t 9, 20 (.tmp not an executable extension)
+
+=head2 Hard Links
+
+FAT partitions do not support hard links (whereas NTFS does), in which
+case Cygwin implements link() by copying the file. On remote (network)
+drives Cygwin's stat() always sets C<st_nlink> to 1, so the link count
+for remote directories and files is not available. In either case,
+these tests will fail:
+
+ Failed Test List of failed
+ ------------------------------------
+ io/fs.t 4
+ op/stat.t 3
+
+=head2 Filetime Granularity
+
+On FAT partitions the filetime granularity is 2 seconds. The following
+test will fail:
+
+ Failed Test List of failed
+ ------------------------------------
+ io/fs.t 18
+
+=head2 Tainting Checks
+
+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:
+
+ Win9x
+ Error Starting Program
+ A required .DLL file, CYGWIN1.DLL, was not found
+
+ WinNT
+ perl.exe - Unable to Locate DLL
+ The dynamic link library cygwin1.dll could not be found in the
+ specified path ...
+
+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:
+
+ Failed Test List of failed
+ ------------------------------------
+ op/taint.t 1, 3, 31, 37
+
+Alternatively, you can copy F<cygwin1.dll> into the directory where the
+tests run:
+
+ cp /bin/cygwin1.dll t
+
+or one of the Windows system directories (although, this is B<not>
+recommended).
+
+=head2 /etc/group
+
+Cygwin does not require 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:
+
+ Failed Test List of failed
+ ------------------------------------
+ op/grent.t 1
+
+=head2 Script Portability
+
+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 a very brief guide
+to portability, more information can be found in the Cygwin documentation.
+
+=over 4
+
+=item * Pathnames
+
+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?>, F<nul>) are invalid as base filenames. However, they
+can be used in extensions (e.g., F<hello.aux>). Names may contain all
+printable characters except these:
+
+ : * ? " < > |
+
+File names are case insensitive, but case preserving. A pathname that
+contains a backslash or drive letter is a Win32 pathname (and not subject
+to the translations applied to POSIX style pathnames).
+
+=item * Text/Binary
+
+When a file is opened it is in either text or binary mode. In text mode
+a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default
+mode for an open() is determined by the mode of the mount that underlies
+the file. Perl provides a binmode() function to set binary mode on files
+that otherwise would be treated as text. sysopen() with the C<O_TEXT>
+flag sets text mode on files that otherwise would be treated as binary:
+
+ sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
+
+lseek(), tell() and sysseek() only work with files opened in binary mode.
+
+The text/binary issue is covered at length in the Cygwin documentation.
+
+=item * F<.exe>
+
+The Cygwin stat(), lstat() and readlink() functions make the F<.exe>
+extension transparent by looking for 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<cp>
+in a makefile) the F<.exe> is not transparent. The I<install> included
+with Cygwin automatically appends a F<.exe> when necessary.
+
+=item * chown()
+
+On WinNT chown() can change a file's user and group IDs. On Win9x chown()
+is a no-op, although this is appropriate 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>.
+
+Win9x can not rename() an open file (although WinNT can).
+
+The Cygwin chroot() implementation has holes (it can not restrict file
+access by native Win32 programs).
+
+=back
+
+=head1 INSTALL
+
+This will install Perl, including I<man> pages.
+
+ make install | tee log.make-install
+
+NOTE: If C<STDERR> is redirected `C<make install>' will B<not> prompt
+you to install I<perl> into F</usr/bin>.
+
+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.
+
+Information on installing the Perl documentation in HTML format can be
+found in the F<INSTALL> document.
+
+=head1 MANIFEST
+
+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.
+
+=over 4
+
+=item Documentation
+
+ INSTALL README.cygwin README.win32 MANIFEST
+ Changes Changes5.005 Changes5.004 Changes5.6
+ pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
+ pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
+ pod/perlhist.pod pod/perlmodlib.pod pod/buildtoc.PL pod/perltoc.pod
+
+=item Build, Configure, Make, Install
+
+ 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
+ Configure - help finding hints from uname,
+ shared libperl required for dynamic loading
+ Makefile.SH - linklibperl
+ Porting/patchls - cygwin in port list
+ installman - man pages with :: translated to .
+ installperl - install dll/ld2/perlld, install to pods
+ makedepend.SH - uwinfix
+
+=item Tests
+
+ t/io/tell.t - binmode
+ t/lib/b.t - ignore Cwd from os_extras
+ t/lib/glob-basic.t - Win32 directory list access differs from read mode
+ t/op/magic.t - $^X/symlink WORKAROUND, s/.exe//
+ t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk
+ (cache manager sometimes preserves ctime of file
+ previously created and deleted), no -u (setuid)
+
+=item Compiled Perl Source
+
+ EXTERN.h - __declspec(dllimport)
+ XSUB.h - __declspec(dllexport)
+ cygwin/cygwin.c - os_extras (getcwd, spawn)
+ perl.c - os_extras
+ perl.h - binmode
+ doio.c - win9x can not rename a file when it is open
+ pp_sys.c - do not define h_errno, pp_system with spawn
+ util.c - use setenv
+
+=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/Cwd.pm - hook to internal Cwd::cwd
+ lib/ExtUtils/MakeMaker.pm
+ - require MM_Cygwin.pm
+ lib/ExtUtils/MM_Cygwin.pm
+ - canonpath, cflags, manifypods, perl_archive
+ lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1
+ lib/File/Spec/Unix.pm - preserve //unc
+ lib/File/Temp.pm - no directory sticky bit
+ lib/perl5db.pl - use stdin not /dev/tty
+ utils/perldoc.PL - version comment
+
+=back
+
+=head1 BUGS
+
+When I<make> starts, it warns about overriding commands for F<perlmain.o>.
+
+`C<make clean>' does not remove library F<.def> or F<.exe.stackdump>
+files.
+
+The I<ld2> script contains references to the source directory. You should
+change these to $installbin after `C<make install>'.
+
+Support for swapping real and effective user and group IDs is incomplete.
+On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid().
+However, additional Cygwin calls for manipulating WinNT access tokens
+and security contexts are required.
+
+When building DLLs, `C<dllwrap --export-all-symbols>' is used to export
+global symbols. It might be better to generate an explicit F<.def> file
+(see F<makedef.pl>). Also, DLLs can now be build with `C<gcc -shared>'.
+
+=head1 AUTHORS
+
+Charles Wilson <cwilson@ece.gatech.edu>,
+Eric Fifer <egf7@columbia.edu>,
+alexander smishlajev <als@turnhere.com>,
+Steven Morlock <newspost@morlock.net>,
+Sebastien Barre <Sebastien.Barre@utc.fr>,
+Teun Burgers <burgers@ecn.nl>.
+
+=head1 HISTORY
+
+Last updated: 9 November 2000
projects / dh-make-perl / blobdiff