Commit | Line | Data |
---|---|---|
8736538c | 1 | If you read this file _as_is_, just ignore the funny characters you |
5bc802de | 2 | see. It is written in the POD format (see F<pod/perlpod.pod>) which is |
8736538c | 3 | specially designed to be readable as is. |
5aabfad6 | 4 | |
8736538c | 5 | =head1 NAME |
5aabfad6 | 6 | |
de2902a6 | 7 | perlcygwin - Perl for Cygwin |
5aabfad6 | 8 | |
8736538c | 9 | =head1 SYNOPSIS |
5aabfad6 | 10 | |
f8dbba82 GS |
11 | This document will help you configure, make, test and install Perl |
12 | on Cygwin. This document also describes features of Cygwin that will | |
13 | affect how Perl behaves at runtime. | |
5aabfad6 | 14 | |
f8dbba82 | 15 | B<NOTE:> There are pre-built Perl packages available for Cygwin and a |
37a78d01 JH |
16 | version of Perl is provided in the normal Cygwin install. If you do |
17 | not need to customize the configuration, consider using one of those | |
18 | packages. | |
5aabfad6 | 19 | |
5aabfad6 | 20 | |
a83b6f46 | 21 | =head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN |
8736538c | 22 | |
f8dbba82 | 23 | =head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) |
8736538c | 24 | |
f8dbba82 GS |
25 | The Cygwin tools are ports of the popular GNU development tools for Win32 |
26 | platforms. They run thanks to the Cygwin library which provides the UNIX | |
27 | system calls and environment these programs expect. More information | |
28 | about this project can be found at: | |
8736538c | 29 | |
adb873e1 | 30 | L<http://www.cygwin.com/> |
1cab015a | 31 | |
f8dbba82 | 32 | A recent net or commercial release of Cygwin is required. |
8736538c | 33 | |
940a0b6a | 34 | At the time this document was last updated, Cygwin 1.7.16 was current. |
8736538c | 35 | |
1cab015a | 36 | |
f8dbba82 | 37 | =head2 Cygwin Configuration |
1cab015a | 38 | |
f8dbba82 GS |
39 | While building Perl some changes may be necessary to your Cygwin setup so |
40 | that Perl builds cleanly. These changes are B<not> required for normal | |
41 | Perl usage. | |
1cab015a | 42 | |
f8dbba82 | 43 | B<NOTE:> The binaries that are built will run on all Win32 versions. |
5bc802de RU |
44 | They do not depend on your host system (WinXP/Win2K/Win7) or your |
45 | Cygwin configuration (binary/text mounts, cvgserver). | |
f703fc96 | 46 | The only dependencies come from hard-coded pathnames like F</usr/local>. |
125a13ce EF |
47 | However, your host system and Cygwin configuration will affect Perl's |
48 | runtime behavior (see L</"TEST">). | |
1cab015a | 49 | |
f8dbba82 | 50 | =over 4 |
1cab015a | 51 | |
f8dbba82 | 52 | =item * C<PATH> |
1cab015a | 53 | |
f8dbba82 | 54 | Set the C<PATH> environment variable so that Configure finds the Cygwin |
5bc802de | 55 | versions of programs. Any not-needed Windows directories should be removed or |
f8dbba82 | 56 | moved to the end of your C<PATH>. |
1cab015a | 57 | |
f8dbba82 | 58 | =item * I<nroff> |
1cab015a | 59 | |
f8dbba82 | 60 | If you do not have I<nroff> (which is part of the I<groff> package), |
b4bcd662 | 61 | Configure will B<not> prompt you to install I<man> pages. |
f8dbba82 | 62 | |
8736538c AS |
63 | =back |
64 | ||
a83b6f46 | 65 | =head1 CONFIGURE PERL ON CYGWIN |
8736538c | 66 | |
f8dbba82 GS |
67 | The default options gathered by Configure with the assistance of |
68 | F<hints/cygwin.sh> will build a Perl that supports dynamic loading | |
5bc802de | 69 | (which requires a shared F<cygperl5_16.dll>). |
f89d6eaa | 70 | |
f8dbba82 | 71 | This will run Configure and keep a record: |
8736538c | 72 | |
f8dbba82 | 73 | ./Configure 2>&1 | tee log.configure |
8736538c | 74 | |
b4bcd662 | 75 | If you are willing to accept all the defaults run Configure with B<-de>. |
f8dbba82 | 76 | However, several useful customizations are available. |
5aabfad6 | 77 | |
a83b6f46 | 78 | =head2 Stripping Perl Binaries on Cygwin |
5aabfad6 | 79 | |
f8dbba82 GS |
80 | It is possible to strip the EXEs and DLLs created by the build process. |
81 | The resulting binaries will be significantly smaller. If you want the | |
82 | binaries to be stripped, you can either add a B<-s> option when Configure | |
83 | prompts you, | |
8736538c | 84 | |
f8dbba82 | 85 | Any additional ld flags (NOT including libraries)? [none] -s |
4de3a274 | 86 | Any special flags to pass to g++ to create a dynamically loaded library? |
f8dbba82 | 87 | [none] -s |
4de3a274 | 88 | Any special flags to pass to gcc to use dynamic linking? [none] -s |
8736538c | 89 | |
f8dbba82 GS |
90 | or you can edit F<hints/cygwin.sh> and uncomment the relevant variables |
91 | near the end of the file. | |
8736538c | 92 | |
a83b6f46 | 93 | =head2 Optional Libraries for Perl on Cygwin |
8736538c | 94 | |
f8dbba82 GS |
95 | Several Perl functions and modules depend on the existence of |
96 | some optional libraries. Configure will find them if they are | |
97 | installed in one of the directories listed as being used for library | |
37a78d01 JH |
98 | searches. Pre-built packages for most of these are available from |
99 | the Cygwin installer. | |
8736538c | 100 | |
f8dbba82 | 101 | =over 4 |
8736538c | 102 | |
f8dbba82 | 103 | =item * C<-lcrypt> |
8736538c | 104 | |
125a13ce EF |
105 | The crypt package distributed with Cygwin is a Linux compatible 56-bit |
106 | DES crypt port by Corinna Vinschen. | |
107 | ||
108 | Alternatively, the crypt libraries in GNU libc have been ported to Cygwin. | |
1cab015a | 109 | |
4de3a274 | 110 | =item * C<-lgdbm_compat> (C<use GDBM_File>) |
1cab015a | 111 | |
a0457be1 | 112 | GDBM is available for Cygwin. |
125a13ce | 113 | |
be238d52 JH |
114 | NOTE: The GDBM library only works on NTFS partitions. |
115 | ||
f8dbba82 | 116 | =item * C<-ldb> (C<use DB_File>) |
1cab015a | 117 | |
be238d52 | 118 | BerkeleyDB is available for Cygwin. |
1cab015a | 119 | |
5bc802de | 120 | NOTE: The BerkeleyDB library only completely works on NTFS partitions. |
125a13ce | 121 | |
15414d2b | 122 | =item * C<cygserver> (C<use IPC::SysV>) |
f8dbba82 | 123 | |
6b49d266 EF |
124 | A port of SysV IPC is available for Cygwin. |
125 | ||
126 | NOTE: This has B<not> been extensively tested. In particular, | |
b4bcd662 GS |
127 | C<d_semctl_semun> is undefined because it fails a Configure test |
128 | and on Win9x the I<shm*()> functions seem to hang. It also creates | |
129 | a compile time dependency because F<perl.h> includes F<<sys/ipc.h>> | |
130 | and F<<sys/sem.h>> (which will be required in the future when compiling | |
be238d52 | 131 | CPAN modules). CURRENTLY NOT SUPPORTED! |
47f4f673 GH |
132 | |
133 | =item * C<-lutil> | |
134 | ||
4de3a274 | 135 | Included with the standard Cygwin netrelease is the inetutils package |
47f4f673 | 136 | which includes libutil.a. |
1cab015a EF |
137 | |
138 | =back | |
139 | ||
a83b6f46 | 140 | =head2 Configure-time Options for Perl on Cygwin |
f8dbba82 | 141 | |
0a110db2 GS |
142 | The F<INSTALL> document describes several Configure-time options. Some of |
143 | these will work with Cygwin, others are not yet possible. Also, some of | |
144 | these are experimental. You can either select an option when Configure | |
145 | prompts you or you can define (undefine) symbols on the command line. | |
f8dbba82 GS |
146 | |
147 | =over 4 | |
148 | ||
149 | =item * C<-Uusedl> | |
150 | ||
0a110db2 | 151 | Undefining this symbol forces Perl to be compiled statically. |
f8dbba82 | 152 | |
5bc802de | 153 | =item * C<-Dusemymalloc> |
1cab015a | 154 | |
5bc802de RU |
155 | By default Perl does not use the C<malloc()> included with the Perl source, |
156 | because it was slower and not entirely thread-safe. If you want to force | |
157 | Perl to build with the old -Dusemymalloc define this. | |
1cab015a | 158 | |
33bf3ba1 RGS |
159 | =item * C<-Uuseperlio> |
160 | ||
bbebedce YST |
161 | Undefining this symbol disables the PerlIO abstraction. PerlIO is now the |
162 | default; it is not recommended to disable PerlIO. | |
33bf3ba1 | 163 | |
6b49d266 | 164 | =item * C<-Dusemultiplicity> |
1cab015a | 165 | |
f8dbba82 | 166 | Multiplicity is required when embedding Perl in a C program and using |
5bc802de RU |
167 | more than one interpreter instance. This is only required when you build |
168 | a not-threaded perl with C<-Uuseithreads>. | |
1cab015a | 169 | |
5bc802de | 170 | =item * C<-Uuse64bitint> |
1cab015a | 171 | |
5bc802de RU |
172 | By default Perl uses 64 bit integers. If you want to use smaller 32 bit |
173 | integers, define this symbol. | |
1cab015a | 174 | |
f8dbba82 | 175 | =item * C<-Duselongdouble> |
1cab015a | 176 | |
f8dbba82 GS |
177 | I<gcc> supports long doubles (12 bytes). However, several additional |
178 | long double math functions are necessary to use them within Perl | |
4de3a274 | 179 | (I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l, |
5cb3728c | 180 | strtold>). |
5bc802de | 181 | These are B<not> yet available with newlib, the Cygwin libc. |
1cab015a | 182 | |
5bc802de | 183 | =item * C<-Uuseithreads> |
1cab015a | 184 | |
5bc802de | 185 | Define this symbol if you want not-threaded faster perl. |
f8dbba82 GS |
186 | |
187 | =item * C<-Duselargefiles> | |
188 | ||
4de3a274 | 189 | Cygwin uses 64-bit integers for internal size and position calculations, |
be238d52 | 190 | this will be correctly detected and defined by Configure. |
1cab015a | 191 | |
a0457be1 GH |
192 | =item * C<-Dmksymlinks> |
193 | ||
5bc802de RU |
194 | Use this to build perl outside of the source tree. Details can be |
195 | found in the F<INSTALL> document. This is the recommended way to | |
196 | build perl from sources. | |
a0457be1 | 197 | |
1cab015a EF |
198 | =back |
199 | ||
a83b6f46 | 200 | =head2 Suspicious Warnings on Cygwin |
1cab015a | 201 | |
f8dbba82 | 202 | You may see some messages during Configure that seem suspicious. |
8736538c | 203 | |
f8dbba82 | 204 | =over 4 |
8736538c | 205 | |
b4bcd662 | 206 | =item * Win9x and C<d_eofnblk> |
5db16f6a EF |
207 | |
208 | Win9x does not correctly report C<EOF> with a non-blocking read on a | |
209 | closed pipe. You will see the following messages: | |
210 | ||
211 | But it also returns -1 to signal EOF, so be careful! | |
212 | WARNING: you can't distinguish between EOF and no data! | |
213 | ||
214 | *** WHOA THERE!!! *** | |
215 | The recommended value for $d_eofnblk on this machine was "define"! | |
216 | Keep the recommended value? [y] | |
217 | ||
218 | At least for consistency with WinNT, you should keep the recommended | |
219 | value. | |
220 | ||
0a110db2 GS |
221 | =item * Compiler/Preprocessor defines |
222 | ||
223 | The following error occurs because of the Cygwin C<#define> of | |
224 | C<_LONG_DOUBLE>: | |
225 | ||
226 | Guessing which symbols your C compiler and preprocessor define... | |
fb652349 | 227 | try.c:<line#>: missing binary operator |
0a110db2 | 228 | |
fb652349 YST |
229 | This failure does not seem to cause any problems. With older gcc |
230 | versions, "parse error" is reported instead of "missing binary | |
231 | operator". | |
0a110db2 | 232 | |
5db16f6a EF |
233 | =back |
234 | ||
a83b6f46 | 235 | =head1 MAKE ON CYGWIN |
5aabfad6 | 236 | |
b4bcd662 | 237 | Simply run I<make> and wait: |
f8dbba82 GS |
238 | |
239 | make 2>&1 | tee log.make | |
240 | ||
a83b6f46 | 241 | =head1 TEST ON CYGWIN |
f8dbba82 GS |
242 | |
243 | There are two steps to running the test suite: | |
244 | ||
245 | make test 2>&1 | tee log.make-test | |
246 | ||
15414d2b | 247 | cd t; ./perl harness 2>&1 | tee ../log.harness |
f8dbba82 GS |
248 | |
249 | The same tests are run both times, but more information is provided when | |
b432a672 | 250 | running as C<./perl harness>. |
5aabfad6 | 251 | |
f8dbba82 | 252 | Test results vary depending on your host system and your Cygwin |
b4bcd662 GS |
253 | configuration. If a test can pass in some Cygwin setup, it is always |
254 | attempted and explainable test failures are documented. It is possible | |
125a13ce EF |
255 | for Perl to pass all the tests, but it is more likely that some tests |
256 | will fail for one of the reasons listed below. | |
1cab015a | 257 | |
a83b6f46 | 258 | =head2 File Permissions on Cygwin |
1cab015a | 259 | |
f8dbba82 | 260 | UNIX file permissions are based on sets of mode bits for |
b4bcd662 GS |
261 | {read,write,execute} for each {user,group,other}. By default Cygwin |
262 | only tracks the Win32 read-only attribute represented as the UNIX file | |
263 | user write bit (files are always readable, files are executable if they | |
264 | have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are | |
265 | always readable and executable). On WinNT with the I<ntea> C<CYGWIN> | |
266 | setting, the additional mode bits are stored as extended file attributes. | |
4de3a274 | 267 | On WinNT with the default I<ntsec> C<CYGWIN> setting, permissions use the |
15414d2b | 268 | standard WinNT security descriptors and access control lists. Without one of |
47f4f673 | 269 | these options, these tests will fail (listing not updated yet): |
1cab015a | 270 | |
f8dbba82 GS |
271 | Failed Test List of failed |
272 | ------------------------------------ | |
273 | io/fs.t 5, 7, 9-10 | |
274 | lib/anydbm.t 2 | |
275 | lib/db-btree.t 20 | |
276 | lib/db-hash.t 16 | |
277 | lib/db-recno.t 18 | |
278 | lib/gdbm.t 2 | |
f8dbba82 GS |
279 | lib/ndbm.t 2 |
280 | lib/odbm.t 2 | |
281 | lib/sdbm.t 2 | |
282 | op/stat.t 9, 20 (.tmp not an executable extension) | |
1cab015a | 283 | |
fb652349 YST |
284 | =head2 NDBM_File and ODBM_File do not work on FAT filesystems |
285 | ||
286 | Do not use NDBM_File or ODBM_File on FAT filesystem. They can be | |
287 | built on a FAT filesystem, but many tests will fail: | |
288 | ||
289 | ../ext/NDBM_File/ndbm.t 13 3328 71 59 83.10% 1-2 4 16-71 | |
290 | ../ext/ODBM_File/odbm.t 255 65280 ?? ?? % ?? | |
291 | ../lib/AnyDBM_File.t 2 512 12 2 16.67% 1 4 | |
292 | ../lib/Memoize/t/errors.t 0 139 11 5 45.45% 7-11 | |
293 | ../lib/Memoize/t/tie_ndbm.t 13 3328 4 4 100.00% 1-4 | |
294 | run/fresh_perl.t 97 1 1.03% 91 | |
295 | ||
296 | If you intend to run only on FAT (or if using AnyDBM_File on FAT), | |
297 | run Configure with the -Ui_ndbm and -Ui_dbm options to prevent | |
298 | NDBM_File and ODBM_File being built. | |
299 | ||
15414d2b | 300 | With NTFS (and no CYGWIN=nontsec), there should be no problems even if |
fb652349 YST |
301 | perl was built on FAT. |
302 | ||
538204d5 | 303 | =head2 C<fork()> failures in io_* tests |
0be9fa5d | 304 | |
538204d5 | 305 | A C<fork()> failure may result in the following tests failing: |
fb652349 YST |
306 | |
307 | ext/IO/lib/IO/t/io_multihomed.t | |
308 | ext/IO/lib/IO/t/io_sock.t | |
309 | ext/IO/lib/IO/t/io_unix.t | |
310 | ||
fd161f2c | 311 | See comment on fork in L</Miscellaneous> below. |
0be9fa5d | 312 | |
49fd6edc YST |
313 | =head1 Specific features of the Cygwin port |
314 | ||
a83b6f46 | 315 | =head2 Script Portability on Cygwin |
1cab015a | 316 | |
b4bcd662 GS |
317 | Cygwin does an outstanding job of providing UNIX-like semantics on top of |
318 | Win32 systems. However, in addition to the items noted above, there are | |
319 | some differences that you should know about. This is a very brief guide | |
320 | to portability, more information can be found in the Cygwin documentation. | |
1cab015a | 321 | |
f8dbba82 | 322 | =over 4 |
1cab015a | 323 | |
f8dbba82 | 324 | =item * Pathnames |
1cab015a | 325 | |
5bc802de RU |
326 | Cygwin pathnames are separated by forward (F</>) slashes, Universal |
327 | Naming Codes (F<//UNC>) are also supported Since cygwin-1.7 non-POSIX | |
940a0b6a | 328 | pathnames are discouraged. Names may contain all printable |
5bc802de | 329 | characters. |
1cab015a | 330 | |
125a13ce | 331 | File names are case insensitive, but case preserving. A pathname that |
5bc802de RU |
332 | contains a backslash or drive letter is a Win32 pathname, and not |
333 | subject to the translations applied to POSIX style pathnames, but | |
334 | cygwin will warn you, so better convert them to POSIX. | |
f8dbba82 | 335 | |
4de3a274 | 336 | For conversion we have C<Cygwin::win_to_posix_path()> and |
15414d2b RU |
337 | C<Cygwin::posix_to_win_path()>. |
338 | ||
5bc802de | 339 | Since cygwin-1.7 pathnames are UTF-8 encoded. |
15414d2b | 340 | |
f8dbba82 GS |
341 | =item * Text/Binary |
342 | ||
95ccf9d5 | 343 | Since cygwin-1.7 textmounts are deprecated and strongly discouraged. |
5bc802de | 344 | |
f8dbba82 | 345 | When a file is opened it is in either text or binary mode. In text mode |
5db16f6a | 346 | a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default |
538204d5 | 347 | mode for an C<open()> is determined by the mode of the mount that underlies |
5fc51037 | 348 | the file. See L</Cygwin::is_binmount>(). Perl provides a C<binmode()> function |
7b7dcf5a RGS |
349 | to set binary mode on files that otherwise would be treated as text. |
350 | C<sysopen()> with the C<O_TEXT> flag sets text mode on files that otherwise | |
351 | would be treated as binary: | |
5db16f6a EF |
352 | |
353 | sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) | |
f8dbba82 | 354 | |
538204d5 GH |
355 | C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary |
356 | mode. | |
5db16f6a EF |
357 | |
358 | The text/binary issue is covered at length in the Cygwin documentation. | |
f8dbba82 | 359 | |
538204d5 GH |
360 | =item * PerlIO |
361 | ||
4de3a274 RGS |
362 | PerlIO overrides the default Cygwin Text/Binary behaviour. A file will |
363 | always be treated as binary, regardless of the mode of the mount it lives | |
364 | on, just like it is in UNIX. So CR/LF translation needs to be requested in | |
538204d5 GH |
365 | either the C<open()> call like this: |
366 | ||
367 | open(FH, ">:crlf", "out.txt"); | |
368 | ||
4de3a274 | 369 | which will do conversion from LF to CR/LF on the output, or in the |
538204d5 GH |
370 | environment settings (add this to your .bashrc): |
371 | ||
372 | export PERLIO=crlf | |
373 | ||
4de3a274 | 374 | which will pull in the crlf PerlIO layer which does LF -> CRLF conversion |
538204d5 GH |
375 | on every output generated by perl. |
376 | ||
f8dbba82 GS |
377 | =item * F<.exe> |
378 | ||
538204d5 | 379 | The Cygwin C<stat()>, C<lstat()> and C<readlink()> functions make the F<.exe> |
497711e7 GS |
380 | extension transparent by looking for F<foo.exe> when you ask for F<foo> |
381 | (unless a F<foo> also exists). Cygwin does not require a F<.exe> | |
382 | extension, but I<gcc> adds it automatically when building a program. | |
383 | However, when accessing an executable as a normal file (e.g., I<cp> | |
5bc802de RU |
384 | in a makefile) the F<.exe> is not transparent. The I<install> program |
385 | included with Cygwin automatically appends a F<.exe> when necessary. | |
f8dbba82 | 386 | |
e3988807 | 387 | =item * Cygwin vs. Windows process ids |
75e109ec RGS |
388 | |
389 | Cygwin processes have their own pid, which is different from the | |
390 | underlying windows pid. Most posix compliant Proc functions expect | |
391 | the cygwin pid, but several Win32::Process functions expect the | |
392 | winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not | |
f15c31c1 | 393 | the winpid. Use C<Cygwin::pid_to_winpid()> and C<Cygwin::winpid_to_pid()> |
75e109ec RGS |
394 | to translate between them. |
395 | ||
e3988807 JH |
396 | =item * Cygwin vs. Windows errors |
397 | ||
398 | Under Cygwin, $^E is the same as $!. When using L<Win32 API Functions|Win32>, | |
399 | use C<Win32::GetLastError()> to get the last Windows error. | |
400 | ||
5bc802de RU |
401 | =item * rebase errors on fork or system |
402 | ||
403 | Using C<fork()> or C<system()> out to another perl after loading multiple dlls | |
404 | may result on a DLL baseaddress conflict. The internal cygwin error | |
405 | looks like like the following: | |
406 | ||
407 | 0 [main] perl 8916 child_info_fork::abort: data segment start: parent | |
408 | (0xC1A000) != child(0xA6A000) | |
409 | ||
410 | or: | |
411 | ||
1dcc3c19 DG |
412 | 183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error - unable to remap |
413 | C:\cygwin\bin\cygsvn_subr-1-0.dll to same address as parent(0x6FB30000) != 0x6FE60000 | |
5bc802de RU |
414 | 46 [main] perl 3488 fork: child 3588 - died waiting for dll loading, errno11 |
415 | ||
416 | See L<http://cygwin.com/faq/faq-nochunks.html#faq.using.fixing-fork-failures> | |
417 | It helps if not too many DLLs are loaded in memory so the available address space is larger, | |
418 | e.g. stopping the MS Internet Explorer might help. | |
419 | ||
420 | Use the perlrebase or rebase utilities to resolve the conflicting dll addresses. | |
421 | The rebase package is included in the Cygwin setup. Use F<setup.exe> | |
422 | from L<http://www.cygwin.com/setup.exe> to install it. | |
423 | ||
424 | 1. kill all perl processes and run C<perlrebase> or | |
425 | ||
426 | 2. kill all cygwin processes and services, start dash from cmd.exe and run C<rebaseall>. | |
427 | ||
538204d5 | 428 | =item * C<chown()> |
f8dbba82 | 429 | |
538204d5 | 430 | On WinNT C<chown()> can change a file's user and group IDs. On Win9x C<chown()> |
b4bcd662 | 431 | is a no-op, although this is appropriate since there is no security model. |
f8dbba82 GS |
432 | |
433 | =item * Miscellaneous | |
434 | ||
538204d5 | 435 | File locking using the C<F_GETLK> command to C<fcntl()> is a stub that |
f8dbba82 GS |
436 | returns C<ENOSYS>. |
437 | ||
538204d5 | 438 | Win9x can not C<rename()> an open file (although WinNT can). |
1cab015a | 439 | |
538204d5 | 440 | The Cygwin C<chroot()> implementation has holes (it can not restrict file |
125a13ce EF |
441 | access by native Win32 programs). |
442 | ||
4de3a274 | 443 | Inplace editing C<perl -i> of files doesn't work without doing a backup |
c030f24b | 444 | of the file being edited C<perl -i.bak> because of windowish restrictions, |
4de3a274 | 445 | therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i> |
27008580 | 446 | without specifying a backup extension. |
818c4caa | 447 | |
1cab015a EF |
448 | =back |
449 | ||
49fd6edc YST |
450 | =head2 Prebuilt methods: |
451 | ||
452 | =over 4 | |
453 | ||
454 | =item C<Cwd::cwd> | |
455 | ||
15414d2b | 456 | Returns the current working directory. |
49fd6edc YST |
457 | |
458 | =item C<Cygwin::pid_to_winpid> | |
459 | ||
460 | Translates a cygwin pid to the corresponding Windows pid (which may or | |
461 | may not be the same). | |
462 | ||
463 | =item C<Cygwin::winpid_to_pid> | |
464 | ||
465 | Translates a Windows pid to the corresponding cygwin pid (if any). | |
466 | ||
15414d2b RU |
467 | =item C<Cygwin::win_to_posix_path> |
468 | ||
469 | Translates a Windows path to the corresponding cygwin path respecting | |
470 | the current mount points. With a second non-null argument returns an | |
471 | absolute path. Double-byte characters will not be translated. | |
472 | ||
473 | =item C<Cygwin::posix_to_win_path> | |
474 | ||
475 | Translates a cygwin path to the corresponding cygwin path respecting | |
476 | the current mount points. With a second non-null argument returns an | |
477 | absolute path. Double-byte characters will not be translated. | |
478 | ||
a25ce5f3 RU |
479 | =item C<Cygwin::mount_table()> |
480 | ||
481 | Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts]. | |
482 | ||
483 | perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}' | |
484 | /bin c:\cygwin\bin system binmode,cygexec | |
485 | /usr/bin c:\cygwin\bin system binmode | |
486 | /usr/lib c:\cygwin\lib system binmode | |
487 | / c:\cygwin system binmode | |
488 | /cygdrive/c c: system binmode,noumount | |
489 | /cygdrive/d d: system binmode,noumount | |
4de3a274 | 490 | /cygdrive/e e: system binmode,noumount |
a25ce5f3 RU |
491 | |
492 | =item C<Cygwin::mount_flags> | |
493 | ||
494 | Returns the mount type and flags for a specified mount point. | |
4de3a274 | 495 | A comma-separated string of mntent->mnt_type (always |
a25ce5f3 RU |
496 | "system" or "user"), then the mntent->mnt_opts, where |
497 | the first is always "binmode" or "textmode". | |
498 | ||
499 | system|user,binmode|textmode,exec,cygexec,cygdrive,mixed, | |
500 | notexec,managed,nosuid,devfs,proc,noumount | |
501 | ||
74dc058d JH |
502 | If the argument is "/cygdrive", then just the volume mount settings, |
503 | and the cygdrive mount prefix are returned. | |
a25ce5f3 RU |
504 | |
505 | User mounts override system mounts. | |
506 | ||
507 | $ perl -e 'print Cygwin::mount_flags "/usr/bin"' | |
508 | system,binmode,cygexec | |
509 | $ perl -e 'print Cygwin::mount_flags "/cygdrive"' | |
74dc058d | 510 | binmode,cygdrive,/cygdrive |
a25ce5f3 | 511 | |
15414d2b RU |
512 | =item C<Cygwin::is_binmount> |
513 | ||
514 | Returns true if the given cygwin path is binary mounted, false if the | |
515 | path is mounted in textmode. | |
516 | ||
286f8194 RU |
517 | =item C<Cygwin::sync_winenv> |
518 | ||
519 | Cygwin does not initialize all original Win32 environment variables. | |
520 | See the bottom of this page L<http://cygwin.com/cygwin-ug-net/setup-env.html> | |
521 | for "Restricted Win32 environment". | |
522 | ||
523 | Certain Win32 programs called from cygwin programs might need some environment | |
524 | variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%. | |
525 | Call Cygwin::sync_winenv() to copy all Win32 environment variables to your | |
526 | process and note that cygwin will warn on every encounter of non-POSIX paths. | |
527 | ||
49fd6edc YST |
528 | =back |
529 | ||
a83b6f46 | 530 | =head1 INSTALL PERL ON CYGWIN |
f8dbba82 | 531 | |
b4bcd662 | 532 | This will install Perl, including I<man> pages. |
f8dbba82 | 533 | |
a0457be1 | 534 | make install 2>&1 | tee log.make-install |
5db16f6a | 535 | |
b432a672 | 536 | NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt |
5db16f6a | 537 | you to install I<perl> into F</usr/bin>. |
1cab015a | 538 | |
b432a672 | 539 | You may need to be I<Administrator> to run C<make install>. If you |
f8dbba82 | 540 | are not, you must have write access to the directories in question. |
1cab015a | 541 | |
f8dbba82 GS |
542 | Information on installing the Perl documentation in HTML format can be |
543 | found in the F<INSTALL> document. | |
1cab015a | 544 | |
a83b6f46 | 545 | =head1 MANIFEST ON CYGWIN |
1cab015a | 546 | |
f8dbba82 GS |
547 | These are the files in the Perl release that contain references to Cygwin. |
548 | These very brief notes attempt to explain the reason for all conditional | |
549 | code. Hopefully, keeping this up to date will allow the Cygwin port to | |
4de3a274 | 550 | be kept as clean as possible. |
1cab015a | 551 | |
f8dbba82 | 552 | =over 4 |
1cab015a | 553 | |
f8dbba82 | 554 | =item Documentation |
1cab015a | 555 | |
47dafe4d | 556 | INSTALL README.cygwin README.win32 MANIFEST |
47dafe4d EF |
557 | pod/perl.pod pod/perlport.pod pod/perlfaq3.pod |
558 | pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod | |
4de3a274 RGS |
559 | pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod |
560 | pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod | |
561 | pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod | |
0aef0fe5 | 562 | pod/perltoc.pod Porting/Glossary pod/perlgit.pod |
4de3a274 | 563 | Porting/checkAUTHORS.pl |
2a6dc374 FR |
564 | dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes |
565 | ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes | |
566 | ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes | |
339aa067 | 567 | ext/Time-HiRes/Changes ext/Win32API-File/Changes |
2a6dc374 | 568 | lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes lib/ExtUtils/NOTES |
a4678072 | 569 | lib/ExtUtils/PATCHING lib/ExtUtils/README |
2a6dc374 FR |
570 | lib/Net/Ping/Changes lib/Test/Harness/Changes |
571 | lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README README.symbian | |
572 | symbian/TODO | |
1cab015a | 573 | |
f8dbba82 | 574 | =item Build, Configure, Make, Install |
1cab015a | 575 | |
f8dbba82 | 576 | cygwin/Makefile.SHs |
f8dbba82 GS |
577 | ext/IPC/SysV/hints/cygwin.pl |
578 | ext/NDBM_File/hints/cygwin.pl | |
579 | ext/ODBM_File/hints/cygwin.pl | |
580 | hints/cygwin.sh | |
f8dbba82 GS |
581 | Configure - help finding hints from uname, |
582 | shared libperl required for dynamic loading | |
4de3a274 RGS |
583 | Makefile.SH Cross/Makefile-cross-SH |
584 | - linklibperl | |
6b49d266 | 585 | Porting/patchls - cygwin in port list |
f8dbba82 | 586 | installman - man pages with :: translated to . |
4de3a274 | 587 | installperl - install dll, install to 'pods' |
6b49d266 | 588 | makedepend.SH - uwinfix |
4de3a274 RGS |
589 | regen_lib.pl - file permissions |
590 | ||
591 | NetWare/Makefile | |
592 | plan9/mkfile | |
593 | symbian/sanity.pl symbian/sisify.pl | |
594 | hints/uwin.sh | |
595 | vms/descrip_mms.template | |
596 | win32/Makefile win32/makefile.mk | |
1cab015a | 597 | |
f8dbba82 | 598 | =item Tests |
1cab015a | 599 | |
4de3a274 RGS |
600 | t/io/fs.t - no file mode checks if not ntsec |
601 | skip rename() check when not check_case:relaxed | |
f8dbba82 | 602 | t/io/tell.t - binmode |
4de3a274 RGS |
603 | t/lib/cygwin.t - builtin cygwin function tests |
604 | t/op/groups.t - basegroup has ID = 0 | |
5db16f6a EF |
605 | t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// |
606 | t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk | |
607 | (cache manager sometimes preserves ctime of file | |
608 | previously created and deleted), no -u (setuid) | |
4de3a274 RGS |
609 | t/op/taint.t - can't use empty path under Cygwin Perl |
610 | t/op/time.t - no tzset() | |
f8dbba82 GS |
611 | |
612 | =item Compiled Perl Source | |
613 | ||
f8dbba82 GS |
614 | EXTERN.h - __declspec(dllimport) |
615 | XSUB.h - __declspec(dllexport) | |
a25ce5f3 | 616 | cygwin/cygwin.c - os_extras (getcwd, spawn, and several Cygwin:: functions) |
4de3a274 | 617 | perl.c - os_extras, -i.bak |
f8dbba82 | 618 | perl.h - binmode |
6b49d266 | 619 | doio.c - win9x can not rename a file when it is open |
4de3a274 | 620 | pp_sys.c - do not define h_errno, init _pwent_struct.pw_comment |
47dafe4d | 621 | util.c - use setenv |
4de3a274 RGS |
622 | util.h - PERL_FILE_IS_ABSOLUTE macro |
623 | pp.c - Comment about Posix vs IEEE math under Cygwin | |
624 | perlio.c - CR/LF mode | |
625 | perliol.c - Comment about EXTCONST under Cygwin | |
f8dbba82 GS |
626 | |
627 | =item Compiled Module Source | |
628 | ||
dc539f3d | 629 | ext/Compress-Raw-Zlib/Makefile.PL |
4de3a274 | 630 | - Can't install via CPAN shell under Cygwin |
dc539f3d | 631 | ext/Compress-Raw-Zlib/zlib-src/zutil.h |
4de3a274 RGS |
632 | - Cygwin is Unix-like and has vsnprintf |
633 | ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under Cygwin | |
f8dbba82 GS |
634 | ext/POSIX/POSIX.xs - tzname defined externally |
635 | ext/SDBM_File/sdbm/pair.c | |
636 | - EXTCONST needs to be redefined from EXTERN.h | |
637 | ext/SDBM_File/sdbm/sdbm.c | |
638 | - binary open | |
4de3a274 RGS |
639 | ext/Sys/Syslog/Syslog.xs |
640 | - Cygwin has syslog.h | |
641 | ext/Sys/Syslog/win32/compile.pl | |
642 | - Convert paths to Windows paths | |
40d04ec4 | 643 | ext/Time-HiRes/HiRes.xs |
4de3a274 | 644 | - Various timers not available |
40d04ec4 | 645 | ext/Time-HiRes/Makefile.PL |
4de3a274 RGS |
646 | - Find w32api/windows.h |
647 | ext/Win32/Makefile.PL - Use various libraries under Cygwin | |
648 | ext/Win32/Win32.xs - Child dir and child env under Cygwin | |
4282a474 | 649 | ext/Win32API-File/File.xs |
4de3a274 RGS |
650 | - _open_osfhandle not implemented under Cygwin |
651 | ext/Win32CORE/Win32CORE.c | |
652 | - __declspec(dllexport) | |
f8dbba82 GS |
653 | |
654 | =item Perl Modules/Scripts | |
655 | ||
4de3a274 | 656 | ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under Cygwin |
12fc04c9 | 657 | ext/Digest-SHA/bin/shasum |
4de3a274 RGS |
658 | - Use binary mode under Cygwin |
659 | ext/Sys/Syslog/win32/Win32.pm | |
660 | - Convert paths to Windows paths | |
40d04ec4 | 661 | ext/Time-HiRes/HiRes.pm |
4de3a274 | 662 | - Comment about various timers not available |
4282a474 | 663 | ext/Win32API-File/File.pm |
4de3a274 RGS |
664 | - _open_osfhandle not implemented under Cygwin |
665 | ext/Win32CORE/Win32CORE.pm | |
666 | - History of Win32CORE under Cygwin | |
6b49d266 | 667 | lib/Cwd.pm - hook to internal Cwd::cwd |
4de3a274 RGS |
668 | lib/ExtUtils/CBuilder/Platform/cygwin.pm |
669 | - use gcc for ld, and link to libperl.dll.a | |
670 | lib/ExtUtils/CBuilder.pm | |
671 | - Cygwin is Unix-like | |
672 | lib/ExtUtils/Install.pm - Install and rename issues under Cygwin | |
673 | lib/ExtUtils/MM.pm - OS classifications | |
674 | lib/ExtUtils/MM_Any.pm - Example for Cygwin | |
f8dbba82 GS |
675 | lib/ExtUtils/MakeMaker.pm |
676 | - require MM_Cygwin.pm | |
677 | lib/ExtUtils/MM_Cygwin.pm | |
678 | - canonpath, cflags, manifypods, perl_archive | |
4de3a274 | 679 | lib/File/Fetch.pm - Comment about quotes using a Cygwin example |
497711e7 | 680 | lib/File/Find.pm - on remote drives stat() always sets st_nlink to 1 |
a25ce5f3 | 681 | lib/File/Spec/Cygwin.pm - case_tolerant |
6b49d266 | 682 | lib/File/Spec/Unix.pm - preserve //unc |
4de3a274 RGS |
683 | lib/File/Spec/Win32.pm - References a message on cygwin.com |
684 | lib/File/Spec.pm - Pulls in lib/File/Spec/Cygwin.pm | |
5d129265 | 685 | lib/File/Temp.pm - no directory sticky bit |
4de3a274 RGS |
686 | lib/Module/CoreList.pm - List of all module files and versions |
687 | lib/Net/Domain.pm - No domainname command under Cygwin | |
688 | lib/Net/Netrc.pm - Bypass using stat() under Cygwin | |
689 | lib/Net/Ping.pm - ECONREFUSED is EAGAIN under Cygwin | |
690 | lib/Pod/Find.pm - Set 'pods' dir | |
691 | lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man | |
692 | lib/Pod/Perldoc.pm - Use 'less' pager, and use .exe extension | |
693 | lib/Term/ANSIColor.pm - Cygwin terminal info | |
6b49d266 | 694 | lib/perl5db.pl - use stdin not /dev/tty |
4de3a274 RGS |
695 | utils/perlbug.PL - Add CYGWIN environment variable to report |
696 | ||
697 | =item Perl Module Tests | |
698 | ||
2a6dc374 | 699 | dist/Cwd/t/cwd.t |
32592041 | 700 | ext/Compress-Zlib/t/14gzopen.t |
4de3a274 RGS |
701 | ext/DB_File/t/db-btree.t |
702 | ext/DB_File/t/db-hash.t | |
703 | ext/DB_File/t/db-recno.t | |
704 | ext/DynaLoader/t/DynaLoader.t | |
005c4f26 | 705 | ext/File-Glob/t/basic.t |
4de3a274 RGS |
706 | ext/GDBM_File/t/gdbm.t |
707 | ext/POSIX/t/sysconf.t | |
708 | ext/POSIX/t/time.t | |
709 | ext/SDBM_File/t/sdbm.t | |
710 | ext/Sys/Syslog/t/syslog.t | |
40d04ec4 | 711 | ext/Time-HiRes/t/HiRes.t |
4de3a274 | 712 | ext/Win32/t/Unicode.t |
4282a474 | 713 | ext/Win32API-File/t/file.t |
4de3a274 RGS |
714 | ext/Win32CORE/t/win32core.t |
715 | lib/AnyDBM_File.t | |
716 | lib/Archive/Extract/t/01_Archive-Extract.t | |
717 | lib/Archive/Tar/t/02_methods.t | |
4de3a274 RGS |
718 | lib/ExtUtils/t/Embed.t |
719 | lib/ExtUtils/t/eu_command.t | |
720 | lib/ExtUtils/t/MM_Cygwin.t | |
721 | lib/ExtUtils/t/MM_Unix.t | |
722 | lib/File/Compare.t | |
723 | lib/File/Copy.t | |
724 | lib/File/Find/t/find.t | |
725 | lib/File/Path.t | |
726 | lib/File/Spec/t/crossplatform.t | |
727 | lib/File/Spec/t/Spec.t | |
4de3a274 RGS |
728 | lib/Net/hostent.t |
729 | lib/Net/Ping/t/110_icmp_inst.t | |
730 | lib/Net/Ping/t/500_ping_icmp.t | |
731 | lib/Net/t/netrc.t | |
732 | lib/Pod/Simple/t/perlcyg.pod | |
733 | lib/Pod/Simple/t/perlcygo.txt | |
734 | lib/Pod/Simple/t/perlfaq.pod | |
735 | lib/Pod/Simple/t/perlfaqo.txt | |
736 | lib/User/grent.t | |
737 | lib/User/pwent.t | |
1cab015a EF |
738 | |
739 | =back | |
f89d6eaa | 740 | |
a83b6f46 | 741 | =head1 BUGS ON CYGWIN |
f8dbba82 | 742 | |
125a13ce | 743 | Support for swapping real and effective user and group IDs is incomplete. |
538204d5 | 744 | On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>. |
125a13ce EF |
745 | However, additional Cygwin calls for manipulating WinNT access tokens |
746 | and security contexts are required. | |
747 | ||
f8dbba82 GS |
748 | =head1 AUTHORS |
749 | ||
b4bcd662 | 750 | Charles Wilson <cwilson@ece.gatech.edu>, |
47dafe4d | 751 | Eric Fifer <egf7@columbia.edu>, |
b4bcd662 GS |
752 | alexander smishlajev <als@turnhere.com>, |
753 | Steven Morlock <newspost@morlock.net>, | |
754 | Sebastien Barre <Sebastien.Barre@utc.fr>, | |
a0457be1 | 755 | Teun Burgers <burgers@ecn.nl>, |
a25ce5f3 RU |
756 | Gerrit P. Haase <gp@familiehaase.de>, |
757 | Reini Urban <rurban@cpan.org>, | |
4de3a274 RGS |
758 | Jan Dubois <jand@activestate.com>, |
759 | Jerry D. Hedden <jdhedden@cpan.org>. | |
f8dbba82 GS |
760 | |
761 | =head1 HISTORY | |
762 | ||
5bc802de | 763 | Last updated: 2012-02-08 |