[Summary view] [Print] [Text view]

   1  If you read this file _as_is_, just ignore the funny characters you
   2  see. It is written in the POD format (see perlpod manpage) which is
   3  specially designed to be readable as is.
   4  
   5  =head1 NAME
   6  
   7  perldos - Perl under DOS, W31, W95.
   8  
   9  =head1 SYNOPSIS
  10  
  11  These are instructions for building Perl under DOS (or w??), using
  12  DJGPP v2.03 or later.  Under w95 long filenames are supported.
  13  
  14  =head1 DESCRIPTION
  15  
  16  Before you start, you should glance through the README file
  17  found in the top-level directory where the Perl distribution
  18  was extracted.  Make sure you read and understand the terms under
  19  which this software is being distributed.
  20  
  21  This port currently supports MakeMaker (the set of modules that
  22  is used to build extensions to perl).  Therefore, you should be
  23  able to build and install most extensions found in the CPAN sites.
  24  
  25  Detailed instructions on how to build and install perl extension
  26  modules, including XS-type modules, is included.  See 'BUILDING AND
  27  INSTALLING MODULES'.
  28  
  29  =head2 Prerequisites for Compiling Perl on DOS
  30  
  31  =over 4
  32  
  33  =item DJGPP
  34  
  35  DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit,
  36  protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible
  37  operating systems, by DJ Delorie <dj@delorie.com> and friends.
  38  
  39  For more details (FAQ), check out the home of DJGPP at:
  40  
  41          http://www.delorie.com/djgpp/
  42  
  43  If you have questions about DJGPP, try posting to the DJGPP newsgroup:
  44  comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com.
  45  
  46  You can find the full DJGPP distribution on any of the mirrors listed here:
  47  
  48          http://www.delorie.com/djgpp/getting.html
  49  
  50  You need the following files to build perl (or add new modules):
  51  
  52          v2/djdev203.zip
  53          v2gnu/bnu2112b.zip
  54          v2gnu/gcc2953b.zip
  55          v2gnu/bsh204b.zip
  56          v2gnu/mak3791b.zip
  57          v2gnu/fil40b.zip
  58          v2gnu/sed3028b.zip
  59          v2gnu/txt20b.zip
  60          v2gnu/dif272b.zip
  61          v2gnu/grep24b.zip
  62          v2gnu/shl20jb.zip
  63          v2gnu/gwk306b.zip
  64          v2misc/csdpmi5b.zip
  65  
  66  or possibly any newer version.
  67  
  68  =item Pthreads
  69  
  70  Thread support is not tested in this version of the djgpp perl.
  71  
  72  =back
  73  
  74  =head2 Shortcomings of Perl under DOS
  75  
  76  Perl under DOS lacks some features of perl under UNIX because of
  77  deficiencies in the UNIX-emulation, most notably:
  78  
  79  =over 4
  80  
  81  =item *
  82  
  83  fork() and pipe()
  84  
  85  =item *
  86  
  87  some features of the UNIX filesystem regarding link count and file dates
  88  
  89  =item *
  90  
  91  in-place operation is a little bit broken with short filenames
  92  
  93  =item *
  94  
  95  sockets
  96  
  97  =back
  98  
  99  =head2 Building Perl on DOS
 100  
 101  =over 4
 102  
 103  =item *
 104  
 105  Unpack the source package F<perl5.8*.tar.gz> with djtarx. If you want
 106  to use long file names under w95 and also to get Perl to pass all its
 107  tests, don't forget to use
 108  
 109          set LFN=y
 110          set FNCASE=y
 111  
 112  before unpacking the archive.
 113  
 114  =item *
 115  
 116  Create a "symlink" or copy your bash.exe to sh.exe in your C<($DJDIR)/bin>
 117  directory.
 118  
 119          ln -s bash.exe sh.exe
 120  
 121  [If you have the recommended version of bash for DJGPP, this is already
 122  done for you.]
 123  
 124  And make the C<SHELL> environment variable point to this F<sh.exe>:
 125  
 126          set SHELL=c:/djgpp/bin/sh.exe (use full path name!)
 127  
 128  You can do this in F<djgpp.env> too. Add this line BEFORE any section
 129  definition:
 130  
 131          +SHELL=%DJDIR%/bin/sh.exe
 132  
 133  =item *
 134  
 135  If you have F<split.exe> and F<gsplit.exe> in your path, then rename 
 136  F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>.
 137  Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>.
 138  Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>.
 139  
 140  [If you have the recommended versions of djdev, shell utilities and
 141  gawk, all these are already done for you, and you will not need to do
 142  anything.]
 143  
 144  =item *
 145  
 146  Chdir to the djgpp subdirectory of perl toplevel and type the following
 147  commands:
 148  
 149          set FNCASE=y
 150          configure.bat
 151  
 152  This will do some preprocessing then run the Configure script for you.
 153  The Configure script is interactive, but in most cases you just need to
 154  press ENTER.  The "set" command ensures that DJGPP preserves the letter
 155  case of file names when reading directories.  If you already issued this
 156  set command when unpacking the archive, and you are in the same DOS
 157  session as when you unpacked the archive, you don't have to issue the
 158  set command again.  This command is necessary *before* you start to 
 159  (re)configure or (re)build perl in order to ensure both that perl builds 
 160  correctly and that building XS-type modules can succeed.  See the DJGPP 
 161  info entry for "_preserve_fncase" for more information:
 162  
 163          info libc alphabetical _preserve_fncase
 164  
 165  If the script says that your package is incomplete, and asks whether
 166  to continue, just answer with Y (this can only happen if you don't use
 167  long filenames or forget to issue "set FNCASE=y" first).
 168  
 169  When Configure asks about the extensions, I suggest IO and Fcntl,
 170  and if you want database handling then SDBM_File or GDBM_File
 171  (you need to install gdbm for this one). If you want to use the
 172  POSIX extension (this is the default), make sure that the stack
 173  size of your F<cc1.exe> is at least 512kbyte (you can check this
 174  with: C<stubedit cc1.exe>).
 175  
 176  You can use the Configure script in non-interactive mode too.
 177  When I built my F<perl.exe>, I used something like this:
 178  
 179          configure.bat -des
 180  
 181  You can find more info about Configure's command line switches in
 182  the F<INSTALL> file.
 183  
 184  When the script ends, and you want to change some values in the
 185  generated F<config.sh> file, then run
 186  
 187          sh Configure -S
 188  
 189  after you made your modifications.
 190  
 191  IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG
 192  environment variable before running the script:
 193  
 194          set CONFIG=
 195  
 196  =item *
 197  
 198  Now you can compile Perl. Type:
 199  
 200          make
 201  
 202  =back
 203  
 204  =head2 Testing Perl on DOS
 205  
 206  Type:
 207  
 208          make test
 209  
 210  If you're lucky you should see "All tests successful". But there can be
 211  a few failed subtests (less than 5 hopefully) depending on some external
 212  conditions (e.g. some subtests fail under linux/dosemu or plain dos
 213  with short filenames only).
 214  
 215  =head2 Installation of Perl on DOS
 216  
 217  Type:
 218  
 219          make install
 220  
 221  This will copy the newly compiled perl and libraries into your DJGPP
 222  directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>,
 223  and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation
 224  goes under C<($DJDIR)/lib/perl5/pod>.
 225  
 226  =head1 BUILDING AND INSTALLING MODULES ON DOS
 227  
 228  =head2 Building Prerequisites for Perl on DOS
 229  
 230  For building and installing non-XS modules, all you need is a working
 231  perl under DJGPP.  Non-XS modules do not require re-linking the perl
 232  binary, and so are simpler to build and install.
 233  
 234  XS-type modules do require re-linking the perl binary, because part of
 235  an XS module is written in "C", and has to be linked together with the
 236  perl binary to be executed.  This is required because perl under DJGPP
 237  is built with the "static link" option, due to the lack of "dynamic
 238  linking" in the DJGPP environment.
 239  
 240  Because XS modules require re-linking of the perl binary, you need both
 241  the perl binary distribution and the perl source distribution to build
 242  an XS extension module.  In addition, you will have to have built your
 243  perl binary from the source distribution so that all of the components
 244  of the perl binary are available for the required link step.
 245  
 246  =head2 Unpacking CPAN Modules on DOS
 247  
 248  First, download the module package from CPAN (e.g., the "Comma Separated
 249  Value" text package, Text-CSV-0.01.tar.gz).  Then expand the contents of
 250  the package into some location on your disk.  Most CPAN modules are
 251  built with an internal directory structure, so it is usually safe to
 252  expand it in the root of your DJGPP installation.  Some people prefer to
 253  locate source trees under /usr/src (i.e., C<($DJDIR)/usr/src>), but you may
 254  put it wherever seems most logical to you, *EXCEPT* under the same
 255  directory as your perl source code.  There are special rules that apply
 256  to modules which live in the perl source tree that do not apply to most
 257  of the modules in CPAN.
 258  
 259  Unlike other DJGPP packages, which are normal "zip" files, most CPAN
 260  module packages are "gzipped tarballs".  Recent versions of WinZip will
 261  safely unpack and expand them, *UNLESS* they have zero-length files.  It
 262  is a known WinZip bug (as of v7.0) that it will not extract zero-length
 263  files.
 264  
 265  From the command line, you can use the djtar utility provided with DJGPP
 266  to unpack and expand these files.  For example:
 267  
 268          C:\djgpp>djtarx -v Text-CSV-0.01.tar.gz
 269  
 270  This will create the new directory C<($DJDIR)/Text-CSV-0.01>, filling
 271  it with the source for this module.
 272  
 273  =head2 Building Non-XS Modules on DOS
 274  
 275  To build a non-XS module, you can use the standard module-building
 276  instructions distributed with perl modules.
 277  
 278      perl Makefile.PL
 279      make
 280      make test
 281      make install
 282  
 283  This is sufficient because non-XS modules install only ".pm" files and
 284  (sometimes) pod and/or man documentation.  No re-linking of the perl
 285  binary is needed to build, install or use non-XS modules.
 286  
 287  =head2 Building XS Modules on DOS
 288  
 289  To build an XS module, you must use the standard module-building
 290  instructions distributed with perl modules *PLUS* three extra
 291  instructions specific to the DJGPP "static link" build environment.
 292  
 293      set FNCASE=y
 294      perl Makefile.PL
 295      make
 296      make perl
 297      make test
 298      make -f Makefile.aperl inst_perl MAP_TARGET=perl.exe
 299      make install
 300  
 301  The first extra instruction sets DJGPP's FNCASE environment variable so
 302  that the new perl binary which you must build for an XS-type module will
 303  build correctly.  The second extra instruction re-builds the perl binary
 304  in your module directory before you run "make test", so that you are
 305  testing with the new module code you built with "make".  The third extra
 306  instruction installs the perl binary from your module directory into the
 307  standard DJGPP binary directory, C<($DJDIR)/bin>, replacing your
 308  previous perl binary.
 309  
 310  Note that the MAP_TARGET value *must* have the ".exe" extension or you
 311  will not create a "perl.exe" to replace the one in C<($DJDIR)/bin>.
 312  
 313  When you are done, the XS-module install process will have added information
 314  to your "perllocal" information telling that the perl binary has been replaced,
 315  and what module was installed.  You can view this information at any time
 316  by using the command:
 317  
 318          perl -S perldoc perllocal
 319  
 320  =head1 AUTHOR
 321  
 322  Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se> [Installing/building perl]
 323  
 324  Peter J. Farley III F<pjfarley@banet.net> [Building/installing modules]
 325  
 326  =head1 SEE ALSO
 327  
 328  perl(1).
 329  
 330  =cut
 331