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