A recent net or commercial release of Cygwin is required.
-At the time this document was last updated, Cygwin 1.3.12 was current.
+At the time this document was last updated, Cygwin 1.5.2 was current.
=head2 Cygwin Configuration
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.
+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
GDBM is available for Cygwin.
+NOTE: The GDBM library only works 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>.
+BerkeleyDB is available for Cygwin.
NOTE: The BerkeleyDB library only completely works on NTFS partitions.
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). NO LONGER SUPPORTED!
+CPAN modules). CURRENTLY NOT SUPPORTED!
=item * C<-lutil>
=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.
+By default Perl uses the C<malloc()> included with the Perl source. If you
+want to force Perl to build with the system C<malloc()> undefine this symbol.
=item * C<-Uuseperlio>
-Undefining this symbol disables the PerlIO abstraction, which is now the
-default.
+Undefining this symbol disables the PerlIO abstraction. PerlIO is now the
+default; it is not recommended to disable PerlIO.
=item * C<-Dusemultiplicity>
=item * C<-Duse64bitint>
By default Perl uses 32 bit integers. If you want to use larger 64
-bit integers, define this symbol. If there is trouble, check that
-your Cygwin installation is up to date.
+bit integers, define this symbol.
=item * C<-Duselongdouble>
=item * C<-Dusethreads>
-POSIX threads are B<not> yet implemented in Cygwin completely.
+POSIX threads are implemented in Cygwin, define this symbol if you want
+a threaded perl.
=item * C<-Duselargefiles>
-Although Win32 supports large files, Cygwin currently uses 32-bit integers
-for internal size and position calculations.
+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. This works with Cygwin.
-Details can be found in the F<INSTALL> document.
+Details can be found in the F<INSTALL> document. This is the recommended
+way to build perl from sources.
=back
=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).
+when C<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 ...
+ Checking whether your C<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.
make 2>&1 | tee log.make
-=head2 Warnings on Cygwin
+=head2 Errors on Cygwin
-Warnings like these are normal:
+Errors like these are normal:
- perl.c: In function `S_parse_body':
- perl.c:1468: warning: implicit declaration of function `init_os_extras'
- ...
- pp_sys.c:289: warning: `S_emulate_eaccess' defined but not used
- ...
- perlio.c: In function `perlsio_binmode':
- perlio.c:98: warning: implicit declaration of function `setmode'
- perlio.c:98: warning: passing arg 1 of `Perl_PerlIO_fileno' from incompatible pointer type
...
make: [extra.pods] Error 1 (ignored)
...
=head2 ld2 on Cygwin
-During `C<make>', I<ld2> will be created and installed in your $installbin
+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
+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,
+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>.
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>'.
+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
With NTFS (and CYGWIN=ntsec), there should be no problems even if
perl was built on FAT.
-=head2 fork() failures in io_* tests
+=head2 C<fork()> failures in io_* tests
-A fork() failure may result in the following tests failing:
+A C<fork()> failure may result in the following tests failing:
ext/IO/lib/IO/t/io_multihomed.t
ext/IO/lib/IO/t/io_sock.t
See comment on fork in L<Miscellaneous> below.
+=head1 Specific features of the Cygwin port
+
=head2 Script Portability on Cygwin
Cygwin does an outstanding job of providing UNIX-like semantics on top of
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>
+mode for an C<open()> is determined by the mode of the mount that underlies
+the file. 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:
sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)
-lseek(), tell() and sysseek() only work with files opened in binary mode.
+C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
+mode.
The text/binary issue is covered at length in the Cygwin documentation.
+=item * PerlIO
+
+PerlIO overrides the default Cygwin Text/Binary behaviour. A file will
+always treated as binary, regardless which 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:
+
+ open(FH, ">:crlf", "out.txt");
+
+which will do conversion from LF to CR/LF on the output, or in the
+environment settings (add this to your .bashrc):
+
+ export PERLIO=crlf
+
+which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
+on every output generated by perl.
+
=item * F<.exe>
-The Cygwin stat(), lstat() and readlink() functions make the F<.exe>
+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.
in a makefile) the F<.exe> is not transparent. The I<install> included
with Cygwin automatically appends a F<.exe> when necessary.
-=item * chown()
+=item * cygwin vs. windows process ids
+
+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::winpid_to_pid()> and C<Cygwin::winpid_to_pid()>
+to translate between them.
+
+=item * C<chown()>
-On WinNT chown() can change a file's user and group IDs. On Win9x 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 fcntl() is a stub that
+File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
returns C<ENOSYS>.
-Win9x can not rename() an open file (although WinNT can).
+Win9x can not C<rename()> an open file (although WinNT can).
-The Cygwin chroot() implementation has holes (it can not restrict file
+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,
-so Perl adds the C<.bak> automatically if you just use C<perl -i>.
+therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
+without specifying a backup extension.
-Using fork() after loading multiple dlls may fail with an internal cygwin
+Using C<fork()> after loading multiple dlls may fail with an internal cygwin
error like the following:
C:\CYGWIN\BIN\PERL.EXE: *** couldn't allocate memory 0x10000(4128768) for 'C:\CYGWIN\LIB\PERL5\5.6.1\CYGWIN-MULTI\AUTO\SOCKET\SOCKET.DLL' alignment, Win32 error 8
200 [main] perl 377147 sync_with_child: child -395691(0xB8) died before initialization with status code 0x1
1370 [main] perl 377147 sync_with_child: *** child state child loading dlls
-Use the rebase utility to resolve the conflicting dll addresses.
-See: http://www.tishler.net/jason/software/rebase/
-and http://sources.redhat.com/ml/cygwin/2002-07/msg00276.html
+Use the rebase utility to resolve the conflicting dll addresses. The
+rebase package is included in the Cygwin netrelease. Use setup.exe from
+F<http://www.cygwin.com/setup.exe> to install it and run rebaseall.
+
+=back
+
+=head2 Prebuilt methods:
+
+=over 4
+
+=item C<Cwd::cwd>
+
+Returns 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).
=back
make install 2>&1 | tee log.make-install
-NOTE: If C<STDERR> is redirected `C<make install>' will B<not> prompt
+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
+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
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
+ pod/perlhist.pod pod/perlmodlib.pod perl/buildtoc pod/perltoc.pod
=item Build, Configure, Make, Install
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/lib/cygwin.t - builtin cygwin function tests
=item Compiled Perl Source
EXTERN.h - __declspec(dllimport)
XSUB.h - __declspec(dllexport)
- cygwin/cygwin.c - os_extras (getcwd, spawn)
+ cygwin/cygwin.c - os_extras (getcwd, spawn, Cygwin::winpid_to_pid,
+ Cygwin::pid_to_winpid)
perl.c - os_extras
perl.h - binmode
doio.c - win9x can not rename a file when it is open
=head1 BUGS ON CYGWIN
Support for swapping real and effective user and group IDs is incomplete.
-On WinNT Cygwin provides setuid(), seteuid(), setgid() and setegid().
+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.
Steven Morlock <newspost@morlock.net>,
Sebastien Barre <Sebastien.Barre@utc.fr>,
Teun Burgers <burgers@ecn.nl>,
-Gerrit Haase <gh@familiehaase.de>.
+Gerrit P. Haase <gp@familiehaase.de>.
=head1 HISTORY
-Last updated: 2002-10-07
+Last updated: 2005-02-11
https://perl5.git.perl.org / perl5.git / blobdiff