README_cygwin.pod

   1 This file is best viewed with "perldoc README.cygwin".
   2
   3 =head1 NAME
   4
   5 README.cygwin - Parrot under Cygwin
   6
   7 =head1 SYNOPSIS
   8
   9 Parrot builds out of the box under Cygwin,
  10 when no other parrot is installed. See below at PROBLEMS.
  11
  12 There are official cygwin parrot packages available via
  13 L<http://cygwin.com/setup.exe>.
  14
  15   parrot libparrot0 libparrot-devel parrot-perl6 parrot-languages
  16
  17 Some tweaks are needed for different names for the ffi to some dll's.
  18 See L</loadlib DLL versioning>.
  19
  20
  21 =head1 Packages
  22
  23 You'll need the following Cygwin packages to run and build Parrot
  24 by your own.
  25
  26 Runtime requirements:
  27
  28   libreadline6 ncurses libintl8 libgmp3 libgdbm4
  29
  30 Optional requirements:
  31
  32   libicu38 libpq5 openssl
  33
  34   for opengl: w32api opengl or libglut3 xorg-x11-base xorg-x11-bin-dlls
  35
  36 Build requirements:
  37
  38   gcc make perl parrot readline libncurses-devel libgmp-devel
  39   libgdbm-devel pcre-devel
  40
  41 Optional build requirements:
  42
  43   libicu-devel openssl-devel
  44
  45   for Cygwin/X opengl: freeglut libglut-devel xorg-x11-devel
  46
  47 Optional perl packages for testing:
  48
  49   L<Test::TAP::HTMLMatrix> if you want to run the smoke tests
  50   with C<make smoke>.
  51
  52   perl L<Test::Perl::Critic> and L<Perl::Critic>
  53
  54 =over 4
  55
  56 =item Cygwin subversion and perl
  57
  58 If you use SVN to get a copy of Parrot, you should use the Cygwin SVN
  59 and not the TortoiseSVN client to avoid build errors.  Similarly you will
  60 need Cygwin Perl rather than ActiveState or Strawberry Perl.
  61
  62 =item icu
  63
  64 Note that ICU is now optional, you can build Parrot without it,
  65 by not installing it or asking Parrot to ignore it (C<--without-icu>).
  66
  67 =item opengl
  68
  69 Building is tricky:
  70
  71 If the freeglut package for the X Server is installed, this
  72 is used, otherwise the w32api and opengl packages for native
  73 Windows opengl support are tried.
  74
  75 In order to use the w32api native GLUT there must be no
  76 F</usr/include/GL> directory.
  77
  78 The problem is that the L<NCI|pdds/draft/pdd16_native_call.pod>
  79 tries the header files to create the imports and not the
  80 libraries, and if the /usr/include/GL headers are found
  81 these are used, despite the w32api GLUT libraries are
  82 defined.
  83
  84   Determining if your platform supports OpenGL.............yes, freeglut 3.4.
  85   Determining if your platform supports OpenGL...................yes, GLUT 3.
  86   Determining if your platform supports OpenGL............................no.
  87
  88 Required packages:
  89
  90   libglut-devel libGL-devel libGLU-devel libglut3 ...
  91
  92 or if C<libglut-devel> and C<libGL-devel> is not installed:
  93
  94   w32api opengl
  95
  96 =item SDL
  97
  98 SDL references F<cygSDL-1-2-0.dll>, which is only in cygports
  99 L<http://news.gmane.org/gmane.os.cygwin.ports.announce>
 100
 101 =item aio
 102
 103 libaio-devel "Linux-native asynchronous I/O access" is not available
 104 for cygwin, and as the name says it will never be :)
 105
 106 =back
 107
 108 =head1 BUILD
 109
 110   perl Configure.pl
 111   make
 112   make test
 113   make install
 114
 115 =head1 PROBLEMS
 116
 117 =over
 118
 119 =item perl fatal error - unable to remap Glob.dll
 120
 121 Something like:
 122   F<perl.exe>: *** fatal error - unable to remap
 123   F<C:\cygwin\lib\perl5\5.10\i686-cygwin\auto\File\Glob\Glob.dll>
 124   to same address as parent(C<0x860000>) != C<0x14D0000>
 125
 126 This is a known cygwin problem with dll's, esp. perl on non-XP 32bit platforms.
 127 You need to install the C<rebase> package and run C<rebaseall> from an C<ash>
 128 shell.
 129
 130 =item Crash at miniparrot.exe config_lib.pasm
 131
 132 Invoking Parrot to generate runtime/parrot/include/config.fpmc --cross your
 133 fingers
 134
 135   F<./miniparrot.exe config_lib.pasm > runtime/parrot/include/config.fpmc>
 136 crashes
 137
 138 See below.
 139
 140 =item Spurious stackdumps while building
 141
 142 Building with an already installed library fails. See RT#39742
 143
 144 Be sure that there's no other libparrot.dll.a or libparrot.a
 145 in the linker libpath.
 146
 147 F</usr/lib/libparrot.dll.a>, F</usr/local/lib/libparrot.dll.a>
 148
 149 =item os hardlink test fail
 150
 151   t/pmc/os....................................
 152   #   Failed test 'hard link was really created'
 153   #   at t/pmc/os.t line 312.
 154
 155 This is a known Windows limitation with NTFS junctions on files.
 156
 157 =back
 158
 159 =head1 TODO
 160
 161 =over
 162
 163 =item loadlib DLL versioning
 164
 165 Use cyg*-1.1.dll naming conventions instead of lib*.so.1.1 names for
 166 loadlib, the FFI.
 167
 168 Thanks to the C<Windows DLL Hell> and the impossibility of
 169 file hardlinks, windows dll names are versioned, so the loadlib
 170 function or the various pir's needs more logic.
 171
 172 Either add the version to each loadlib call, and stem the version from
 173 POSIX versions within get_path(), or add an optional version argument
 174 to loadlib for win32. Or just fix all the pir's, which will be easier
 175 when exceptions work again.
 176
 177 =item Features
 178
 179 Threads, Events, and Signals are missing.
 180
 181 =back
 182
 183 =head1 AUTHORS
 184
 185 =over
 186
 187 =item Reini Urban E<lt>rurban@x-ray.atE<gt>
 188
 189 =back
 190
 191 =head1 SEE ALSO
 192
 193     L<parrot>
 194
 195 =head1 HISTORY
 196
 197 Last updated: 23 January 2009
 198
 199 =cut