This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
dos-djgpp update (from Laszlo Molnar <laszlo.molnar@eth.ericsson.se>)
[perl5.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/djdev201.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 any newer version.
64
65 =item Pthreads
66
67 If you want multithreading support in perl, you need a pthread library
68 that supports DJGPP. One of them can be found at:
69
70         ftp://ftp.cs.fsu.edu/pub/PART/PTHREADS/pthreads.zip
71
72 But thread support is still in alpha, it may be unstable. For more information
73 see below.
74
75 =back
76
77 =head2 Shortcomings of Perl under DOS
78
79 Perl under DOS lacks some features of perl under UNIX because of
80 deficiencies in the UNIX-emulation, most notably:
81
82 =over 4
83
84 =item *
85
86 fork() and pipe()
87
88 =item *
89
90 some features of the UNIX filesystem regarding link count and file dates
91
92 =item *
93
94 in-place operation is a little bit broken with short filenames
95
96 =item *
97
98 sockets
99
100 =back
101
102 =head2 Building
103
104 =over 4
105
106 =item *
107
108 Unpack the source package F<perl5.00?_??.tar.gz> with djtarx. If you want
109 to use long file names under w95, don't forget to use
110
111         set LFN=y
112         
113 before unpacking the archive.
114
115 =item *
116
117 Create a "symlink" or copy your bash.exe to sh.exe in your C<($DJDIR)/bin>
118 directory.
119
120         ln -s bash.exe sh.exe
121
122 And make the C<SHELL> environment variable point to this F<sh.exe>:
123
124         set SHELL=c:/djgpp/bin/sh.exe (use full path name!)
125
126 You can do this in F<djgpp.env> too. Add this line BEFORE any section
127 definition:
128
129         +SHELL=%DJDIR%/bin/sh.exe
130
131 =item *
132
133 If you have F<split.exe> and F<gsplit.exe> in your path, then rename 
134 F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>.
135 Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>.
136 Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>.
137
138 =item *
139
140 Chdir to the djgpp subdirectory of perl toplevel and type the following
141 command:
142
143         configure.bat
144
145 This will do some preprocessing then run the Configure script for you.
146 The Configure script is interactive, but in most cases you
147 just need to press ENTER.
148
149 If the script says that your package is incomplete, and asks whether
150 to continue, just answer with Y (this can only happen if you don't use
151 long filenames).
152
153 When Configure asks about the extensions, I suggest IO and Fcntl,
154 and if you want database handling then SDBM_File or GDBM_File
155 (you need to install gdbm for this one). If you want to use the
156 POSIX extension (this is the default), make sure that the stack
157 size of your F<cc1.exe> is at least 512kbyte (you can check this
158 with: C<stubedit cc1.exe>).
159
160 You can use the Configure script in non-interactive mode too.
161 When I built my F<perl.exe>, I used something like this:
162
163         configure.bat -Uuseposix -des
164
165 You can find more info about Configure's command line switches in
166 the F<INSTALL> file.
167
168 When the script ends, and you want to change some values in the
169 generated F<config.sh> file, then run
170
171         sh Configure -S
172
173 after you made your modifications.
174
175 IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG
176 environment variable before running the script:
177
178         set CONFIG=
179
180 =item *
181
182 Now you can compile Perl. Type:
183
184         make
185
186 =back
187
188 =head2 Testing
189
190 Type:
191
192         make test
193
194 You should see "All tests successful" if you configured a database
195 manager, and 1 failed test script if not (F<lib/anydbm.t>). If you
196 configured POSIX you will see 1 additional failed subtest in F<lib/posix.t>.
197
198 =head2 Installation
199
200 Type:
201
202         make install
203
204 This will copy the newly compiled perl and libraries into your DJGPP
205 directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>,
206 and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation
207 goes under C<($DJDIR)/lib/perl5/pod>.
208
209 =head2 Threaded perl under dos-djgpp
210
211 Multithreading support is considered alpha, because some of the
212 tests in C<ext/Thread> still die with SIGSEGV (patches are welcome). But
213 if you want to give it a try, here are the necessary steps:
214
215 =over 4
216
217 =item
218
219 1. You will need a pthread library which supports djgpp. Go, and download
220 FSU's version from:
221
222       ftp://ftp.cs.fsu.edu/pub/PART/PTHREADS/pthreads.zip
223
224 The latest version is 3.5, released in Feb 98.
225
226 =item 
227
228 2. Unzip the file, cd to C<threads\src> and run F<configur.bat>.
229
230 =item 
231
232 3. Add C<RAND_SWITCH> or C<MUTEX_SWITCH> or C<RR_SWITCH> to C<CFLAGS>
233 in the F<makefile>. Note that using these values, multithreading will
234 NOT be preemptive. This is necessary, since djgpp's libc is not thread safe.
235
236 =item 
237
238 4. Apply the following patch:
239
240     *** include/pthread/signal.h~       Wed Feb  4 10:51:24 1998
241     --- include/pthread/signal.h        Tue Feb 10 22:40:32 1998
242     ***************
243     *** 364,368 ****
244     --- 364,370 ----
245       
246       #ifndef SA_ONSTACK
247     + #ifdef  SV_ONSTACK
248       #define SA_ONSTACK SV_ONSTACK
249     + #endif
250       #endif /* !SA_ONSTACK */
251
252 =item
253
254 5. run make (before you do this, you must make sure your C<SHELL> environment 
255 variable does NOT point to bash).
256
257 =item
258
259 6. Install the library and header files into your djgpp directory structure.
260
261 =item
262
263 7. Add C<-Dusethreads> to the commmand line of perl's F<configure.bat>.
264
265 =back
266
267 =head1 AUTHOR
268
269 Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se>
270
271 =head1 SEE ALSO
272
273 perl(1).
274
275 =cut
276