| 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 |