README.dos

   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