README_win32.pod

   1 # $Id$
   2
   3 This file is best viewed with "perldoc README_win32".
   4
   5 =head1 NAME
   6
   7 README.win32 - Parrot under Windows
   8
   9 =head1 SYNOPSIS
  10
  11 These are instructions for building the "native" port of Parrot under
  12 Windows 2000/XP on the Intel x86 architecture.
  13
  14 =head1 DESCRIPTION
  15
  16 Win32 "native" ports require no additional software to run but the
  17 operating system.  There should be other READMEs for (emulation)
  18 systems that run on Win32, eg Cygwin.
  19
  20 Native compilers include:
  21
  22        Borland C++ (bcc)                version xxx or later
  23        Microsoft Visual C++ (cl)        version 13.10.3077 or later
  24        MinGW32 with GCC (gcc)           version 3.4.2 or later
  25        Intel C++ (icl)                  version 8.0.48 works
  26
  27 =head2 Setting Up Parrot
  28
  29 =over
  30
  31 =item Make
  32
  33 You need "nmake" to build Parrot under Windows with Microsoft compilers.  It
  34 should be available via Microsoft Visual Studio .NET 2003 or the Microsoft .NET
  35 Framework SDK 1.1.  Download the latter from the Microsoft .NET Framework
  36 Homepage L<http://msdn.microsoft.com/netframework/>.
  37
  38 Note: Parrot will not build using nmake v1.5 from the MS web site.  Download
  39 one of the above toolkits to obtain a later version, either v7 or v8.
  40
  41 MinGW works with its GNU "make" (v 3.81) port and its name is
  42 'mingw32-make.exe'.  If you also have the Minimal SYStem (MSYS) installed,
  43 you will need to remove the Msys/bin folder from your PATH environment
  44 variable before calling "perl Configure.pl" and mingw32-make.  Perl detects
  45 and calls /bin/sh.exe, if found, whenever shelling a new process.  sh.exe
  46 causes problems for mingw32-make.exe because of its inability to handle
  47 Windows pathnames with backslashes.  You must run "perl Configure.pl" and
  48 mingw32-make from a dosbox; running those commands from an MSYS shell window
  49 will experience the same backslash path problems.
  50
  51 =item Command Shell
  52
  53 The surest way to build it is on Windows NT/2000/XP, using the cmd shell.
  54
  55 =item ICU
  56
  57 Parrot no longer comes with its own ICU, thus you need to install it on your
  58 system if you want to use it.  Note that ICU is now optional, you can
  59 build Parrot without it, by not installing it or asking Parrot to
  60 ignore it (C<--without-icu>).
  61
  62 If you want to use ICU, download it from
  63 L<http://site.icu-project.org/download>.
  64
  65 If you want to use precompiled binaries, do the following.
  66 Download the package matching your compiler, unpack it (say, into
  67 C:\usr\lib), add the F<bin> directory to C<PATH>, and tell
  68 Configure.pl to use it.
  69
  70     mkdir C:\usr\lib
  71     unzip icu4c-4_2_1-Win32-msvc9.zip -d C:\usr\lib
  72     mkdir C:\usr\lib\data
  73     set PATH=%PATH%;C:\usr\lib\icu\bin
  74     cd <parrot directory>
  75     perl Configure.pl
  76         --icushared="C:\usr\lib\icu\lib\icudt.lib C:\usr\lib\icu\lib\icuuc.lib"
  77         --icuheaders="C:\usr\lib\icu\include"
  78
  79 Note the step of creating the F<C:\usr\lib\data> directory, as Parrot
  80 really wants it and the binary packages don't contain it.  It doesn't
  81 need to contain anything though, as the data is pulled in from
  82 F<lib/icudt.lib>, which contains the standard data in binary form.
  83
  84 =item Optional libraries
  85
  86 The availability of these libraries is checked by Configure.pl.
  87
  88 B<libcrypto> - a part of libssl / OpenSSL
  89 L<http://gnuwin32.sourceforge.net/>
  90
  91 B<gettext> - library and tools for native language support
  92 L<http://gnuwin32.sourceforge.net/>
  93
  94 B<gdbm> - GNU database manager
  95 L<http://gnuwin32.sourceforge.net/>
  96
  97 B<GMP> - GNU multiple precision arithmetic library
  98 L<http://developer.berlios.de/projects/win32gmp/>
  99
 100 B<OpenGL> / B<GLUT> - Open Graphics Library
 101 L<http://www.xmission.com/~nate/glut.html> or
 102 L<http://www.transmissionzero.co.uk/computing/using-glut-with-mingw/>
 103
 104 B<pcre> - Perl-Compatible Regular Expression library
 105 L<http://gnuwin32.sourceforge.net/>
 106
 107 B<readline> - edit command lines
 108 L<http://gnuwin32.sourceforge.net/>
 109
 110 =item Optional utilities
 111
 112 The availability of these utilities is checked by Configure.pl
 113 or by some test.
 114
 115 B<antlr> - ANother Tool for Language Recognition
 116 L<http://www.antlr.org/>
 117
 118 B<ctags> - Exuberant Ctags
 119 L<http://ctags.sourceforge.net/>
 120
 121 =item Inno Setup
 122
 123 Inno Setup is a I<free> installer for Windows programs.
 124
 125 The latest release of Inno Setup at the time of writing is 5.3.7.
 126
 127 The HomePage is on L<http://www.jrsoftware.org/>.
 128
 129 Add the directory to PATH.
 130
 131     set PATH=%PATH%;C:\Program Files\Inno Setup 5
 132
 133 =item Borland C++
 134
 135 XXX
 136
 137 =item Microsoft Visual C++
 138
 139 Since mid April 2004, Visual C++ comes in two flavors.  Microsoft
 140 Visual Studio .NET 2003 (L<http://msdn.microsoft.com/visualc/>), which
 141 includes the full blown IDE, and Microsoft Visual C++ Toolkit 2003
 142 (L<http://msdn.microsoft.com/visualc/vctoolkit2003/>), which is a free
 143 (but unsupported) package, containing only the basic compiler and
 144 linker stuff.
 145
 146 If you use the Toolkit, be sure to follow the directions for setting up
 147 your build environment that come with the perl distributions. (README.win32
 148 in the latest perl distribution.) You may have to substitute "Microsoft
 149 Platform SDK" wherever "Microsoft SDK" is listed, depending on the your
 150 install. You can ignore the entries regarding "win32/config.vc", but be sure
 151 to create the "link.bat" batch file. Copy the missing files mentioned,
 152 run the Toolkit Command Prompt, set the appropriate env vars, and you
 153 should be fine. (For env vars, you can update them under My Computer->
 154 properties so they are available whenever you open a shell.)
 155
 156 Note: It is possible to use ActiveState Perl with the Toolkit: you don't
 157 have to compile your own perl.
 158
 159 =item Strawberry Perl
 160
 161 With the Strawberry perl distro from
 162 L<http://strawberryperl.com/>, gcc is included. To build parrot,
 163 use the strawberry perl binary to run Configure.pl, and then
 164 follow the directions.
 165
 166 =item MinGW32 with GCC
 167
 168 The latest release of MinGW package at the time of writing is 5.1.6,
 169 which contains gcc-3.4.5 as current release.
 170 It can be downloaded here:
 171 L<http://sourceforge.net/projects/mingw/files/>
 172
 173 The HomePage is on L<http://www.mingw.org/>.
 174
 175 With the ActiveState Perl distribution, tell Configure.pl to use gcc :
 176
 177     perl Configure.pl
 178          --cc=gcc
 179          --icushared="C:\usr\lib\icu\lib\icudt.lib C:\usr\lib\icu\lib\icuuc.lib"
 180          --icuheaders="C:\usr\lib\icu\include"
 181 or
 182     perl Configure.pl --cc=gcc --without-icu
 183
 184 =item Intel C++
 185
 186 XXX
 187
 188 =back
 189
 190 =head2 Building
 191
 192     $MAKE
 193
 194 =head2 Testing
 195
 196     $MAKE test
 197
 198 =head2 Installation
 199
 200     $MAKE install
 201
 202 =head2 Installer
 203
 204     $MAKE win32-inno-installer
 205
 206 This command creates a setup-parrot-x.y.z.exe that contains all parrot install
 207 directories.
 208
 209 =head2 Usage Hints
 210
 211     XXX
 212
 213 =head1 BUGS AND CAVEATS
 214
 215 =over
 216
 217 =item Features
 218
 219 Threads, Events, and Signals are missing.
 220
 221 =back
 222
 223 =head1 ACKNOWLEDGEMENTS
 224
 225 XXX
 226
 227 =head1 AUTHORS
 228
 229 =over
 230
 231 =item Ron Blaschke E<lt>ron@rblasch.orgE<gt>
 232
 233 =item François Perrad  E<lt>francois.perrad@gadz.orgE<gt>
 234
 235 =back
 236
 237 This document is maintained by The Parrot Developers
 238 (E<lt>parrot-dev@lists.parrot.orgE<gt>).
 239
 240 =head1 SEE ALSO
 241
 242     L<parrot>
 243
 244 =head1 HISTORY
 245
 246 This document borrows heavily from Perl's README.win32.
 247
 248 GCC/mingw32 support was added in 0.1.2 (François Perrad).
 249
 250 Last updated: 20 Jan 2009
 251
 252 =cut