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