Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLCYGWIN 1" | |
132 | .TH PERLCYGWIN 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | README.cygwin \- Perl for Cygwin | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | This document will help you configure, make, test and install Perl | |
138 | on Cygwin. This document also describes features of Cygwin that will | |
139 | affect how Perl behaves at runtime. | |
140 | .PP | |
141 | \&\fB\s-1NOTE:\s0\fR There are pre-built Perl packages available for Cygwin and a | |
142 | version of Perl is provided in the normal Cygwin install. If you do | |
143 | not need to customize the configuration, consider using one of those | |
144 | packages. | |
145 | .SH "PREREQUISITES FOR COMPILING PERL ON CYGWIN" | |
146 | .IX Header "PREREQUISITES FOR COMPILING PERL ON CYGWIN" | |
147 | .Sh "Cygwin = GNU+Cygnus+Windows (Don't leave \s-1UNIX\s0 without it)" | |
148 | .IX Subsection "Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)" | |
149 | The Cygwin tools are ports of the popular \s-1GNU\s0 development tools for Win32 | |
150 | platforms. They run thanks to the Cygwin library which provides the \s-1UNIX\s0 | |
151 | system calls and environment these programs expect. More information | |
152 | about this project can be found at: | |
153 | .PP | |
154 | .Vb 1 | |
155 | \& http://www.cygwin.com/ | |
156 | .Ve | |
157 | .PP | |
158 | A recent net or commercial release of Cygwin is required. | |
159 | .PP | |
160 | At the time this document was last updated, Cygwin 1.5.2 was current. | |
161 | .Sh "Cygwin Configuration" | |
162 | .IX Subsection "Cygwin Configuration" | |
163 | While building Perl some changes may be necessary to your Cygwin setup so | |
164 | that Perl builds cleanly. These changes are \fBnot\fR required for normal | |
165 | Perl usage. | |
166 | .PP | |
167 | \&\fB\s-1NOTE:\s0\fR The binaries that are built will run on all Win32 versions. | |
168 | They do not depend on your host system (Win9x/WinME, WinNT/Win2K) | |
169 | or your Cygwin configuration (\fIntea\fR, \fIntsec\fR, binary/text mounts). | |
170 | The only dependencies come from hard-coded pathnames like \f(CW\*(C`/usr/local\*(C'\fR. | |
171 | However, your host system and Cygwin configuration will affect Perl's | |
172 | runtime behavior (see \*(L"\s-1TEST\s0\*(R"). | |
173 | .ie n .IP "* ""PATH""" 4 | |
174 | .el .IP "* \f(CWPATH\fR" 4 | |
175 | .IX Item "PATH" | |
176 | Set the \f(CW\*(C`PATH\*(C'\fR environment variable so that Configure finds the Cygwin | |
177 | versions of programs. Any Windows directories should be removed or | |
178 | moved to the end of your \f(CW\*(C`PATH\*(C'\fR. | |
179 | .IP "* \fInroff\fR" 4 | |
180 | .IX Item "nroff" | |
181 | If you do not have \fInroff\fR (which is part of the \fIgroff\fR package), | |
182 | Configure will \fBnot\fR prompt you to install \fIman\fR pages. | |
183 | .IP "* Permissions" 4 | |
184 | .IX Item "Permissions" | |
185 | On WinNT with either the \fIntea\fR or \fIntsec\fR \f(CW\*(C`CYGWIN\*(C'\fR settings, directory | |
186 | and file permissions may not be set correctly. Since the build process | |
187 | creates directories and files, to be safe you may want to run a | |
188 | \&\f(CW\*(C`chmod \-R +w *\*(C'\fR on the entire Perl source tree. | |
189 | .Sp | |
190 | Also, it is a well known WinNT \*(L"feature\*(R" that files created by a login | |
191 | that is a member of the \fIAdministrators\fR group will be owned by the | |
192 | \&\fIAdministrators\fR group. Depending on your umask, you may find that you | |
193 | can not write to files that you just created (because you are no longer | |
194 | the owner). When using the \fIntsec\fR \f(CW\*(C`CYGWIN\*(C'\fR setting, this is not an | |
195 | issue because it \*(L"corrects\*(R" the ownership to what you would expect on | |
196 | a \s-1UNIX\s0 system. | |
197 | .SH "CONFIGURE PERL ON CYGWIN" | |
198 | .IX Header "CONFIGURE PERL ON CYGWIN" | |
199 | The default options gathered by Configure with the assistance of | |
200 | \&\fIhints/cygwin.sh\fR will build a Perl that supports dynamic loading | |
201 | (which requires a shared \fIlibperl.dll\fR). | |
202 | .PP | |
203 | This will run Configure and keep a record: | |
204 | .PP | |
205 | .Vb 1 | |
206 | \& ./Configure 2>&1 | tee log.configure | |
207 | .Ve | |
208 | .PP | |
209 | If you are willing to accept all the defaults run Configure with \fB\-de\fR. | |
210 | However, several useful customizations are available. | |
211 | .Sh "Stripping Perl Binaries on Cygwin" | |
212 | .IX Subsection "Stripping Perl Binaries on Cygwin" | |
213 | It is possible to strip the EXEs and DLLs created by the build process. | |
214 | The resulting binaries will be significantly smaller. If you want the | |
215 | binaries to be stripped, you can either add a \fB\-s\fR option when Configure | |
216 | prompts you, | |
217 | .PP | |
218 | .Vb 4 | |
219 | \& Any additional ld flags (NOT including libraries)? [none] -s | |
220 | \& Any special flags to pass to gcc to use dynamic linking? [none] -s | |
221 | \& Any special flags to pass to ld2 to create a dynamically loaded library? | |
222 | \& [none] -s | |
223 | .Ve | |
224 | .PP | |
225 | or you can edit \fIhints/cygwin.sh\fR and uncomment the relevant variables | |
226 | near the end of the file. | |
227 | .Sh "Optional Libraries for Perl on Cygwin" | |
228 | .IX Subsection "Optional Libraries for Perl on Cygwin" | |
229 | Several Perl functions and modules depend on the existence of | |
230 | some optional libraries. Configure will find them if they are | |
231 | installed in one of the directories listed as being used for library | |
232 | searches. Pre-built packages for most of these are available from | |
233 | the Cygwin installer. | |
234 | .ie n .IP "* ""\-lcrypt""" 4 | |
235 | .el .IP "* \f(CW\-lcrypt\fR" 4 | |
236 | .IX Item "-lcrypt" | |
237 | The crypt package distributed with Cygwin is a Linux compatible 56\-bit | |
238 | \&\s-1DES\s0 crypt port by Corinna Vinschen. | |
239 | .Sp | |
240 | Alternatively, the crypt libraries in \s-1GNU\s0 libc have been ported to Cygwin. | |
241 | .Sp | |
242 | The \s-1DES\s0 based Ultra Fast Crypt port was done by Alexey Truhan: | |
243 | .Sp | |
244 | .Vb 1 | |
245 | \& ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Okhapkin_Sergey/cw32crypt-dist-0.tgz | |
246 | .Ve | |
247 | .Sp | |
248 | \&\s-1NOTE:\s0 There are various export restrictions on \s-1DES\s0 implementations, | |
249 | see the glibc \s-1README\s0 for more details. | |
250 | .Sp | |
251 | The \s-1MD5\s0 port was done by Andy Piper: | |
252 | .Sp | |
253 | .Vb 1 | |
254 | \& ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Okhapkin_Sergey/libcrypt.tgz | |
255 | .Ve | |
256 | .ie n .IP "* ""\-lgdbm""\fR (\f(CW""use GDBM_File"")" 4 | |
257 | .el .IP "* \f(CW\-lgdbm\fR (\f(CWuse GDBM_File\fR)" 4 | |
258 | .IX Item "-lgdbm (use GDBM_File)" | |
259 | \&\s-1GDBM\s0 is available for Cygwin. | |
260 | .Sp | |
261 | \&\s-1NOTE:\s0 The \s-1GDBM\s0 library only works on \s-1NTFS\s0 partitions. | |
262 | .ie n .IP "* ""\-ldb""\fR (\f(CW""use DB_File"")" 4 | |
263 | .el .IP "* \f(CW\-ldb\fR (\f(CWuse DB_File\fR)" 4 | |
264 | .IX Item "-ldb (use DB_File)" | |
265 | BerkeleyDB is available for Cygwin. | |
266 | .Sp | |
267 | \&\s-1NOTE:\s0 The BerkeleyDB library only completely works on \s-1NTFS\s0 partitions. | |
268 | .ie n .IP "* ""\-lcygipc""\fR (\f(CW""use IPC::SysV"")" 4 | |
269 | .el .IP "* \f(CW\-lcygipc\fR (\f(CWuse IPC::SysV\fR)" 4 | |
270 | .IX Item "-lcygipc (use IPC::SysV)" | |
271 | A port of SysV \s-1IPC\s0 is available for Cygwin. | |
272 | .Sp | |
273 | \&\s-1NOTE:\s0 This has \fBnot\fR been extensively tested. In particular, | |
274 | \&\f(CW\*(C`d_semctl_semun\*(C'\fR is undefined because it fails a Configure test | |
275 | and on Win9x the \fIshm*()\fR functions seem to hang. It also creates | |
276 | a compile time dependency because \fIperl.h\fR includes \fI<sys/ipc.h\fR> | |
277 | and \fI<sys/sem.h\fR> (which will be required in the future when compiling | |
278 | \&\s-1CPAN\s0 modules). \s-1CURRENTLY\s0 \s-1NOT\s0 \s-1SUPPORTED\s0! | |
279 | .ie n .IP "* ""\-lutil""" 4 | |
280 | .el .IP "* \f(CW\-lutil\fR" 4 | |
281 | .IX Item "-lutil" | |
282 | Included with the standard Cygwin netrelease is the inetutils package | |
283 | which includes libutil.a. | |
284 | .Sh "Configure-time Options for Perl on Cygwin" | |
285 | .IX Subsection "Configure-time Options for Perl on Cygwin" | |
286 | The \fI\s-1INSTALL\s0\fR document describes several Configure-time options. Some of | |
287 | these will work with Cygwin, others are not yet possible. Also, some of | |
288 | these are experimental. You can either select an option when Configure | |
289 | prompts you or you can define (undefine) symbols on the command line. | |
290 | .ie n .IP "* ""\-Uusedl""" 4 | |
291 | .el .IP "* \f(CW\-Uusedl\fR" 4 | |
292 | .IX Item "-Uusedl" | |
293 | Undefining this symbol forces Perl to be compiled statically. | |
294 | .ie n .IP "* ""\-Uusemymalloc""" 4 | |
295 | .el .IP "* \f(CW\-Uusemymalloc\fR" 4 | |
296 | .IX Item "-Uusemymalloc" | |
297 | By default Perl uses the \f(CW\*(C`malloc()\*(C'\fR included with the Perl source. If you | |
298 | want to force Perl to build with the system \f(CW\*(C`malloc()\*(C'\fR undefine this symbol. | |
299 | .ie n .IP "* ""\-Uuseperlio""" 4 | |
300 | .el .IP "* \f(CW\-Uuseperlio\fR" 4 | |
301 | .IX Item "-Uuseperlio" | |
302 | Undefining this symbol disables the PerlIO abstraction. PerlIO is now the | |
303 | default; it is not recommended to disable PerlIO. | |
304 | .ie n .IP "* ""\-Dusemultiplicity""" 4 | |
305 | .el .IP "* \f(CW\-Dusemultiplicity\fR" 4 | |
306 | .IX Item "-Dusemultiplicity" | |
307 | Multiplicity is required when embedding Perl in a C program and using | |
308 | more than one interpreter instance. This works with the Cygwin port. | |
309 | .ie n .IP "* ""\-Duse64bitint""" 4 | |
310 | .el .IP "* \f(CW\-Duse64bitint\fR" 4 | |
311 | .IX Item "-Duse64bitint" | |
312 | By default Perl uses 32 bit integers. If you want to use larger 64 | |
313 | bit integers, define this symbol. | |
314 | .ie n .IP "* ""\-Duselongdouble""" 4 | |
315 | .el .IP "* \f(CW\-Duselongdouble\fR" 4 | |
316 | .IX Item "-Duselongdouble" | |
317 | \&\fIgcc\fR supports long doubles (12 bytes). However, several additional | |
318 | long double math functions are necessary to use them within Perl | |
319 | (\fI{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l, | |
320 | strtold\fR). | |
321 | These are \fBnot\fR yet available with Cygwin. | |
322 | .ie n .IP "* ""\-Dusethreads""" 4 | |
323 | .el .IP "* \f(CW\-Dusethreads\fR" 4 | |
324 | .IX Item "-Dusethreads" | |
325 | \&\s-1POSIX\s0 threads are implemented in Cygwin, define this symbol if you want | |
326 | a threaded perl. | |
327 | .ie n .IP "* ""\-Duselargefiles""" 4 | |
328 | .el .IP "* \f(CW\-Duselargefiles\fR" 4 | |
329 | .IX Item "-Duselargefiles" | |
330 | Cygwin uses 64\-bit integers for internal size and position calculations, | |
331 | this will be correctly detected and defined by Configure. | |
332 | .ie n .IP "* ""\-Dmksymlinks""" 4 | |
333 | .el .IP "* \f(CW\-Dmksymlinks\fR" 4 | |
334 | .IX Item "-Dmksymlinks" | |
335 | Use this to build perl outside of the source tree. This works with Cygwin. | |
336 | Details can be found in the \fI\s-1INSTALL\s0\fR document. This is the recommended | |
337 | way to build perl from sources. | |
338 | .Sh "Suspicious Warnings on Cygwin" | |
339 | .IX Subsection "Suspicious Warnings on Cygwin" | |
340 | You may see some messages during Configure that seem suspicious. | |
341 | .IP "* \fI\fIdlsym()\fI\fR" 4 | |
342 | .IX Item "dlsym()" | |
343 | \&\fIld2\fR is needed to build dynamic libraries, but it does not exist | |
344 | when \f(CW\*(C`dlsym()\*(C'\fR checking occurs (it is not created until \f(CW\*(C`make\*(C'\fR runs). | |
345 | You will see the following message: | |
346 | .Sp | |
347 | .Vb 4 | |
348 | \& Checking whether your C<dlsym()> needs a leading underscore ... | |
349 | \& ld2: not found | |
350 | \& I can't compile and run the test program. | |
351 | \& I'm guessing that dlsym doesn't need a leading underscore. | |
352 | .Ve | |
353 | .Sp | |
354 | Since the guess is correct, this is not a problem. | |
355 | .ie n .IP "* Win9x and ""d_eofnblk""" 4 | |
356 | .el .IP "* Win9x and \f(CWd_eofnblk\fR" 4 | |
357 | .IX Item "Win9x and d_eofnblk" | |
358 | Win9x does not correctly report \f(CW\*(C`EOF\*(C'\fR with a non-blocking read on a | |
359 | closed pipe. You will see the following messages: | |
360 | .Sp | |
361 | .Vb 2 | |
362 | \& But it also returns -1 to signal EOF, so be careful! | |
363 | \& WARNING: you can't distinguish between EOF and no data! | |
364 | .Ve | |
365 | .Sp | |
366 | .Vb 3 | |
367 | \& *** WHOA THERE!!! *** | |
368 | \& The recommended value for $d_eofnblk on this machine was "define"! | |
369 | \& Keep the recommended value? [y] | |
370 | .Ve | |
371 | .Sp | |
372 | At least for consistency with WinNT, you should keep the recommended | |
373 | value. | |
374 | .IP "* Compiler/Preprocessor defines" 4 | |
375 | .IX Item "Compiler/Preprocessor defines" | |
376 | The following error occurs because of the Cygwin \f(CW\*(C`#define\*(C'\fR of | |
377 | \&\f(CW\*(C`_LONG_DOUBLE\*(C'\fR: | |
378 | .Sp | |
379 | .Vb 2 | |
380 | \& Guessing which symbols your C compiler and preprocessor define... | |
381 | \& try.c:<line#>: missing binary operator | |
382 | .Ve | |
383 | .Sp | |
384 | This failure does not seem to cause any problems. With older gcc | |
385 | versions, \*(L"parse error\*(R" is reported instead of \*(L"missing binary | |
386 | operator\*(R". | |
387 | .SH "MAKE ON CYGWIN" | |
388 | .IX Header "MAKE ON CYGWIN" | |
389 | Simply run \fImake\fR and wait: | |
390 | .PP | |
391 | .Vb 1 | |
392 | \& make 2>&1 | tee log.make | |
393 | .Ve | |
394 | .Sh "Errors on Cygwin" | |
395 | .IX Subsection "Errors on Cygwin" | |
396 | Errors like these are normal: | |
397 | .PP | |
398 | .Vb 4 | |
399 | \& ... | |
400 | \& make: [extra.pods] Error 1 (ignored) | |
401 | \& ... | |
402 | \& make: [extras.make] Error 1 (ignored) | |
403 | .Ve | |
404 | .Sh "ld2 on Cygwin" | |
405 | .IX Subsection "ld2 on Cygwin" | |
406 | During \f(CW\*(C`make\*(C'\fR, \fIld2\fR will be created and installed in your \f(CW$installbin\fR | |
407 | directory (where you said to put public executables). It does not | |
408 | wait until the \f(CW\*(C`make install\*(C'\fR process to install the \fIld2\fR script, | |
409 | this is because the remainder of the \f(CW\*(C`make\*(C'\fR refers to \fIld2\fR without | |
410 | fully specifying its path and does this from multiple subdirectories. | |
411 | The assumption is that \f(CW$installbin\fR is in your current \f(CW\*(C`PATH\*(C'\fR. If this | |
412 | is not the case \f(CW\*(C`make\*(C'\fR will fail at some point. If this happens, | |
413 | just manually copy \fIld2\fR from the source directory to somewhere in | |
414 | your \f(CW\*(C`PATH\*(C'\fR. | |
415 | .SH "TEST ON CYGWIN" | |
416 | .IX Header "TEST ON CYGWIN" | |
417 | There are two steps to running the test suite: | |
418 | .PP | |
419 | .Vb 1 | |
420 | \& make test 2>&1 | tee log.make-test | |
421 | .Ve | |
422 | .PP | |
423 | .Vb 1 | |
424 | \& cd t;./perl harness 2>&1 | tee ../log.harness | |
425 | .Ve | |
426 | .PP | |
427 | The same tests are run both times, but more information is provided when | |
428 | running as \f(CW\*(C`./perl harness\*(C'\fR. | |
429 | .PP | |
430 | Test results vary depending on your host system and your Cygwin | |
431 | configuration. If a test can pass in some Cygwin setup, it is always | |
432 | attempted and explainable test failures are documented. It is possible | |
433 | for Perl to pass all the tests, but it is more likely that some tests | |
434 | will fail for one of the reasons listed below. | |
435 | .Sh "File Permissions on Cygwin" | |
436 | .IX Subsection "File Permissions on Cygwin" | |
437 | \&\s-1UNIX\s0 file permissions are based on sets of mode bits for | |
438 | {read,write,execute} for each {user,group,other}. By default Cygwin | |
439 | only tracks the Win32 read-only attribute represented as the \s-1UNIX\s0 file | |
440 | user write bit (files are always readable, files are executable if they | |
441 | have a \fI.{com,bat,exe}\fR extension or begin with \f(CW\*(C`#!\*(C'\fR, directories are | |
442 | always readable and executable). On WinNT with the \fIntea\fR \f(CW\*(C`CYGWIN\*(C'\fR | |
443 | setting, the additional mode bits are stored as extended file attributes. | |
444 | On WinNT with the \fIntsec\fR \f(CW\*(C`CYGWIN\*(C'\fR setting, permissions use the standard | |
445 | WinNT security descriptors and access control lists. Without one of | |
446 | these options, these tests will fail (listing not updated yet): | |
447 | .PP | |
448 | .Vb 12 | |
449 | \& Failed Test List of failed | |
450 | \& ------------------------------------ | |
451 | \& io/fs.t 5, 7, 9-10 | |
452 | \& lib/anydbm.t 2 | |
453 | \& lib/db-btree.t 20 | |
454 | \& lib/db-hash.t 16 | |
455 | \& lib/db-recno.t 18 | |
456 | \& lib/gdbm.t 2 | |
457 | \& lib/ndbm.t 2 | |
458 | \& lib/odbm.t 2 | |
459 | \& lib/sdbm.t 2 | |
460 | \& op/stat.t 9, 20 (.tmp not an executable extension) | |
461 | .Ve | |
462 | .Sh "NDBM_File and ODBM_File do not work on \s-1FAT\s0 filesystems" | |
463 | .IX Subsection "NDBM_File and ODBM_File do not work on FAT filesystems" | |
464 | Do not use NDBM_File or ODBM_File on \s-1FAT\s0 filesystem. They can be | |
465 | built on a \s-1FAT\s0 filesystem, but many tests will fail: | |
466 | .PP | |
467 | .Vb 6 | |
468 | \& ../ext/NDBM_File/ndbm.t 13 3328 71 59 83.10% 1-2 4 16-71 | |
469 | \& ../ext/ODBM_File/odbm.t 255 65280 ?? ?? % ?? | |
470 | \& ../lib/AnyDBM_File.t 2 512 12 2 16.67% 1 4 | |
471 | \& ../lib/Memoize/t/errors.t 0 139 11 5 45.45% 7-11 | |
472 | \& ../lib/Memoize/t/tie_ndbm.t 13 3328 4 4 100.00% 1-4 | |
473 | \& run/fresh_perl.t 97 1 1.03% 91 | |
474 | .Ve | |
475 | .PP | |
476 | If you intend to run only on \s-1FAT\s0 (or if using AnyDBM_File on \s-1FAT\s0), | |
477 | run Configure with the \-Ui_ndbm and \-Ui_dbm options to prevent | |
478 | NDBM_File and ODBM_File being built. | |
479 | .PP | |
480 | With \s-1NTFS\s0 (and CYGWIN=ntsec), there should be no problems even if | |
481 | perl was built on \s-1FAT\s0. | |
482 | .ie n .Sh """fork()"" failures in io_* tests" | |
483 | .el .Sh "\f(CWfork()\fP failures in io_* tests" | |
484 | .IX Subsection "fork() failures in io_* tests" | |
485 | A \f(CW\*(C`fork()\*(C'\fR failure may result in the following tests failing: | |
486 | .PP | |
487 | .Vb 3 | |
488 | \& ext/IO/lib/IO/t/io_multihomed.t | |
489 | \& ext/IO/lib/IO/t/io_sock.t | |
490 | \& ext/IO/lib/IO/t/io_unix.t | |
491 | .Ve | |
492 | .PP | |
493 | See comment on fork in Miscellaneous below. | |
494 | .SH "Specific features of the Cygwin port" | |
495 | .IX Header "Specific features of the Cygwin port" | |
496 | .Sh "Script Portability on Cygwin" | |
497 | .IX Subsection "Script Portability on Cygwin" | |
498 | Cygwin does an outstanding job of providing UNIX-like semantics on top of | |
499 | Win32 systems. However, in addition to the items noted above, there are | |
500 | some differences that you should know about. This is a very brief guide | |
501 | to portability, more information can be found in the Cygwin documentation. | |
502 | .IP "* Pathnames" 4 | |
503 | .IX Item "Pathnames" | |
504 | Cygwin pathnames can be separated by forward (\fI/\fR) or backward (\fI\e\e\fR) | |
505 | slashes. They may also begin with drive letters (\fIC:\fR) or Universal | |
506 | Naming Codes (\fI//UNC\fR). \s-1DOS\s0 device names (\fIaux\fR, \fIcon\fR, \fIprn\fR, | |
507 | \&\fIcom*\fR, \fIlpt?\fR, \fInul\fR) are invalid as base filenames. However, they | |
508 | can be used in extensions (e.g., \fIhello.aux\fR). Names may contain all | |
509 | printable characters except these: | |
510 | .Sp | |
511 | .Vb 1 | |
512 | \& : * ? " < > | | |
513 | .Ve | |
514 | .Sp | |
515 | File names are case insensitive, but case preserving. A pathname that | |
516 | contains a backslash or drive letter is a Win32 pathname (and not subject | |
517 | to the translations applied to \s-1POSIX\s0 style pathnames). | |
518 | .IP "* Text/Binary" 4 | |
519 | .IX Item "Text/Binary" | |
520 | When a file is opened it is in either text or binary mode. In text mode | |
521 | a file is subject to CR/LF/Ctrl\-Z translations. With Cygwin, the default | |
522 | mode for an \f(CW\*(C`open()\*(C'\fR is determined by the mode of the mount that underlies | |
523 | the file. Perl provides a \f(CW\*(C`binmode()\*(C'\fR function to set binary mode on files | |
524 | that otherwise would be treated as text. \f(CW\*(C`sysopen()\*(C'\fR with the \f(CW\*(C`O_TEXT\*(C'\fR | |
525 | flag sets text mode on files that otherwise would be treated as binary: | |
526 | .Sp | |
527 | .Vb 1 | |
528 | \& sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) | |
529 | .Ve | |
530 | .Sp | |
531 | \&\f(CW\*(C`lseek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR and \f(CW\*(C`sysseek()\*(C'\fR only work with files opened in binary | |
532 | mode. | |
533 | .Sp | |
534 | The text/binary issue is covered at length in the Cygwin documentation. | |
535 | .IP "* PerlIO" 4 | |
536 | .IX Item "PerlIO" | |
537 | PerlIO overrides the default Cygwin Text/Binary behaviour. A file will | |
538 | always treated as binary, regardless which mode of the mount it lives on, | |
539 | just like it is in \s-1UNIX\s0. So \s-1CR/LF\s0 translation needs to be requested in | |
540 | either the \f(CW\*(C`open()\*(C'\fR call like this: | |
541 | .Sp | |
542 | .Vb 1 | |
543 | \& open(FH, ">:crlf", "out.txt"); | |
544 | .Ve | |
545 | .Sp | |
546 | which will do conversion from \s-1LF\s0 to \s-1CR/LF\s0 on the output, or in the | |
547 | environment settings (add this to your .bashrc): | |
548 | .Sp | |
549 | .Vb 1 | |
550 | \& export PERLIO=crlf | |
551 | .Ve | |
552 | .Sp | |
553 | which will pull in the crlf PerlIO layer which does \s-1LF\s0 \-> \s-1CRLF\s0 conversion | |
554 | on every output generated by perl. | |
555 | .IP "* \fI.exe\fR" 4 | |
556 | .IX Item ".exe" | |
557 | The Cygwin \f(CW\*(C`stat()\*(C'\fR, \f(CW\*(C`lstat()\*(C'\fR and \f(CW\*(C`readlink()\*(C'\fR functions make the \fI.exe\fR | |
558 | extension transparent by looking for \fIfoo.exe\fR when you ask for \fIfoo\fR | |
559 | (unless a \fIfoo\fR also exists). Cygwin does not require a \fI.exe\fR | |
560 | extension, but \fIgcc\fR adds it automatically when building a program. | |
561 | However, when accessing an executable as a normal file (e.g., \fIcp\fR | |
562 | in a makefile) the \fI.exe\fR is not transparent. The \fIinstall\fR included | |
563 | with Cygwin automatically appends a \fI.exe\fR when necessary. | |
564 | .IP "* cygwin vs. windows process ids" 4 | |
565 | .IX Item "cygwin vs. windows process ids" | |
566 | Cygwin processes have their own pid, which is different from the | |
567 | underlying windows pid. Most posix compliant Proc functions expect | |
568 | the cygwin pid, but several Win32::Process functions expect the | |
569 | winpid. E.g. \f(CW$$\fR is the cygwin pid of \fI/usr/bin/perl\fR, which is not | |
570 | the winpid. Use \f(CW\*(C`Cygwin::winpid_to_pid()\*(C'\fR and \f(CW\*(C`Cygwin::winpid_to_pid()\*(C'\fR | |
571 | to translate between them. | |
572 | .ie n .IP "* ""chown()""" 4 | |
573 | .el .IP "* \f(CWchown()\fR" 4 | |
574 | .IX Item "chown()" | |
575 | On WinNT \f(CW\*(C`chown()\*(C'\fR can change a file's user and group IDs. On Win9x \f(CW\*(C`chown()\*(C'\fR | |
576 | is a no\-op, although this is appropriate since there is no security model. | |
577 | .IP "* Miscellaneous" 4 | |
578 | .IX Item "Miscellaneous" | |
579 | File locking using the \f(CW\*(C`F_GETLK\*(C'\fR command to \f(CW\*(C`fcntl()\*(C'\fR is a stub that | |
580 | returns \f(CW\*(C`ENOSYS\*(C'\fR. | |
581 | .Sp | |
582 | Win9x can not \f(CW\*(C`rename()\*(C'\fR an open file (although WinNT can). | |
583 | .Sp | |
584 | The Cygwin \f(CW\*(C`chroot()\*(C'\fR implementation has holes (it can not restrict file | |
585 | access by native Win32 programs). | |
586 | .Sp | |
587 | Inplace editing \f(CW\*(C`perl \-i\*(C'\fR of files doesn't work without doing a backup | |
588 | of the file being edited \f(CW\*(C`perl \-i.bak\*(C'\fR because of windowish restrictions, | |
589 | therefore Perl adds the suffix \f(CW\*(C`.bak\*(C'\fR automatically if you use \f(CW\*(C`perl \-i\*(C'\fR | |
590 | without specifying a backup extension. | |
591 | .Sp | |
592 | Using \f(CW\*(C`fork()\*(C'\fR after loading multiple dlls may fail with an internal cygwin | |
593 | error like the following: | |
594 | .Sp | |
595 | .Vb 1 | |
596 | \& C:\eCYGWIN\eBIN\ePERL.EXE: *** couldn't allocate memory 0x10000(4128768) for 'C:\eCYGWIN\eLIB\ePERL5\e5.6.1\eCYGWIN-MULTI\eAUTO\eSOCKET\eSOCKET.DLL' alignment, Win32 error 8 | |
597 | .Ve | |
598 | .Sp | |
599 | .Vb 2 | |
600 | \& 200 [main] perl 377147 sync_with_child: child -395691(0xB8) died before initialization with status code 0x1 | |
601 | \& 1370 [main] perl 377147 sync_with_child: *** child state child loading dlls | |
602 | .Ve | |
603 | .Sp | |
604 | Use the rebase utility to resolve the conflicting dll addresses. The | |
605 | rebase package is included in the Cygwin netrelease. Use setup.exe from | |
606 | \&\fIhttp://www.cygwin.com/setup.exe\fR to install it and run rebaseall. | |
607 | .Sh "Prebuilt methods:" | |
608 | .IX Subsection "Prebuilt methods:" | |
609 | .ie n .IP """Cwd::cwd""" 4 | |
610 | .el .IP "\f(CWCwd::cwd\fR" 4 | |
611 | .IX Item "Cwd::cwd" | |
612 | Returns current working directory. | |
613 | .ie n .IP """Cygwin::pid_to_winpid""" 4 | |
614 | .el .IP "\f(CWCygwin::pid_to_winpid\fR" 4 | |
615 | .IX Item "Cygwin::pid_to_winpid" | |
616 | Translates a cygwin pid to the corresponding Windows pid (which may or | |
617 | may not be the same). | |
618 | .ie n .IP """Cygwin::winpid_to_pid""" 4 | |
619 | .el .IP "\f(CWCygwin::winpid_to_pid\fR" 4 | |
620 | .IX Item "Cygwin::winpid_to_pid" | |
621 | Translates a Windows pid to the corresponding cygwin pid (if any). | |
622 | .SH "INSTALL PERL ON CYGWIN" | |
623 | .IX Header "INSTALL PERL ON CYGWIN" | |
624 | This will install Perl, including \fIman\fR pages. | |
625 | .PP | |
626 | .Vb 1 | |
627 | \& make install 2>&1 | tee log.make-install | |
628 | .Ve | |
629 | .PP | |
630 | \&\s-1NOTE:\s0 If \f(CW\*(C`STDERR\*(C'\fR is redirected \f(CW\*(C`make install\*(C'\fR will \fBnot\fR prompt | |
631 | you to install \fIperl\fR into \fI/usr/bin\fR. | |
632 | .PP | |
633 | You may need to be \fIAdministrator\fR to run \f(CW\*(C`make install\*(C'\fR. If you | |
634 | are not, you must have write access to the directories in question. | |
635 | .PP | |
636 | Information on installing the Perl documentation in \s-1HTML\s0 format can be | |
637 | found in the \fI\s-1INSTALL\s0\fR document. | |
638 | .SH "MANIFEST ON CYGWIN" | |
639 | .IX Header "MANIFEST ON CYGWIN" | |
640 | These are the files in the Perl release that contain references to Cygwin. | |
641 | These very brief notes attempt to explain the reason for all conditional | |
642 | code. Hopefully, keeping this up to date will allow the Cygwin port to | |
643 | be kept as clean as possible (listing not updated yet). | |
644 | .IP "Documentation" 4 | |
645 | .IX Item "Documentation" | |
646 | .Vb 5 | |
647 | \& INSTALL README.cygwin README.win32 MANIFEST | |
648 | \& Changes Changes5.005 Changes5.004 Changes5.6 | |
649 | \& pod/perl.pod pod/perlport.pod pod/perlfaq3.pod | |
650 | \& pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod | |
651 | \& pod/perlhist.pod pod/perlmodlib.pod perl/buildtoc pod/perltoc.pod | |
652 | .Ve | |
653 | .IP "Build, Configure, Make, Install" 4 | |
654 | .IX Item "Build, Configure, Make, Install" | |
655 | .Vb 14 | |
656 | \& cygwin/Makefile.SHs | |
657 | \& cygwin/ld2.in | |
658 | \& cygwin/perlld.in | |
659 | \& ext/IPC/SysV/hints/cygwin.pl | |
660 | \& ext/NDBM_File/hints/cygwin.pl | |
661 | \& ext/ODBM_File/hints/cygwin.pl | |
662 | \& hints/cygwin.sh | |
663 | \& Configure - help finding hints from uname, | |
664 | \& shared libperl required for dynamic loading | |
665 | \& Makefile.SH - linklibperl | |
666 | \& Porting/patchls - cygwin in port list | |
667 | \& installman - man pages with :: translated to . | |
668 | \& installperl - install dll/ld2/perlld, install to pods | |
669 | \& makedepend.SH - uwinfix | |
670 | .Ve | |
671 | .IP "Tests" 4 | |
672 | .IX Item "Tests" | |
673 | .Vb 8 | |
674 | \& t/io/tell.t - binmode | |
675 | \& t/lib/b.t - ignore Cwd from os_extras | |
676 | \& t/lib/glob-basic.t - Win32 directory list access differs from read mode | |
677 | \& t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// | |
678 | \& t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk | |
679 | \& (cache manager sometimes preserves ctime of file | |
680 | \& previously created and deleted), no -u (setuid) | |
681 | \& t/lib/cygwin.t - builtin cygwin function tests | |
682 | .Ve | |
683 | .IP "Compiled Perl Source" 4 | |
684 | .IX Item "Compiled Perl Source" | |
685 | .Vb 9 | |
686 | \& EXTERN.h - __declspec(dllimport) | |
687 | \& XSUB.h - __declspec(dllexport) | |
688 | \& cygwin/cygwin.c - os_extras (getcwd, spawn, Cygwin::winpid_to_pid, | |
689 | \& Cygwin::pid_to_winpid) | |
690 | \& perl.c - os_extras | |
691 | \& perl.h - binmode | |
692 | \& doio.c - win9x can not rename a file when it is open | |
693 | \& pp_sys.c - do not define h_errno, pp_system with spawn | |
694 | \& util.c - use setenv | |
695 | .Ve | |
696 | .IP "Compiled Module Source" 4 | |
697 | .IX Item "Compiled Module Source" | |
698 | .Vb 5 | |
699 | \& ext/POSIX/POSIX.xs - tzname defined externally | |
700 | \& ext/SDBM_File/sdbm/pair.c | |
701 | \& - EXTCONST needs to be redefined from EXTERN.h | |
702 | \& ext/SDBM_File/sdbm/sdbm.c | |
703 | \& - binary open | |
704 | .Ve | |
705 | .IP "Perl Modules/Scripts" 4 | |
706 | .IX Item "Perl Modules/Scripts" | |
707 | .Vb 10 | |
708 | \& lib/Cwd.pm - hook to internal Cwd::cwd | |
709 | \& lib/ExtUtils/MakeMaker.pm | |
710 | \& - require MM_Cygwin.pm | |
711 | \& lib/ExtUtils/MM_Cygwin.pm | |
712 | \& - canonpath, cflags, manifypods, perl_archive | |
713 | \& lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1 | |
714 | \& lib/File/Spec/Unix.pm - preserve //unc | |
715 | \& lib/File/Temp.pm - no directory sticky bit | |
716 | \& lib/perl5db.pl - use stdin not /dev/tty | |
717 | \& utils/perldoc.PL - version comment | |
718 | .Ve | |
719 | .SH "BUGS ON CYGWIN" | |
720 | .IX Header "BUGS ON CYGWIN" | |
721 | Support for swapping real and effective user and group IDs is incomplete. | |
722 | On WinNT Cygwin provides \f(CW\*(C`setuid()\*(C'\fR, \f(CW\*(C`seteuid()\*(C'\fR, \f(CW\*(C`setgid()\*(C'\fR and \f(CW\*(C`setegid()\*(C'\fR. | |
723 | However, additional Cygwin calls for manipulating WinNT access tokens | |
724 | and security contexts are required. | |
725 | .SH "AUTHORS" | |
726 | .IX Header "AUTHORS" | |
727 | Charles Wilson <cwilson@ece.gatech.edu>, | |
728 | Eric Fifer <egf7@columbia.edu>, | |
729 | alexander smishlajev <als@turnhere.com>, | |
730 | Steven Morlock <newspost@morlock.net>, | |
731 | Sebastien Barre <Sebastien.Barre@utc.fr>, | |
732 | Teun Burgers <burgers@ecn.nl>, | |
733 | Gerrit P. Haase <gp@familiehaase.de>. | |
734 | .SH "HISTORY" | |
735 | .IX Header "HISTORY" | |
736 | Last updated: 2005\-02\-11 |