perlcyg.pod

source of perl for linux application,

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 <[e-mail]>,
Eric Fifer <[e-mail]>,
alexander smishlajev <[e-mail]>,
Steven Morlock <[e-mail]>,
Sebastien Barre <[e-mail]>,
Teun Burgers <[e-mail]>.

=head1 HISTORY

Last updated: 9 November 2000