You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
592 lines
20 KiB
592 lines
20 KiB
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 <[email protected]>,
|
|
Eric Fifer <[email protected]>,
|
|
alexander smishlajev <[email protected]>,
|
|
Steven Morlock <[email protected]>,
|
|
Sebastien Barre <[email protected]>,
|
|
Teun Burgers <[email protected]>.
|
|
|
|
=head1 HISTORY
|
|
|
|
Last updated: 9 November 2000
|