"Fossies" - the Fresh Open Source Software Archive

Member "perl-5.32.1/README.dos" (18 Dec 2020, 10522 Bytes) of package /linux/misc/perl-5.32.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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