mingw/html/pod/perldos.html

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