EBCDIC %HTML_Escapes for Pod::Text, plus sync patch.

[perl5.git] / README.cygwin32

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.cygwin32 - notes about porting Perl to Cygwin32

=head1 SYNOPSIS

=over

=item Cygwin32

   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 it's home page
http://sourceware.cygnus.com/cygwin/

=item libperl.dll

These instructions and the default cygwin32 hints build a a shared
libperl.dll Perl library and enables dynamically loaded extensions.


=back

=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 embedding as comments in the .sh file.

=item crypt library

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/

=back

=head2 Configure

Check hints/cygwin32.sh for any system specific settings.  In
particular change libpth if Cygwin is installed somewhere other
than /cygnus.

run "sh Configure".  

When confronted with this prompt:

=begin text

	First time through, eh?  I have some defaults handy for the
	following systems:
	   .
	   .
	   .
	Which of these apply, if any?

=end text

select "cygwin32".

Do not use the malloc that comes with perl--using the perl malloc
collides with some cygwin startup routines. 

=head2 make

Run "make".  After that, run "make test" to see how stable your system is.
For me, at io/taint.t you may see several Win32 "Unable To Locate DLL"
messages (just click Ok) that requires cygwin1.dll to be present in the
build directory or somewhere in system path (/WINNT, /WINNT/System,
/WINNT/System32).  And, at lib/io_sock.t you may see several Win32
"Application Error" messages (just click Ok) and the test waits for a
died child that has to be killed manually.  Other test scripts seem to
be more or less harmless.  The result of ./perl harness reads:

=begin text

Failed Test  Status Wstat Total Fail  Failed  List of failed
-------------------------------------------------------------------------------
lib/anydbm.t      2   512    12    8  66.67%  5-12
lib/findbin.t                 1    1 100.00%  1
lib/io_sock.t     9  2304     5    4  80.00%  2-5
lib/sdbm.t        2   512    18   15  83.33%  2, 5-18
op/magic.t                   35    2   5.71%  23, 29
op/split.t                   25    1   4.00%  11
op/stat.t                    58    2   3.45%  9, 26
op/taint.t                  149    3   2.01%  1, 3, 31
pragma/locale.t  11  2816   102    4   3.92%  99-102
9 tests skipped, plus 35 subtests skipped.
Failed 9/190 test scripts, 95.26% okay. 40/6452 subtests failed, 99.38% okay.

=end text

=head1 BUGS

A lot of warnings about incompatible pointer types and comparison
lacking a cast.  This is because of __declspec(dllimport).

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.  I saw no better solution than adding an explicit
define to the rule.

The lib/io_sock.t failure seems to be a problem with a forked child
not having its DLLs remapped.

make clean does not remove library .def and .exe.core files.

ld2 script is installed with reference to source directory.  You should
change this to /usr/local/bin (or whatever) after install.

.bat wrappers for installed utility scripts are not made during installation.

=head1 AUTHOR

alexander smishlajev <als@turnhere.com>

=head1 DISCLAIMER

I 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.

=head1 HISTORY

17..25-apr-1999.  perl 5.005_03.  cygwin b20.1  egcs 1.1.2.
                  far 1.60.  nescafe classic.

efifer@sanwaint.com - Wed May 12 17:22:42 BST 1999

    Removed all references to the impure_ptr hack since it is no longer
    needed.  Some minor cleanup of Alexander's work and a few bug fixes.

=cut