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 | ||
0a31a4b2 | 46 | You can find the full DJGPP distribution on any of the mirrors listed here: |
94bf5962 | 47 | |
0a31a4b2 | 48 | http://www.delorie.com/djgpp/getting.html |
94bf5962 GS |
49 | |
50 | You need the following files to build perl (or add new modules): | |
51 | ||
52 | v2/djdev203.zip | |
97d5a6db JH |
53 | v2gnu/bnu2112b.zip |
54 | v2gnu/gcc2953b.zip | |
94bf5962 GS |
55 | v2gnu/bsh204b.zip |
56 | v2gnu/mak3791b.zip | |
97d5a6db JH |
57 | v2gnu/fil40b.zip |
58 | v2gnu/sed3028b.zip | |
94bf5962 GS |
59 | v2gnu/txt20b.zip |
60 | v2gnu/dif272b.zip | |
61 | v2gnu/grep24b.zip | |
97d5a6db JH |
62 | v2gnu/shl20jb.zip |
63 | v2gnu/gwk306b.zip | |
64 | v2misc/csdpmi5b.zip | |
94bf5962 GS |
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 | ||
afdf87ad | 105 | Unpack the source package F<perl5.8*.tar.gz> with djtarx. If you want |
94bf5962 GS |
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 | |
210b36aa | 314 | to your "perllocal" information telling that the perl binary has been replaced, |
3a1825b5 | 315 | and what module was installed. You can view this information at any time |
94bf5962 GS |
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 |