Commit | Line | Data |
---|---|---|
94bf5962 GS |
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 SimTel.Net mirror all over | |
47 | the world. Like: | |
48 | ||
49 | ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2* | |
50 | ||
51 | You need the following files to build perl (or add new modules): | |
52 | ||
53 | v2/djdev203.zip | |
97d5a6db JH |
54 | v2gnu/bnu2112b.zip |
55 | v2gnu/gcc2953b.zip | |
94bf5962 GS |
56 | v2gnu/bsh204b.zip |
57 | v2gnu/mak3791b.zip | |
97d5a6db JH |
58 | v2gnu/fil40b.zip |
59 | v2gnu/sed3028b.zip | |
94bf5962 GS |
60 | v2gnu/txt20b.zip |
61 | v2gnu/dif272b.zip | |
62 | v2gnu/grep24b.zip | |
97d5a6db JH |
63 | v2gnu/shl20jb.zip |
64 | v2gnu/gwk306b.zip | |
65 | v2misc/csdpmi5b.zip | |
94bf5962 GS |
66 | |
67 | or possibly any newer version. | |
68 | ||
69 | =item Pthreads | |
70 | ||
71 | Thread support is not tested in this version of the djgpp perl. | |
72 | ||
73 | =back | |
74 | ||
75 | =head2 Shortcomings of Perl under DOS | |
76 | ||
77 | Perl under DOS lacks some features of perl under UNIX because of | |
78 | deficiencies in the UNIX-emulation, most notably: | |
79 | ||
80 | =over 4 | |
81 | ||
82 | =item * | |
83 | ||
84 | fork() and pipe() | |
85 | ||
86 | =item * | |
87 | ||
88 | some features of the UNIX filesystem regarding link count and file dates | |
89 | ||
90 | =item * | |
91 | ||
92 | in-place operation is a little bit broken with short filenames | |
93 | ||
94 | =item * | |
95 | ||
96 | sockets | |
97 | ||
98 | =back | |
99 | ||
100 | =head2 Building Perl on DOS | |
101 | ||
102 | =over 4 | |
103 | ||
104 | =item * | |
105 | ||
afdf87ad | 106 | Unpack the source package F<perl5.8*.tar.gz> with djtarx. If you want |
94bf5962 GS |
107 | to use long file names under w95 and also to get Perl to pass all its |
108 | tests, don't forget to use | |
109 | ||
110 | set LFN=y | |
111 | set FNCASE=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 | [If you have the recommended version of bash for DJGPP, this is already | |
123 | done for you.] | |
124 | ||
125 | And make the C<SHELL> environment variable point to this F<sh.exe>: | |
126 | ||
127 | set SHELL=c:/djgpp/bin/sh.exe (use full path name!) | |
128 | ||
129 | You can do this in F<djgpp.env> too. Add this line BEFORE any section | |
130 | definition: | |
131 | ||
132 | +SHELL=%DJDIR%/bin/sh.exe | |
133 | ||
134 | =item * | |
135 | ||
136 | If you have F<split.exe> and F<gsplit.exe> in your path, then rename | |
137 | F<split.exe> to F<djsplit.exe>, and F<gsplit.exe> to F<split.exe>. | |
138 | Copy or link F<gecho.exe> to F<echo.exe> if you don't have F<echo.exe>. | |
139 | Copy or link F<gawk.exe> to F<awk.exe> if you don't have F<awk.exe>. | |
140 | ||
141 | [If you have the recommended versions of djdev, shell utilities and | |
142 | gawk, all these are already done for you, and you will not need to do | |
143 | anything.] | |
144 | ||
145 | =item * | |
146 | ||
147 | Chdir to the djgpp subdirectory of perl toplevel and type the following | |
148 | commands: | |
149 | ||
150 | set FNCASE=y | |
151 | configure.bat | |
152 | ||
153 | This will do some preprocessing then run the Configure script for you. | |
154 | The Configure script is interactive, but in most cases you just need to | |
155 | press ENTER. The "set" command ensures that DJGPP preserves the letter | |
156 | case of file names when reading directories. If you already issued this | |
157 | set command when unpacking the archive, and you are in the same DOS | |
158 | session as when you unpacked the archive, you don't have to issue the | |
159 | set command again. This command is necessary *before* you start to | |
160 | (re)configure or (re)build perl in order to ensure both that perl builds | |
161 | correctly and that building XS-type modules can succeed. See the DJGPP | |
162 | info entry for "_preserve_fncase" for more information: | |
163 | ||
164 | info libc alphabetical _preserve_fncase | |
165 | ||
166 | If the script says that your package is incomplete, and asks whether | |
167 | to continue, just answer with Y (this can only happen if you don't use | |
168 | long filenames or forget to issue "set FNCASE=y" first). | |
169 | ||
170 | When Configure asks about the extensions, I suggest IO and Fcntl, | |
171 | and if you want database handling then SDBM_File or GDBM_File | |
172 | (you need to install gdbm for this one). If you want to use the | |
173 | POSIX extension (this is the default), make sure that the stack | |
174 | size of your F<cc1.exe> is at least 512kbyte (you can check this | |
175 | with: C<stubedit cc1.exe>). | |
176 | ||
177 | You can use the Configure script in non-interactive mode too. | |
178 | When I built my F<perl.exe>, I used something like this: | |
179 | ||
180 | configure.bat -des | |
181 | ||
182 | You can find more info about Configure's command line switches in | |
183 | the F<INSTALL> file. | |
184 | ||
185 | When the script ends, and you want to change some values in the | |
186 | generated F<config.sh> file, then run | |
187 | ||
188 | sh Configure -S | |
189 | ||
190 | after you made your modifications. | |
191 | ||
192 | IMPORTANT: if you use this C<-S> switch, be sure to delete the CONFIG | |
193 | environment variable before running the script: | |
194 | ||
195 | set CONFIG= | |
196 | ||
197 | =item * | |
198 | ||
199 | Now you can compile Perl. Type: | |
200 | ||
201 | make | |
202 | ||
203 | =back | |
204 | ||
205 | =head2 Testing Perl on DOS | |
206 | ||
207 | Type: | |
208 | ||
209 | make test | |
210 | ||
211 | If you're lucky you should see "All tests successful". But there can be | |
212 | a few failed subtests (less than 5 hopefully) depending on some external | |
213 | conditions (e.g. some subtests fail under linux/dosemu or plain dos | |
214 | with short filenames only). | |
215 | ||
216 | =head2 Installation of Perl on DOS | |
217 | ||
218 | Type: | |
219 | ||
220 | make install | |
221 | ||
222 | This will copy the newly compiled perl and libraries into your DJGPP | |
223 | directory structure. Perl.exe and the utilities go into C<($DJDIR)/bin>, | |
224 | and the library goes under C<($DJDIR)/lib/perl5>. The pod documentation | |
225 | goes under C<($DJDIR)/lib/perl5/pod>. | |
226 | ||
227 | =head1 BUILDING AND INSTALLING MODULES ON DOS | |
228 | ||
229 | =head2 Building Prerequisites for Perl on DOS | |
230 | ||
231 | For building and installing non-XS modules, all you need is a working | |
232 | perl under DJGPP. Non-XS modules do not require re-linking the perl | |
233 | binary, and so are simpler to build and install. | |
234 | ||
235 | XS-type modules do require re-linking the perl binary, because part of | |
236 | an XS module is written in "C", and has to be linked together with the | |
237 | perl binary to be executed. This is required because perl under DJGPP | |
238 | is built with the "static link" option, due to the lack of "dynamic | |
239 | linking" in the DJGPP environment. | |
240 | ||
241 | Because XS modules require re-linking of the perl binary, you need both | |
242 | the perl binary distribution and the perl source distribution to build | |
243 | an XS extension module. In addition, you will have to have built your | |
244 | perl binary from the source distribution so that all of the components | |
245 | of the perl binary are available for the required link step. | |
246 | ||
247 | =head2 Unpacking CPAN Modules on DOS | |
248 | ||
249 | First, download the module package from CPAN (e.g., the "Comma Separated | |
250 | Value" text package, Text-CSV-0.01.tar.gz). Then expand the contents of | |
251 | the package into some location on your disk. Most CPAN modules are | |
252 | built with an internal directory structure, so it is usually safe to | |
253 | expand it in the root of your DJGPP installation. Some people prefer to | |
254 | locate source trees under /usr/src (i.e., C<($DJDIR)/usr/src>), but you may | |
255 | put it wherever seems most logical to you, *EXCEPT* under the same | |
256 | directory as your perl source code. There are special rules that apply | |
257 | to modules which live in the perl source tree that do not apply to most | |
258 | of the modules in CPAN. | |
259 | ||
260 | Unlike other DJGPP packages, which are normal "zip" files, most CPAN | |
261 | module packages are "gzipped tarballs". Recent versions of WinZip will | |
262 | safely unpack and expand them, *UNLESS* they have zero-length files. It | |
263 | is a known WinZip bug (as of v7.0) that it will not extract zero-length | |
264 | files. | |
265 | ||
266 | From the command line, you can use the djtar utility provided with DJGPP | |
267 | to unpack and expand these files. For example: | |
268 | ||
269 | C:\djgpp>djtarx -v Text-CSV-0.01.tar.gz | |
270 | ||
271 | This will create the new directory C<($DJDIR)/Text-CSV-0.01>, filling | |
272 | it with the source for this module. | |
273 | ||
274 | =head2 Building Non-XS Modules on DOS | |
275 | ||
276 | To build a non-XS module, you can use the standard module-building | |
277 | instructions distributed with perl modules. | |
278 | ||
279 | perl Makefile.PL | |
280 | make | |
281 | make test | |
282 | make install | |
283 | ||
284 | This is sufficient because non-XS modules install only ".pm" files and | |
285 | (sometimes) pod and/or man documentation. No re-linking of the perl | |
286 | binary is needed to build, install or use non-XS modules. | |
287 | ||
288 | =head2 Building XS Modules on DOS | |
289 | ||
290 | To build an XS module, you must use the standard module-building | |
291 | instructions distributed with perl modules *PLUS* three extra | |
292 | instructions specific to the DJGPP "static link" build environment. | |
293 | ||
294 | set FNCASE=y | |
295 | perl Makefile.PL | |
296 | make | |
297 | make perl | |
298 | make test | |
299 | make -f Makefile.aperl inst_perl MAP_TARGET=perl.exe | |
300 | make install | |
301 | ||
302 | The first extra instruction sets DJGPP's FNCASE environment variable so | |
303 | that the new perl binary which you must build for an XS-type module will | |
304 | build correctly. The second extra instruction re-builds the perl binary | |
305 | in your module directory before you run "make test", so that you are | |
306 | testing with the new module code you built with "make". The third extra | |
307 | instruction installs the perl binary from your module directory into the | |
308 | standard DJGPP binary directory, C<($DJDIR)/bin>, replacing your | |
309 | previous perl binary. | |
310 | ||
311 | Note that the MAP_TARGET value *must* have the ".exe" extension or you | |
312 | will not create a "perl.exe" to replace the one in C<($DJDIR)/bin>. | |
313 | ||
314 | When you are done, the XS-module install process will have added information | |
210b36aa | 315 | to your "perllocal" information telling that the perl binary has been replaced, |
3a1825b5 | 316 | and what module was installed. You can view this information at any time |
94bf5962 GS |
317 | by using the command: |
318 | ||
319 | perl -S perldoc perllocal | |
320 | ||
321 | =head1 AUTHOR | |
322 | ||
323 | Laszlo Molnar, F<laszlo.molnar@eth.ericsson.se> [Installing/building perl] | |
324 | ||
325 | Peter J. Farley III F<pjfarley@banet.net> [Building/installing modules] | |
326 | ||
327 | =head1 SEE ALSO | |
328 | ||
329 | perl(1). | |
330 | ||
331 | =cut | |
332 |