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
+see. It is written in the POD format (see F<pod/perlpod.pod>) which is
specially designed to be readable as is.
=head1 NAME
-README.cygwin32 - notes about porting Perl to Cygwin32
+perlcygwin - 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 Cygwin32
+B<NOTE:> There are pre-built Perl packages available for Cygwin and a
+version of Perl is provided in the normal Cygwin install. If you do
+not need to customize the configuration, consider using one of those
+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/
-=item libperl.dll
+=head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN
-These instructions and the default cygwin32 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:
+
+L<http://www.cygwin.com/>
+
+A recent net or commercial release of Cygwin is required.
+
+At the time this document was last updated, Cygwin 1.7.16 was current.
+
+
+=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 (WinXP/Win2K/Win7) or your
+Cygwin configuration (binary/text mounts, cvgserver).
+The only dependencies come from hard-coded pathnames like F</usr/local>.
+However, your host system and Cygwin configuration will affect Perl's
+runtime behavior (see L</"TEST">).
-=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...
+=over 4
+
+=item * C<PATH>
+
+Set the C<PATH> environment variable so that Configure finds the Cygwin
+versions of programs. Any not-needed 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.
=back
-=item crypt library
+=head1 CONFIGURE PERL ON CYGWIN
-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/
+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<cygperl5_16.dll>).
-=item hacks that should be revisited after the next cygwin release
+This will run Configure and keep a record:
-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:
+ ./Configure 2>&1 | tee log.configure
-=over
+If you are willing to accept all the defaults run Configure with B<-de>.
+However, several useful customizations are available.
-=item fix for pragma/locale
+=head2 Stripping Perl Binaries on Cygwin
-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.
+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,
-=item fix for lib/io_sock
+ Any additional ld flags (NOT including libraries)? [none] -s
+ Any special flags to pass to g++ to create a dynamically loaded
+ library?
+ [none] -s
+ Any special flags to pass to gcc to use dynamic linking? [none] -s
-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.
+or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
+near the end of the file.
-=item fix for lib/filehand
+=head2 Optional Libraries for Perl on Cygwin
-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.
+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 from
+the Cygwin installer.
-=item fix for environ
+=over 4
-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 * C<-lcrypt>
-=item fix for lib/posix
+The crypt package distributed with Cygwin is a Linux compatible 56-bit
+DES crypt port by Corinna Vinschen.
-the following line was added to t/lib/posix.t to work around a Cygwin bug.
+Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.
-=begin text
+As of libcrypt 1.3 (March 2016), you will need to install the
+libcrypt-devel package for Configure to detect crypt().
-kill 'CONT', $$ if($^O =~ /cygwin/); # XXX: Cygwin bug INT signal gets stuck
+=item * C<-lgdbm_compat> (C<use GDBM_File>)
-=end text
+GDBM is available for Cygwin.
-=back
+NOTE: The GDBM library only works on NTFS partitions.
+
+=item * C<-ldb> (C<use DB_File>)
+
+BerkeleyDB is available for Cygwin.
+
+NOTE: The BerkeleyDB library only completely works on NTFS partitions.
+
+=item * C<cygserver> (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). CURRENTLY NOT SUPPORTED!
+
+=item * C<-lutil>
+
+Included with the standard Cygwin netrelease is the inetutils package
+which includes libutil.a.
=back
-=head2 Configure
+=head2 Configure-time Options for Perl on Cygwin
+
+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>
-Check hints/cygwin32.sh for any system specific settings. In
-particular change libpth to point to the correct location of
-...../i586-cygwin32/lib.
+Undefining this symbol forces Perl to be compiled statically.
-run "sh Configure".
+=item * C<-Dusemymalloc>
-When confronted with this prompt:
+By default Perl does not use the C<malloc()> included with the Perl source,
+because it was slower and not entirely thread-safe. If you want to force
+Perl to build with the old -Dusemymalloc define this.
-=begin text
+=item * C<-Uuseperlio>
- First time through, eh? I have some defaults handy for the
- following systems:
- .
- .
- .
- Which of these apply, if any?
+Undefining this symbol disables the PerlIO abstraction. PerlIO is now the
+default; it is not recommended to disable PerlIO.
-=end text
+=item * C<-Dusemultiplicity>
-select "cygwin32".
+Multiplicity is required when embedding Perl in a C program and using
+more than one interpreter instance. This is only required when you build
+a not-threaded perl with C<-Uuseithreads>.
-Do not use the malloc that comes with perl--using the perl malloc
-collides with some cygwin startup routines.
+=item * C<-Uuse64bitint>
-=head2 make
+By default Perl uses 64 bit integers. If you want to use smaller 32 bit
+integers, define this symbol.
-Run "make". If you're really feeling adventurous, type
-"make 2>&1 | tee make-log.txt".
+=item * C<-Duselongdouble>
-=over
+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 newlib, the Cygwin libc.
-=item ld2
+=item * C<-Uuseithreads>
-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.
+Define this symbol if you want not-threaded faster perl.
-This cannot be done prior to make, because ld2 is created during the
-make process.
+=item * C<-Duselargefiles>
+
+Cygwin uses 64-bit integers for internal size and position calculations,
+this will be correctly detected and defined by Configure.
+
+=item * C<-Dmksymlinks>
+
+Use this to build perl outside of the source tree. Details can be
+found in the F<INSTALL> document. This is the recommended way to
+build perl from sources.
=back
-=head2 make test
+=head2 Suspicious Warnings on Cygwin
+
+You may see some messages during Configure that seem suspicious.
-Run "make test" to see how stable your system is. I (csw) got the
-following errors/warnings:
+=over 4
-=over
+=item * Win9x and C<d_eofnblk>
-=item op/taint
+Win9x does not correctly report C<EOF> with a non-blocking read on a
+closed pipe. You will see the following messages:
-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.
+ But it also returns -1 to signal EOF, so be careful!
+ WARNING: you can't distinguish between EOF and no data!
-=item lib/filehand
+ *** WHOA THERE!!! ***
+ The recommended value for $d_eofnblk on this machine was
+ "define"!
+ Keep the recommended value? [y]
-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.
+At least for consistency with WinNT, you should keep the recommended
+value.
-=item lib/io_sock
+=item * Compiler/Preprocessor defines
-Got an "Application Error - memory could not be read" popup. Again,
-just click OK and ignore it.
+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#>: missing binary operator
+
+This failure does not seem to cause any problems. With older gcc
+versions, "parse error" is reported instead of "missing binary
+operator".
=back
-=head2 perl harness
+=head1 MAKE ON CYGWIN
-Once you've run make test, then cd into the t/ subdirectory and
-execute './perl harness'. I (csw) got the following results:
+Simply run I<make> and wait:
-=over
+ make 2>&1 | tee log.make
-=item op/taint
+=head1 TEST ON CYGWIN
-Got four "missing cygwin1.dll" warning popups. Click OK and
-ignore.
+There are two steps to running the test suite:
-=item lib/filehand
+ make test 2>&1 | tee log.make-test
-Got an "Application Error - memory could not be read" popup. Again,
-click OK and ignore.
+ cd t; ./perl harness 2>&1 | tee ../log.harness
-=item lib/io_sock
+The same tests are run both times, but more information is provided when
+running as C<./perl harness>.
-Got an "Application Error - memory could not be read" popup. Again,
-clock OK and ignore.
+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.
-=item final results
+=head2 File Permissions on Cygwin
-After the ./perl harness, I got the following results summary.
+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 default 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 (listing not updated yet):
- 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.
+ 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)
-=back
+=head2 NDBM_File and ODBM_File do not work on FAT filesystems
-=head2 make install
+Do not use NDBM_File or ODBM_File on FAT filesystem. They can be
+built on a FAT filesystem, but many tests will fail:
-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.
+ ../ext/NDBM_File/ndbm.t 13 3328 71 59 83.10% 1-2 4 16-71
+ ../ext/ODBM_File/odbm.t 255 65280 ?? ?? % ??
+ ../lib/AnyDBM_File.t 2 512 12 2 16.67% 1 4
+ ../lib/Memoize/t/errors.t 0 139 11 5 45.45% 7-11
+ ../lib/Memoize/t/tie_ndbm.t 13 3328 4 4 100.00% 1-4
+ run/fresh_perl.t 97 1 1.03% 91
-=head1 BUGS
+If you intend to run only on FAT (or if using AnyDBM_File on FAT),
+run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
+NDBM_File and ODBM_File being built.
-A lot of warnings about incompatible pointer types and comparison
-lacking a cast. This is because of __declspec(dllimport).
+With NTFS (and no CYGWIN=nontsec), there should be no problems even if
+perl was built on FAT.
-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.
+=head2 C<fork()> failures in io_* tests
-make clean does not remove library .def and .exe.core files.
+A C<fork()> failure may result in the following tests failing:
-ld2 script is installed with reference to source directory. You should
-change this to /usr/local/bin (or whatever) after install.
+ ext/IO/lib/IO/t/io_multihomed.t
+ ext/IO/lib/IO/t/io_sock.t
+ ext/IO/lib/IO/t/io_unix.t
-.bat wrappers for installed utility scripts are not made during installation.
+See comment on fork in L</Miscellaneous> below.
-=head1 AUTHOR
+=head1 Specific features of the Cygwin port
-alexander smishlajev <als@turnhere.com>
+=head2 Script Portability on Cygwin
-=head1 DISCLAIMER
+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.
-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.
+=over 4
-=head1 HISTORY
+=item * Pathnames
-=over
+Cygwin pathnames are separated by forward (F</>) slashes, Universal
+Naming Codes (F<//UNC>) are also supported Since cygwin-1.7 non-POSIX
+pathnames are discouraged. Names may contain all printable
+characters.
-=item Release 1.4.1: 28-May-1999
+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, but
+cygwin will warn you, so better convert them to POSIX.
-Charles Wilson - cwilson@ece.gatech.edu
+For conversion we have C<Cygwin::win_to_posix_path()> and
+C<Cygwin::posix_to_win_path()>.
- Configure minor fix for spaces in $PATH
- documentation updates
+Since cygwin-1.7 pathnames are UTF-8 encoded.
-=item Release 1.4: 26-May-1999
+=item * Text/Binary
-Charles Wilson - cwilson@ece.gatech.edu
+Since cygwin-1.7 textmounts are deprecated and strongly discouraged.
- 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
+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 C<open()> is determined by the mode of the mount that underlies
+the file. See L</Cygwin::is_binmount>(). Perl provides a C<binmode()> function
+to set binary mode on files that otherwise would be treated as text.
+C<sysopen()> with the C<O_TEXT> flag sets text mode on files that otherwise
+would be treated as binary:
-=item Release 1.3: 26-May-1999
+ sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
-Charles Wilson - cwilson@ece.gatech.edu
+C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
+mode.
- 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!!!
+The text/binary issue is covered at length in the Cygwin documentation.
-=item Release 1.2: 25-May-1999
+=item * PerlIO
-Charles Wilson - cwilson@ece.gatech.edu
+PerlIO overrides the default Cygwin Text/Binary behaviour. A file will
+always be treated as binary, regardless of the mode of the mount it lives
+on, just like it is in UNIX. So CR/LF translation needs to be requested in
+either the C<open()> call like this:
- 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!!!
+ open(FH, ">:crlf", "out.txt");
-=item Release 1.1: 21-May-1999
+which will do conversion from LF to CR/LF on the output, or in the
+environment settings (add this to your .bashrc):
-Charles Wilson - cwilson@ece.gatech.edu
+ export PERLIO=crlf
-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
+which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
+on every output generated by perl.
-=item Release 1.0: 16-May-1999
+=item * F<.exe>
-Charles Wilson - cwilson@ece.gatech.edu
+The Cygwin C<stat()>, C<lstat()> and C<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> program
+included with Cygwin automatically appends a F<.exe> when necessary.
-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
+=item * Cygwin vs. Windows process ids
-=item Pre-release 3: 12-May-1999
+Cygwin processes have their own pid, which is different from the
+underlying windows pid. Most posix compliant Proc functions expect
+the cygwin pid, but several Win32::Process functions expect the
+winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not
+the winpid. Use C<Cygwin::pid_to_winpid()> and C<Cygwin::winpid_to_pid()>
+to translate between them.
-Eric Fifer - efifer@sanwaint.com
+=item * Cygwin vs. Windows errors
-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.
+Under Cygwin, $^E is the same as $!. When using L<Win32 API Functions|Win32>,
+use C<Win32::GetLastError()> to get the last Windows error.
-=item Pre-release 2 (initial dynamic build): 17..25-apr-1999
+=item * rebase errors on fork or system
-alexander smishlajev - als@turnher.com
+Using C<fork()> or C<system()> out to another perl after loading multiple dlls
+may result on a DLL baseaddress conflict. The internal cygwin error
+looks like like the following:
-perl 5.005_03. cygwin b20.1 egcs 1.1.2. far 1.60. nescafe classic.
+ 0 [main] perl 8916 child_info_fork::abort: data segment start:
+ parent (0xC1A000) != child(0xA6A000)
-=item Pre-release 1 (static build): 5-Mar-1999
+or:
-Charles Wilson - cwilson@ece.gatech.edu
+ 183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error -
+ unable to remap C:\cygwin\bin\cygsvn_subr-1-0.dll to same address
+ as parent(0x6FB30000) != 0x6FE60000 46 [main] perl 3488 fork: child
+ 3588 - died waiting for dll loading, errno11
-Collected various patches that had been floating around the net, along
-with build instructions. Original authorship credit for those patches
-goes to:
+See L<http://cygwin.com/faq/faq-nochunks.html#faq.using.fixing-fork-failures>
+It helps if not too many DLLs are loaded in memory so the available address space is larger,
+e.g. stopping the MS Internet Explorer might help.
- Steven Morlock - newspost@morlock.net
- Sebastien Barre - Sebastien.Barre@utc.fr
- Teun Burgers - burgers@ecn.nl
+Use the perlrebase or rebase utilities to resolve the conflicting dll addresses.
+The rebase package is included in the Cygwin setup. Use F<setup.exe>
+from L<http://www.cygwin.com/setup.exe> to install it.
-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.
+1. kill all perl processes and run C<perlrebase> or
+
+2. kill all cygwin processes and services, start dash from cmd.exe and run C<rebaseall>.
+
+=item * C<chown()>
+
+On WinNT C<chown()> can change a file's user and group IDs. On Win9x C<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 C<fcntl()> is a stub that
+returns C<ENOSYS>.
+
+Win9x can not C<rename()> an open file (although WinNT can).
+
+The Cygwin C<chroot()> implementation has holes (it can not restrict file
+access by native Win32 programs).
+
+Inplace editing C<perl -i> of files doesn't work without doing a backup
+of the file being edited C<perl -i.bak> because of windowish restrictions,
+therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
+without specifying a backup extension.
=back
-=head1 APPENDIX
+=head2 Prebuilt methods:
+
+=over 4
+
+=item C<Cwd::cwd>
+
+Returns the current working directory.
+
+=item C<Cygwin::pid_to_winpid>
+
+Translates a cygwin pid to the corresponding Windows pid (which may or
+may not be the same).
+
+=item C<Cygwin::winpid_to_pid>
+
+Translates a Windows pid to the corresponding cygwin pid (if any).
+
+=item C<Cygwin::win_to_posix_path>
-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.
+Translates a Windows path to the corresponding cygwin path respecting
+the current mount points. With a second non-null argument returns an
+absolute path. Double-byte characters will not be translated.
-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.
+=item C<Cygwin::posix_to_win_path>
-=over
+Translates a cygwin path to the corresponding cygwin path respecting
+the current mount points. With a second non-null argument returns an
+absolute path. Double-byte characters will not be translated.
-=item text mounts, no 'ntea'
+=item C<Cygwin::mount_table()>
- 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
+Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].
-=item binary mounts, no 'ntea'
+ perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}'
+ /bin c:\cygwin\bin system binmode,cygexec
+ /usr/bin c:\cygwin\bin system binmode
+ /usr/lib c:\cygwin\lib system binmode
+ / c:\cygwin system binmode
+ /cygdrive/c c: system binmode,noumount
+ /cygdrive/d d: system binmode,noumount
+ /cygdrive/e e: system binmode,noumount
- 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
+=item C<Cygwin::mount_flags>
-=item binary mounts, 'ntea'
+Returns the mount type and flags for a specified mount point.
+A comma-separated string of mntent->mnt_type (always
+"system" or "user"), then the mntent->mnt_opts, where
+the first is always "binmode" or "textmode".
- 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
+ system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
+ notexec,managed,nosuid,devfs,proc,noumount
-=item binary mounts, ntea (csw build)
+If the argument is "/cygdrive", then just the volume mount settings,
+and the cygdrive mount prefix are returned.
- Failed Test Status Wstat Total Fail Failed List of failed
- -------------------------------------------------------------------------------
- op/taint.t 149 3 2.01% 1, 3, 31
+User mounts override system mounts.
+
+ $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
+ system,binmode,cygexec
+ $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
+ binmode,cygdrive,/cygdrive
+
+=item C<Cygwin::is_binmount>
+
+Returns true if the given cygwin path is binary mounted, false if the
+path is mounted in textmode.
+
+=item C<Cygwin::sync_winenv>
+
+Cygwin does not initialize all original Win32 environment variables.
+See the bottom of this page L<http://cygwin.com/cygwin-ug-net/setup-env.html>
+for "Restricted Win32 environment".
+
+Certain Win32 programs called from cygwin programs might need some environment
+variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%.
+Call Cygwin::sync_winenv() to copy all Win32 environment variables to your
+process and note that cygwin will warn on every encounter of non-POSIX paths.
=back
-=cut
+=head1 INSTALL PERL ON CYGWIN
+
+This will install Perl, including I<man> pages.
+
+ make install 2>&1 | 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 ON CYGWIN
+
+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
+ pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
+ pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
+ pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
+ pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
+ pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
+ pod/perltoc.pod Porting/Glossary pod/perlgit.pod
+ Porting/checkAUTHORS.pl
+ dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
+ dist/Time-HiRes/Changes
+ ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
+ ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
+ ext/Win32API-File/Changes
+ lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes
+ lib/ExtUtils/NOTES lib/ExtUtils/PATCHING lib/ExtUtils/README
+ lib/Net/Ping/Changes lib/Test/Harness/Changes
+ lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README
+ README.symbian symbian/TODO
+
+=item Build, Configure, Make, Install
+
+ cygwin/Makefile.SHs
+ 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 Cross/Makefile-cross-SH
+ - linklibperl
+ Porting/patchls - cygwin in port list
+ installman - man pages with :: translated to .
+ installperl - install dll, install to 'pods'
+ makedepend.SH - uwinfix
+ regen_lib.pl - file permissions
+
+ NetWare/Makefile
+ plan9/mkfile
+ symbian/sanity.pl symbian/sisify.pl
+ hints/uwin.sh
+ vms/descrip_mms.template
+ win32/Makefile win32/makefile.mk
+
+=item Tests
+
+ t/io/fs.t - no file mode checks if not ntsec
+ skip rename() check when not
+ check_case:relaxed
+ t/io/tell.t - binmode
+ t/lib/cygwin.t - builtin cygwin function tests
+ t/op/groups.t - basegroup has ID = 0
+ 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)
+ t/op/taint.t - can't use empty path under Cygwin Perl
+ t/op/time.t - no tzset()
+
+=item Compiled Perl Source
+
+ EXTERN.h - __declspec(dllimport)
+ XSUB.h - __declspec(dllexport)
+ cygwin/cygwin.c - os_extras (getcwd, spawn, and several
+ Cygwin:: functions)
+ perl.c - os_extras, -i.bak
+ perl.h - binmode
+ doio.c - win9x can not rename a file when it is open
+ pp_sys.c - do not define h_errno, init
+ _pwent_struct.pw_comment
+ util.c - use setenv
+ util.h - PERL_FILE_IS_ABSOLUTE macro
+ pp.c - Comment about Posix vs IEEE math under
+ Cygwin
+ perlio.c - CR/LF mode
+ perliol.c - Comment about EXTCONST under Cygwin
+
+=item Compiled Module Source
+
+ ext/Compress-Raw-Zlib/Makefile.PL
+ - Can't install via CPAN shell under Cygwin
+ ext/Compress-Raw-Zlib/zlib-src/zutil.h
+ - Cygwin is Unix-like and has vsnprintf
+ ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under
+ Cygwin
+ 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
+ ext/Sys/Syslog/Syslog.xs
+ - Cygwin has syslog.h
+ ext/Sys/Syslog/win32/compile.pl
+ - Convert paths to Windows paths
+ ext/Time-HiRes/HiRes.xs
+ - Various timers not available
+ ext/Time-HiRes/Makefile.PL
+ - Find w32api/windows.h
+ ext/Win32/Makefile.PL - Use various libraries under Cygwin
+ ext/Win32/Win32.xs - Child dir and child env under Cygwin
+ ext/Win32API-File/File.xs
+ - _open_osfhandle not implemented under
+ Cygwin
+ ext/Win32CORE/Win32CORE.c
+ - __declspec(dllexport)
+
+=item Perl Modules/Scripts
+
+ ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under
+ Cygwin
+ ext/Digest-SHA/bin/shasum
+ - Use binary mode under Cygwin
+ ext/Sys/Syslog/win32/Win32.pm
+ - Convert paths to Windows paths
+ ext/Time-HiRes/HiRes.pm
+ - Comment about various timers not available
+ ext/Win32API-File/File.pm
+ - _open_osfhandle not implemented under
+ Cygwin
+ ext/Win32CORE/Win32CORE.pm
+ - History of Win32CORE under Cygwin
+ lib/Cwd.pm - hook to internal Cwd::cwd
+ lib/ExtUtils/CBuilder/Platform/cygwin.pm
+ - use gcc for ld, and link to libperl.dll.a
+ lib/ExtUtils/CBuilder.pm
+ - Cygwin is Unix-like
+ lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
+ lib/ExtUtils/MM.pm - OS classifications
+ lib/ExtUtils/MM_Any.pm - Example for Cygwin
+ lib/ExtUtils/MakeMaker.pm
+ - require MM_Cygwin.pm
+ lib/ExtUtils/MM_Cygwin.pm
+ - canonpath, cflags, manifypods, perl_archive
+ lib/File/Fetch.pm - Comment about quotes using a Cygwin example
+ lib/File/Find.pm - on remote drives stat() always sets
+ st_nlink to 1
+ lib/File/Spec/Cygwin.pm - case_tolerant
+ lib/File/Spec/Unix.pm - preserve //unc
+ lib/File/Spec/Win32.pm - References a message on cygwin.com
+ lib/File/Spec.pm - Pulls in lib/File/Spec/Cygwin.pm
+ lib/File/Temp.pm - no directory sticky bit
+ lib/Module/CoreList.pm - List of all module files and versions
+ lib/Net/Domain.pm - No domainname command under Cygwin
+ lib/Net/Netrc.pm - Bypass using stat() under Cygwin
+ lib/Net/Ping.pm - ECONREFUSED is EAGAIN under Cygwin
+ lib/Pod/Find.pm - Set 'pods' dir
+ lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
+ lib/Pod/Perldoc.pm - Use 'less' pager, and use .exe extension
+ lib/Term/ANSIColor.pm - Cygwin terminal info
+ lib/perl5db.pl - use stdin not /dev/tty
+ utils/perlbug.PL - Add CYGWIN environment variable to report
+
+=item Perl Module Tests
+
+ dist/Cwd/t/cwd.t
+ ext/Compress-Zlib/t/14gzopen.t
+ ext/DB_File/t/db-btree.t
+ ext/DB_File/t/db-hash.t
+ ext/DB_File/t/db-recno.t
+ ext/DynaLoader/t/DynaLoader.t
+ ext/File-Glob/t/basic.t
+ ext/GDBM_File/t/gdbm.t
+ ext/POSIX/t/sysconf.t
+ ext/POSIX/t/time.t
+ ext/SDBM_File/t/sdbm.t
+ ext/Sys/Syslog/t/syslog.t
+ ext/Time-HiRes/t/HiRes.t
+ ext/Win32/t/Unicode.t
+ ext/Win32API-File/t/file.t
+ ext/Win32CORE/t/win32core.t
+ lib/AnyDBM_File.t
+ lib/Archive/Extract/t/01_Archive-Extract.t
+ lib/Archive/Tar/t/02_methods.t
+ lib/ExtUtils/t/Embed.t
+ lib/ExtUtils/t/eu_command.t
+ lib/ExtUtils/t/MM_Cygwin.t
+ lib/ExtUtils/t/MM_Unix.t
+ lib/File/Compare.t
+ lib/File/Copy.t
+ lib/File/Find/t/find.t
+ lib/File/Path.t
+ lib/File/Spec/t/crossplatform.t
+ lib/File/Spec/t/Spec.t
+ lib/Net/hostent.t
+ lib/Net/Ping/t/110_icmp_inst.t
+ lib/Net/Ping/t/500_ping_icmp.t
+ lib/Net/t/netrc.t
+ lib/Pod/Simple/t/perlcyg.pod
+ lib/Pod/Simple/t/perlcygo.txt
+ lib/Pod/Simple/t/perlfaq.pod
+ lib/Pod/Simple/t/perlfaqo.txt
+ lib/User/grent.t
+ lib/User/pwent.t
+
+=back
+
+=head1 BUGS ON CYGWIN
+
+Support for swapping real and effective user and group IDs is incomplete.
+On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
+However, additional Cygwin calls for manipulating WinNT access tokens
+and security contexts are required.
+
+=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>,
+Gerrit P. Haase <gp@familiehaase.de>,
+Reini Urban <rurban@cpan.org>,
+Jan Dubois <jand@activestate.com>,
+Jerry D. Hedden <jdhedden@cpan.org>.
+
+=head1 HISTORY
+
+Last updated: 2012-02-08
https://perl5.git.perl.org / perl5.git / blobdiff