# Copyright (C) 2008-2012, Parrot Foundation.
# This file is best viewed with "perldoc README.cygwin".

=pod

=head1 NAME

README.cygwin - Parrot under Cygwin

=head1 DESCRIPTION

Parrot builds out of the box under Cygwin, when no other parrot is installed.
I<See> PROBLEMS below.

There are official cygwin parrot packages available via
L<http://cygwin.com/setup.exe>.

  parrot libparrot0 libparrot-devel parrot-perl6 parrot-languages

Some tweaks are needed for different names for the ffi to some dll's.
See L</loadlib DLL versioning>.


=head1 Packages

You'll need the following Cygwin packages to run and build Parrot
by your own.

Runtime requirements:

  libreadline6 ncurses libintl8 libgmp3

Optional requirements:

  libicu38 libpq5

  for opengl: w32api opengl or libglut3 xorg-x11-base xorg-x11-bin-dlls

Build requirements:

  gcc make perl parrot readline libncurses-devel libgmp-devel
  pcre-devel

Optional build requirements:

  libicu-devel

  for Cygwin/X opengl: freeglut libglut-devel xorg-x11-devel

Optional perl packages for testing:

  L<Test::TAP::HTMLMatrix> if you want to run the smoke tests
  with C<make smoke>.

  perl L<Test::Perl::Critic> and L<Perl::Critic>

=over 4

=item Cygwin subversion and perl

If you use SVN to get a copy of Parrot, you should use the Cygwin SVN
and not the TortoiseSVN client to avoid build errors.  Similarly you will
need Cygwin Perl rather than ActiveState or Strawberry Perl.

=item icu

Note that ICU is now optional, you can build Parrot without it,
by not installing it or asking Parrot to ignore it (C<--without-icu>).

=item opengl

Building is tricky:

If the freeglut package for the X Server is installed, this
is used, otherwise the w32api and opengl packages for native
Windows opengl support are tried.

In order to use the w32api native GLUT there must be no
F</usr/include/GL> directory.

The problem is that the L<NCI|pdds/draft/pdd16_native_call.pod>
tries the header files to create the imports and not the
libraries, and if the /usr/include/GL headers are found
these are used, despite the w32api GLUT libraries are
defined.

  Determining if your platform supports OpenGL.............yes, freeglut 3.4.
  Determining if your platform supports OpenGL...................yes, GLUT 3.
  Determining if your platform supports OpenGL............................no.

Required packages:

  libglut-devel libGL-devel libGLU-devel libglut3 ...

or if C<libglut-devel> and C<libGL-devel> is not installed:

  w32api opengl

=item SDL

SDL references F<cygSDL-1-2-0.dll>, which is only in cygports
L<http://news.gmane.org/gmane.os.cygwin.ports.announce>

=item aio

libaio-devel "Linux-native asynchronous I/O access" is not available
for cygwin, and as the name says it will never be :)

=back

=head1 BUILD

  perl Configure.pl
  make
  make test
  make install

=head1 PROBLEMS

=over

=item perl fatal error - unable to remap Glob.dll

Something like:
  F<perl.exe>: *** fatal error - unable to remap
  F<C:\cygwin\lib\perl5\5.10\i686-cygwin\auto\File\Glob\Glob.dll>
  to same address as parent(C<0x860000>) != C<0x14D0000>

This is a known cygwin problem with dll's, esp. perl on non-XP 32bit platforms.
You need to install the C<rebase> package and run C<rebaseall> from an C<ash>
shell.

For more information regarding this problem, I<see>
http://www.cygwin.com/ml/cygwin/2009-05/msg00413.html;
http://www.heikkitoivonen.net/blog/2008/11/26/cygwin-upgrades-and-rebaseall/;
I<and see> http://code.google.com/p/chromium/wiki/CygwinDllRemappingFailure.

=item Crash at miniparrot.exe config_lib.pasm

Invoking Parrot to generate runtime/parrot/include/config.fpmc --cross your
fingers

  F<./miniparrot.exe config_lib.pasm > runtime/parrot/include/config.fpmc>
crashes

See below.

=item Spurious stackdumps while building

Be sure that there's no other libparrot.dll.a or libparrot.a
in the linker libpath.

F</usr/lib/libparrot.dll.a>, F</usr/local/lib/libparrot.dll.a>

=item os hardlink test fail

  t/pmc/os....................................
  #   Failed test 'hard link was really created'
  #   at t/pmc/os.t line 312.

This is a known Windows limitation with NTFS junctions on files.

=item Exception: STATUS_ACCESS_VIOLATION ....

If this exception results, ensure there is only one version of the
C<cygwin1.dll> present on your system or, alternatively, ensure no other
application interferes with Cygwin. For more information on this problem,
I<see> the Cygwin/X FAQ at
http://x.cygwin.com/docs/faq/cygwin-x-faq.html#q-status-access-violation
I<and see> the main Cygwin FAQ at
http://cygwin.com/faq-nochunks.html#faq.using.bloda

=item build aborts

If the build aborts, it may be necessary to include already built DLLs in the
rebase. For instructions on how to accomplish this, I<see> the "PROBLEMS"
section at http://cpansearch.perl.org/src/BFREE/OpenGL-0.57/README.cygwin

=back

=head1 TODO

=over

=item loadlib DLL versioning

Use cyg*-1.1.dll naming conventions instead of lib*.so.1.1 names for
loadlib, the FFI.

Thanks to the C<Windows DLL Hell> and the impossibility of
file hardlinks, windows dll names are versioned, so the loadlib
function or the various pir's needs more logic.

Either add the version to each loadlib call, and stem the version from
POSIX versions within get_path(), or add an optional version argument
to loadlib for win32. Or just fix all the pir's, which will be easier
when exceptions work again.

=item Features

Threads, Events, and Signals are missing.

=back

=head1 AUTHORS

=over

=item Reini Urban E<lt>rurban@x-ray.atE<gt>

=back

=head1 SEE ALSO

    L<parrot>

=head1 HISTORY

Last updated: 23 January 2009

=cut
