Retract the mergesort code, way too incompatible licensing
[perl.git] / 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.01 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 =head2 Prerequisites
26
27 =over 4
28
29 =item DJGPP
30
31 DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit,
32 protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible
33 operating systems, by DJ Delorie <dj@delorie.com> and friends.
34
35 For more details (FAQ), check out the home of DJGPP at:
36
37         http://www.delorie.com/djgpp/
38
39 If you have questions about DJGPP, try posting to the DJGPP newsgroup:
40 comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com.
41
42 You can find the full DJGPP distribution on any SimTel.Net mirror all over
43 the world. Like:
44
45         ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2*
46
47 You need the following files to build perl (or add new modules):
48
49         v2/djdev202.zip
50         v2/bnu27b.zip
51         v2gnu/gcc2721b.zip
52         v2gnu/bsh1147b.zip
53         v2gnu/mak3761b.zip
54         v2gnu/fil316b.zip
55         v2gnu/sed118b.zip
56         v2gnu/txt122b.zip
57         v2gnu/dif271b.zip
58         v2gnu/grep21b.zip
59         v2gnu/shl112b.zip
60         v2gnu/gawk303b.zip
61         v2misc/csdpmi4b.zip 
62
63 or possibly any newer version.
64
65 =item Pthreads
66
67 Thread support is not tested in this version of the djgpp perl.
68
69 =back
70
71 =head2 Shortcomings of Perl under DOS
72
73 Perl under DOS lacks some features of perl under UNIX because of
74 deficiencies in the UNIX-emulation, most notably:
75
76 =over 4
77
78 =item *
79
80 fork() and pipe()
81
82 =item *
83
84 some features of the UNIX filesystem regarding link count and file dates
85
86 =item *
87
88 in-place operation is a little bit broken with short filenames
89
90 =item *
91
92 sockets
93
94 =back
95
96 =head2 Building
97
98 =over 4
99
100 =item *
101
102 Unpack the source package F<perl5.6*.tar.gz> with djtarx. If you want
103 to use long file names under w95, don't forget to use
104
105         set LFN=y
106
107 before unpacking the archive.
108
109 =item *
110
111 Create a "symlink" or copy your bash.exe to sh.exe in your C<($DJDIR)/bin>
112 directory.
113
114         ln -s bash.exe sh.exe
115
116 And make the C<SHELL> environment variable point to this F<sh.exe>:
117
118         set SHELL=c:/djgpp/bin/sh.exe (use full path name!)
119
120 You can do this in F<djgpp.env> too. Add this line BEFORE any section
121 definition:
122
123         +SHELL=%DJDIR%/bin/sh.exe
124
125 =item *
126
127 If you have F<split.exe> and F<gsplit.exe> in your path, then rename 
128 F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>.
129 Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>.
130 Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>.
131
132 =item *
133
134 Chdir to the djgpp subdirectory of perl toplevel and type the following
135 command:
136
137         configure.bat
138
139 This will do some preprocessing then run the Configure script for you.
140 The Configure script is interactive, but in most cases you
141 just need to press ENTER.
142
143 If the script says that your package is incomplete, and asks whether
144 to continue, just answer with Y (this can only happen if you don't use
145 long filenames).
146
147 When Configure asks about the extensions, I suggest IO and Fcntl,
148 and if you want database handling then SDBM_File or GDBM_File
149 (you need to install gdbm for this one). If you want to use the
150 POSIX extension (this is the default), make sure that the stack
151 size of your F<cc1.exe> is at least 512kbyte (you can check this
152 with: C<stubedit cc1.exe>).
153
154 You can use the Configure script in non-interactive mode too.
155 When I built my F<perl.exe>, I used something like this:
156
157         configure.bat -des
158
159 You can find more info about Configure's command line switches in
160 the F<INSTALL> file.
161
162 When the script ends, and you want to change some values in the
163 generated F<config.sh> file, then run
164
165         sh Configure -S
166
167 after you made your modifications.
168
169 IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG
170 environment variable before running the script:
171
172         set CONFIG=
173
174 =item *
175
176 Now you can compile Perl. Type:
177
178         make
179
180 =back
181
182 =head2 Testing
183
184 Type:
185
186         make test
187
188 If you're lucky you should see "All tests successful". But there can be
189 a few failed subtests (less than 5 hopefully) depending on some external
190 conditions (e.g. some subtests fail under linux/dosemu or plain dos
191 with short filenames only).
192
193 =head2 Installation
194
195 Type:
196
197         make install
198
199 This will copy the newly compiled perl and libraries into your DJGPP
200 directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>,
201 and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation
202 goes under C<($DJDIR)/lib/perl5/pod>.
203
204 =head1 AUTHOR
205
206 Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se>
207
208 =head1 SEE ALSO
209
210 perl(1).
211
212 =cut
213