[14544] | 1 | If you read this file _as_is_, just ignore the funny characters you |
---|
| 2 | see. It is written in the POD format (see pod/perlpod.pod) which is |
---|
| 3 | specially designed to be readable as is. |
---|
| 4 | |
---|
| 5 | =head1 NAME |
---|
| 6 | |
---|
| 7 | README.cygwin - Perl for Cygwin |
---|
| 8 | |
---|
| 9 | =head1 SYNOPSIS |
---|
| 10 | |
---|
| 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. |
---|
| 14 | |
---|
| 15 | B<NOTE:> There are pre-built Perl packages available for Cygwin and a |
---|
| 16 | version of Perl is provided on the Cygwin CD. If you have no need to |
---|
| 17 | customize the configuration, consider using one of these packages: |
---|
| 18 | |
---|
| 19 | http://cygutils.netpedia.net/ |
---|
| 20 | |
---|
| 21 | =head1 PREREQUISITES |
---|
| 22 | |
---|
| 23 | =head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) |
---|
| 24 | |
---|
| 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: |
---|
| 29 | |
---|
| 30 | http://sourceware.cygnus.com/cygwin/ |
---|
| 31 | |
---|
| 32 | A recent net or commercial release of Cygwin is required. |
---|
| 33 | |
---|
| 34 | At the time this document was written, the port required recent |
---|
| 35 | development snapshots that were expected to stabilize early in 2000 and |
---|
| 36 | be released to the net as B21 and commercially as v1.1. |
---|
| 37 | |
---|
| 38 | B<NOTE:> At this point, minimal effort has been made to provide |
---|
| 39 | compatibility with old (beta) Cygwin releases. The focus has been to |
---|
| 40 | provide a high quality release and not worry about working around old |
---|
| 41 | Cygwin bugs. If you wish to use Perl with Cygwin B20.1 or earlier, |
---|
| 42 | consider using either perl5.005_03 or perl5.005_62, which are available |
---|
| 43 | in source and binary form at C<http://cygutils.netpedia.net/> or on the |
---|
| 44 | Cygwin CD. If there is significant demand, a patch kit can be developed |
---|
| 45 | to port back to earlier Cygwin versions. |
---|
| 46 | |
---|
| 47 | =head2 Compiler |
---|
| 48 | |
---|
| 49 | A recent net or commercial release of I<gcc> is required. |
---|
| 50 | |
---|
| 51 | At the time this document was written, I<gcc-2.95.2> was current and |
---|
| 52 | could be downloaded from: |
---|
| 53 | |
---|
| 54 | ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/cygwin/gcc-2.95.2/ |
---|
| 55 | |
---|
| 56 | =head2 Cygwin Configuration |
---|
| 57 | |
---|
| 58 | While building Perl some changes may be necessary to your Cygwin setup so |
---|
| 59 | that Perl builds cleanly. These changes are B<not> required for normal |
---|
| 60 | Perl usage. |
---|
| 61 | |
---|
| 62 | B<NOTE:> The binaries that are built will run on all Win32 versions. |
---|
| 63 | They do not depend on your host system (Win9x, WinNT) or your Cygwin |
---|
| 64 | configuration (I<ntea>, I<ntsec>, binary/text mounts). The only |
---|
| 65 | dependencies come from hardcoded pathnames like C</usr/local>. However, |
---|
| 66 | your host system and Cygwin configuration will affect Perl's runtime |
---|
| 67 | behavior (see L</"TEST">). Some regression tests may fail in different |
---|
| 68 | ways depending on your setup. For now, the test suite does not skip |
---|
| 69 | tests that do not make sense given a particular setup. If a test can |
---|
| 70 | pass in some Cygwin setup, it is left in and explainable test failures |
---|
| 71 | are documented. |
---|
| 72 | |
---|
| 73 | =over 4 |
---|
| 74 | |
---|
| 75 | =item * C<PATH> |
---|
| 76 | |
---|
| 77 | Set the C<PATH> environment variable so that Configure finds the Cygwin |
---|
| 78 | versions of programs. Any Windows directories should be removed or |
---|
| 79 | moved to the end of your C<PATH>. |
---|
| 80 | |
---|
| 81 | =item * F</bin/cat.exe> |
---|
| 82 | |
---|
| 83 | There should be an instance of I<cat> in F</bin> (or F</usr/bin>). |
---|
| 84 | Configure tests C<#!/bin/cat> and if it is not found, you will see |
---|
| 85 | the error: |
---|
| 86 | |
---|
| 87 | Configure: ./try: No such file or directory |
---|
| 88 | |
---|
| 89 | =item * F</usr/bin> |
---|
| 90 | |
---|
| 91 | If you do not have a F</usr/bin> directory, Configure will B<not> prompt |
---|
| 92 | you to install I<perl> into F</usr/bin>. |
---|
| 93 | |
---|
| 94 | =item * I<nroff> |
---|
| 95 | |
---|
| 96 | If you do not have I<nroff> (which is part of the I<groff> package), |
---|
| 97 | Configure will B<not> prompt you to install man pages. |
---|
| 98 | |
---|
| 99 | =item * Permissions |
---|
| 100 | |
---|
| 101 | On WinNT with either the I<ntea> or I<ntsec> C<CYGWIN> settings, directory |
---|
| 102 | and file permissions may not be set correctly. Since the build process |
---|
| 103 | creates files and directories, to be safe you may want to run a `C<chmod |
---|
| 104 | -R +w *>' on the entire Perl source tree. |
---|
| 105 | |
---|
| 106 | Also, it is a well known WinNT "feature" that files created by a login |
---|
| 107 | that is a member of the I<Administrators> group will be owned by the |
---|
| 108 | I<Administrators> group. Depending on your umask, you may find that you |
---|
| 109 | can not write to files that you just created (because you are no longer |
---|
| 110 | the owner). When using the I<ntsec> C<CYGWIN> setting, this is not an |
---|
| 111 | issue because it "corrects" the ownership to what you would expect on |
---|
| 112 | a UNIX system. |
---|
| 113 | |
---|
| 114 | =back |
---|
| 115 | |
---|
| 116 | =head1 CONFIGURE |
---|
| 117 | |
---|
| 118 | The default options gathered by Configure with the assistance of |
---|
| 119 | F<hints/cygwin.sh> will build a Perl that supports dynamic loading |
---|
| 120 | (which requires a shared F<libperl.dll>). |
---|
| 121 | |
---|
| 122 | This will run Configure and keep a record: |
---|
| 123 | |
---|
| 124 | ./Configure 2>&1 | tee log.configure |
---|
| 125 | |
---|
| 126 | If you are willing to accept all the defaults add a B<-d> option. |
---|
| 127 | However, several useful customizations are available. |
---|
| 128 | |
---|
| 129 | =head2 Strip Binaries |
---|
| 130 | |
---|
| 131 | It is possible to strip the EXEs and DLLs created by the build process. |
---|
| 132 | The resulting binaries will be significantly smaller. If you want the |
---|
| 133 | binaries to be stripped, you can either add a B<-s> option when Configure |
---|
| 134 | prompts you, |
---|
| 135 | |
---|
| 136 | Any additional ld flags (NOT including libraries)? [none] -s |
---|
| 137 | Any special flags to pass to gcc to use dynamic linking? [none] -s |
---|
| 138 | Any special flags to pass to ld2 to create a dynamically loaded library? |
---|
| 139 | [none] -s |
---|
| 140 | |
---|
| 141 | or you can edit F<hints/cygwin.sh> and uncomment the relevant variables |
---|
| 142 | near the end of the file. |
---|
| 143 | |
---|
| 144 | =head2 Optional Libraries |
---|
| 145 | |
---|
| 146 | Several Perl functions and modules depend on the existence of |
---|
| 147 | some optional libraries. Configure will find them if they are |
---|
| 148 | installed in one of the directories listed as being used for library |
---|
| 149 | searches. Pre-built packages for most of these are available at |
---|
| 150 | C<http://cygutils.netpedia.net/>. |
---|
| 151 | |
---|
| 152 | =over 4 |
---|
| 153 | |
---|
| 154 | =item * C<-lcrypt> |
---|
| 155 | |
---|
| 156 | The crypt libraries in GNU libc have been ported to Cygwin. |
---|
| 157 | |
---|
| 158 | The DES based Ultra Fast Crypt port was done by Alexey Truhan: |
---|
| 159 | |
---|
| 160 | http://dome.weeg.uiowa.edu/pub/domestic/sos/cw32crypt-dist-0.tgz |
---|
| 161 | |
---|
| 162 | NOTE: There are various export restrictions on DES implementations, |
---|
| 163 | see the glibc README for more details. |
---|
| 164 | |
---|
| 165 | The MD5 port was done by Andy Piper: |
---|
| 166 | |
---|
| 167 | http://dome.weeg.uiowa.edu/pub/domestic/sos/libcrypt.tgz |
---|
| 168 | |
---|
| 169 | More information can also be found at: |
---|
| 170 | |
---|
| 171 | http://miracle.geol.msu.ru/sos/ |
---|
| 172 | |
---|
| 173 | =item * C<-lgdbm> (C<use GDBM_File>) |
---|
| 174 | |
---|
| 175 | GDBM is available for Cygwin. GDBM's ndbm/dbm compatibility feature |
---|
| 176 | also makes C<NDBM_File> and C<ODBM_File> possible (although they add |
---|
| 177 | little extra value). |
---|
| 178 | |
---|
| 179 | =item * C<-ldb> (C<use DB_File>) |
---|
| 180 | |
---|
| 181 | BerkeleyDB is available for Cygwin. Some details can be found in |
---|
| 182 | F<ext/DB_File/DB_File.pm>. |
---|
| 183 | |
---|
| 184 | =item * C<-lcygipc> (C<use IPC::SysV>) |
---|
| 185 | |
---|
| 186 | A port of SysV IPC is available for Cygwin. |
---|
| 187 | |
---|
| 188 | NOTE: This has B<not> been extensively tested. In particular, |
---|
| 189 | C<d_semctl_semun> is undefined because it fails a configure test and on |
---|
| 190 | Win9x the shm*() functions seem to hang. |
---|
| 191 | |
---|
| 192 | =back |
---|
| 193 | |
---|
| 194 | =head2 Configure-time Options |
---|
| 195 | |
---|
| 196 | The F<INSTALL> document describes several Configure-time options. Some of |
---|
| 197 | these will work with Cygwin, others are not yet possible. Also, some of |
---|
| 198 | these are experimental. You can either select an option when Configure |
---|
| 199 | prompts you or you can define (undefine) symbols on the command line. |
---|
| 200 | |
---|
| 201 | =over 4 |
---|
| 202 | |
---|
| 203 | =item * C<-Uusedl> |
---|
| 204 | |
---|
| 205 | Undefining this symbol forces Perl to be compiled statically. |
---|
| 206 | |
---|
| 207 | =item * C<-Uusemymalloc> |
---|
| 208 | |
---|
| 209 | By default Perl uses the malloc() included with the Perl source. If you |
---|
| 210 | want to force Perl to build with the system malloc() undefine this symbol. |
---|
| 211 | |
---|
| 212 | =item * C<-Dusemultiplicity> |
---|
| 213 | |
---|
| 214 | Multiplicity is required when embedding Perl in a C program and using |
---|
| 215 | more than one interpreter instance. This works with the Cygwin port. |
---|
| 216 | |
---|
| 217 | =item * C<-Duseperlio> |
---|
| 218 | |
---|
| 219 | The PerlIO abstraction works with the Cygwin port. |
---|
| 220 | |
---|
| 221 | =item * C<-Duse64bitint> |
---|
| 222 | |
---|
| 223 | I<gcc> supports 64-bit integers. However, several additional long long |
---|
| 224 | functions are necessary to use them within Perl (I<{strtol,strtoul}l>). |
---|
| 225 | These are B<not> yet available with Cygwin. |
---|
| 226 | |
---|
| 227 | =item * C<-Duselongdouble> |
---|
| 228 | |
---|
| 229 | I<gcc> supports long doubles (12 bytes). However, several additional |
---|
| 230 | long double math functions are necessary to use them within Perl |
---|
| 231 | (I<{atan2,cos,exp,floor,fmod,frexp,log,modf,pow,sin,sqrt}l,strtold>). |
---|
| 232 | These are B<not> yet available with Cygwin. |
---|
| 233 | |
---|
| 234 | =item * C<-Dusethreads> |
---|
| 235 | |
---|
| 236 | POSIX threads are B<not> yet implemented in Cygwin. |
---|
| 237 | |
---|
| 238 | =item * C<-Duselargefiles> |
---|
| 239 | |
---|
| 240 | Although Win32 supports large files, Cygwin currently uses 32-bit integers |
---|
| 241 | for internal size and position calculations. |
---|
| 242 | |
---|
| 243 | =back |
---|
| 244 | |
---|
| 245 | =head2 Suspicious Warnings |
---|
| 246 | |
---|
| 247 | You may see some messages during Configure that seem suspicious. |
---|
| 248 | |
---|
| 249 | =over 4 |
---|
| 250 | |
---|
| 251 | =item * Whoa There |
---|
| 252 | |
---|
| 253 | Cygwin does not yet implement chroot(), setegid() or seteuid() |
---|
| 254 | functionality, but has stub functions that return C<ENOSYS>. You will |
---|
| 255 | see a message when Configure detects that its guess conflicts with the |
---|
| 256 | hint file. |
---|
| 257 | |
---|
| 258 | *** WHOA THERE!!! *** |
---|
| 259 | The recommended value for $d_chroot on this machine was "undef"! |
---|
| 260 | Keep the recommended value? [y] |
---|
| 261 | |
---|
| 262 | You should keep the recommended value. |
---|
| 263 | |
---|
| 264 | =item * dlsym |
---|
| 265 | |
---|
| 266 | I<ld2> is needed to build dynamic libraries, but it does not exist |
---|
| 267 | when dlsym() checking occurs (it is not created until `C<make>' runs). |
---|
| 268 | You will see the following message: |
---|
| 269 | |
---|
| 270 | Checking whether your dlsym() needs a leading underscore ... |
---|
| 271 | I can't compile and run the test program. |
---|
| 272 | I'm guessing that dlsym doesn't need a leading underscore. |
---|
| 273 | |
---|
| 274 | Since the guess is correct, this is not a problem. |
---|
| 275 | |
---|
| 276 | =item * Win9x and d_eofnblk |
---|
| 277 | |
---|
| 278 | Win9x does not correctly report C<EOF> with a non-blocking read on a |
---|
| 279 | closed pipe. You will see the following messages: |
---|
| 280 | |
---|
| 281 | But it also returns -1 to signal EOF, so be careful! |
---|
| 282 | WARNING: you can't distinguish between EOF and no data! |
---|
| 283 | |
---|
| 284 | *** WHOA THERE!!! *** |
---|
| 285 | The recommended value for $d_eofnblk on this machine was "define"! |
---|
| 286 | Keep the recommended value? [y] |
---|
| 287 | |
---|
| 288 | At least for consistency with WinNT, you should keep the recommended |
---|
| 289 | value. |
---|
| 290 | |
---|
| 291 | =item * Checking how std your stdio is... |
---|
| 292 | |
---|
| 293 | Configure reports: |
---|
| 294 | |
---|
| 295 | Your stdio doesn't appear very std. |
---|
| 296 | |
---|
| 297 | This is correct. |
---|
| 298 | |
---|
| 299 | =item * Compiler/Preprocessor defines |
---|
| 300 | |
---|
| 301 | The following error occurs because of the Cygwin C<#define> of |
---|
| 302 | C<_LONG_DOUBLE>: |
---|
| 303 | |
---|
| 304 | Guessing which symbols your C compiler and preprocessor define... |
---|
| 305 | try.c:3847: parse error |
---|
| 306 | |
---|
| 307 | This failure does not seem to cause any problems. |
---|
| 308 | |
---|
| 309 | =back |
---|
| 310 | |
---|
| 311 | =head1 MAKE |
---|
| 312 | |
---|
| 313 | Simply run make and wait: |
---|
| 314 | |
---|
| 315 | make 2>&1 | tee log.make |
---|
| 316 | |
---|
| 317 | =head2 Warnings |
---|
| 318 | |
---|
| 319 | Warnings like these are normal: |
---|
| 320 | |
---|
| 321 | warning: overriding commands for target <file> |
---|
| 322 | warning: ignoring old commands for target <file> |
---|
| 323 | |
---|
| 324 | Warning: no export definition file provided |
---|
| 325 | dllwrap will create one, but may not be what you want |
---|
| 326 | |
---|
| 327 | =head2 ld2 |
---|
| 328 | |
---|
| 329 | During `C<make>', I<ld2> will be created and installed in your $installbin |
---|
| 330 | directory (where you said to put public executables). It does not |
---|
| 331 | wait until the `C<make install>' process to install the I<ld2> script, |
---|
| 332 | this is because the remainder of the `C<make>' refers to I<ld2> without |
---|
| 333 | fully specifying its path and does this from multiple subdirectories. |
---|
| 334 | The assumption is that $installbin is in your current C<PATH>. If this |
---|
| 335 | is not the case or if you do not have an I<install> program, `C<make>' |
---|
| 336 | will fail at some point. If this happens, just manually copy I<ld2> |
---|
| 337 | from the source directory to someplace in your C<PATH>. |
---|
| 338 | |
---|
| 339 | =head1 TEST |
---|
| 340 | |
---|
| 341 | There are two steps to running the test suite: |
---|
| 342 | |
---|
| 343 | make test 2>&1 | tee log.make-test |
---|
| 344 | |
---|
| 345 | cd t;./perl harness 2>&1 | tee ../log.harness |
---|
| 346 | |
---|
| 347 | The same tests are run both times, but more information is provided when |
---|
| 348 | running as `C<./perl harness>'. |
---|
| 349 | |
---|
| 350 | Test results vary depending on your host system and your Cygwin |
---|
| 351 | configuration. It is possible that Cygwin will pass all the tests, |
---|
| 352 | but it is more likely that some tests will fail for one of these reasons. |
---|
| 353 | |
---|
| 354 | =head2 File Permissions |
---|
| 355 | |
---|
| 356 | UNIX file permissions are based on sets of mode bits for |
---|
| 357 | {read,write,execute} for each {user,group,other}. By default Cygwin only |
---|
| 358 | tracks the Win32 readonly attribute represented as the UNIX file user |
---|
| 359 | write bit (files are always readable, files are executable if they have |
---|
| 360 | a F<.{com,bat,exe}> extension or begin with C<#!>, directories are always |
---|
| 361 | readable and executable). On WinNT with the I<ntea> C<CYGWIN> setting, |
---|
| 362 | the remaining mode bits are stored as extended attributes. On WinNT |
---|
| 363 | with the I<ntsec> C<CYGWIN> setting, permissions use the standard WinNT |
---|
| 364 | security descriptors and access control lists. Without one of these |
---|
| 365 | options, these tests will fail: |
---|
| 366 | |
---|
| 367 | Failed Test List of failed |
---|
| 368 | ------------------------------------ |
---|
| 369 | io/fs.t 5, 7, 9-10 |
---|
| 370 | lib/anydbm.t 2 |
---|
| 371 | lib/db-btree.t 20 |
---|
| 372 | lib/db-hash.t 16 |
---|
| 373 | lib/db-recno.t 18 |
---|
| 374 | lib/gdbm.t 2 |
---|
| 375 | lib/ndbm.t 2 |
---|
| 376 | lib/odbm.t 2 |
---|
| 377 | lib/sdbm.t 2 |
---|
| 378 | op/stat.t 9, 20 (.tmp not an executable extension) |
---|
| 379 | |
---|
| 380 | =head2 Hard Links |
---|
| 381 | |
---|
| 382 | FAT partitions do not support hard links (whereas NTFS does), in which |
---|
| 383 | case Cygwin implements link() by copying the file. These tests will fail: |
---|
| 384 | |
---|
| 385 | Failed Test List of failed |
---|
| 386 | ------------------------------------ |
---|
| 387 | io/fs.t 4 |
---|
| 388 | op/stat.t 3 |
---|
| 389 | |
---|
| 390 | =head2 Filetime Granularity |
---|
| 391 | |
---|
| 392 | On FAT partitions the filetime granularity is 2 seconds. The following |
---|
| 393 | test will fail: |
---|
| 394 | |
---|
| 395 | Failed Test List of failed |
---|
| 396 | ------------------------------------ |
---|
| 397 | io/fs.t 18 |
---|
| 398 | |
---|
| 399 | =head2 Tainting Checks |
---|
| 400 | |
---|
| 401 | When Perl is running in taint mode, C<$ENV{PATH}> is considered tainted |
---|
| 402 | and not used, so DLLs not in the default system directories will not |
---|
| 403 | be found. While the tests are running you will see warnings popup from |
---|
| 404 | the system with messages like: |
---|
| 405 | |
---|
| 406 | Win9x |
---|
| 407 | Error Starting Program |
---|
| 408 | A required .DLL file, CYGWIN1.DLL, was not found |
---|
| 409 | |
---|
| 410 | WinNT |
---|
| 411 | perl.exe or sh.exe - Unable to Locate DLL |
---|
| 412 | The dynamic link library cygwin1.dll could not be found in the |
---|
| 413 | specified path ... |
---|
| 414 | |
---|
| 415 | Just click OK and ignore them. When running `C<make test>', 2 popups |
---|
| 416 | occur. During `C<./perl harness>', 4 popups occur. Also, these tests |
---|
| 417 | will fail: |
---|
| 418 | |
---|
| 419 | Failed Test List of failed |
---|
| 420 | ------------------------------------ |
---|
| 421 | op/taint.t 1, 3, 31, 37 |
---|
| 422 | |
---|
| 423 | Alternatively, you can copy F<cygwin1.dll> into one of the Windows system |
---|
| 424 | directories (although, this is B<not> recommended). |
---|
| 425 | |
---|
| 426 | =head2 /etc/group |
---|
| 427 | |
---|
| 428 | Cygwin does not require F</etc/group>, in which case the F<op/grent.t> |
---|
| 429 | test will be skipped. The check performed by F<op/grent.t> expects to |
---|
| 430 | see entries that use the members field, otherwise this test will fail: |
---|
| 431 | |
---|
| 432 | Failed Test List of failed |
---|
| 433 | ------------------------------------ |
---|
| 434 | op/grent.t 1 |
---|
| 435 | |
---|
| 436 | =head2 Unexplained Failures |
---|
| 437 | |
---|
| 438 | Any additional tests that fail are likely due to bugs in Cygwin or the |
---|
| 439 | optional libraries. It is expected that by the time of the next net |
---|
| 440 | release most of these will be solved so they are not described here. |
---|
| 441 | |
---|
| 442 | =head2 Script Portability |
---|
| 443 | |
---|
| 444 | Cygwin does an outstanding job of providing UNIX-like semantics on |
---|
| 445 | top of Win32 systems. However, in addition to the items noted above, |
---|
| 446 | there are some differences that you should know about. This is only a |
---|
| 447 | very brief guide to portability, more information can be found in the |
---|
| 448 | Cygwin documentation. |
---|
| 449 | |
---|
| 450 | =over 4 |
---|
| 451 | |
---|
| 452 | =item * Pathnames |
---|
| 453 | |
---|
| 454 | Cygwin pathnames can be separated by forward (F</>) or backward (F<\>) |
---|
| 455 | slashes. They may also begin with drive letters (F<C:>) or Universal |
---|
| 456 | Naming Codes (F<//UNC>). DOS device names (F<aux>, F<con>, F<prn>, |
---|
| 457 | F<com*>, F<lpt?>) are invalid as base filenames. However, they can be |
---|
| 458 | used in extensions (e.g., F<hello.aux>). Names may not contain these |
---|
| 459 | characters: |
---|
| 460 | |
---|
| 461 | : * ? " < > | |
---|
| 462 | |
---|
| 463 | File names are case insensitive, but case preserving. With the I<mixed> |
---|
| 464 | C<CYGWIN> setting, file names are mixed-case (although, directory names |
---|
| 465 | remain case insensitive). |
---|
| 466 | |
---|
| 467 | The I<mixed> setting is only available with the "coolview" version of |
---|
| 468 | F<cygwin1.dll> provided by Sergey Okhapkin at: |
---|
| 469 | |
---|
| 470 | ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Okhapkin_Sergey/ |
---|
| 471 | |
---|
| 472 | =item * Text/Binary |
---|
| 473 | |
---|
| 474 | When a file is opened it is in either text or binary mode. In text mode |
---|
| 475 | a file is subject to CR/LF/Ctrl-Z translations. With Cygwin, the default |
---|
| 476 | mode for an open() is determined by the mode of the mount that underlies |
---|
| 477 | the file. Perl provides a binmode() function to set binary mode on files |
---|
| 478 | that otherwise would be treated as text. sysopen() with the C<O_TEXT> |
---|
| 479 | flag sets text mode on files that otherwise would be treated as binary: |
---|
| 480 | |
---|
| 481 | sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT) |
---|
| 482 | |
---|
| 483 | lseek(), tell() and sysseek() only work with files opened in binary mode. |
---|
| 484 | |
---|
| 485 | The text/binary issue is covered at length in the Cygwin documentation. |
---|
| 486 | |
---|
| 487 | =item * F<.exe> |
---|
| 488 | |
---|
| 489 | The Cygwin stat() makes the F<.exe> extension transparent by looking for |
---|
| 490 | a F<foo.exe> when you ask for F<foo> (unless a F<foo> also exists). |
---|
| 491 | Cygwin does not require a F<.exe> extension, but I<gcc> adds it |
---|
| 492 | automatically when building a program. However, when accessing an |
---|
| 493 | executable as a normal file (e.g., I<install> or I<cp> in a makefile) |
---|
| 494 | the F<.exe> is not transparent. |
---|
| 495 | |
---|
| 496 | NOTE: There is a version of I<install> that understands the F<.exe> |
---|
| 497 | semantics, it can be found at: |
---|
| 498 | |
---|
| 499 | ftp://ftp.franken.de/pub/win32/develop/gnuwin32/cygwin/porters/Humblet_Pierre_A/ |
---|
| 500 | |
---|
| 501 | =item * chown() |
---|
| 502 | |
---|
| 503 | On WinNT with the I<ntsec> C<CYGWIN> setting, chown() can change a file's |
---|
| 504 | user and group IDs. In all other configurations chown() is a no-op, |
---|
| 505 | although this is appropriate on Win9x since there is no security model. |
---|
| 506 | |
---|
| 507 | =item * Miscellaneous |
---|
| 508 | |
---|
| 509 | File locking using the C<F_GETLK> command to fcntl() is a stub that |
---|
| 510 | returns C<ENOSYS>. |
---|
| 511 | |
---|
| 512 | Win9x can not rename() an open file (although WinNT can). |
---|
| 513 | |
---|
| 514 | =back |
---|
| 515 | |
---|
| 516 | =head1 INSTALL |
---|
| 517 | |
---|
| 518 | This will install Perl, including man pages. |
---|
| 519 | |
---|
| 520 | make install | tee log.make-install |
---|
| 521 | |
---|
| 522 | NOTE: If C<STDERR> is redirected `C<make install>' will B<not> prompt |
---|
| 523 | you to install I<perl> into F</usr/bin>. |
---|
| 524 | |
---|
| 525 | You may need to be I<Administrator> to run `C<make install>'. If you |
---|
| 526 | are not, you must have write access to the directories in question. |
---|
| 527 | |
---|
| 528 | Information on installing the Perl documentation in HTML format can be |
---|
| 529 | found in the F<INSTALL> document. |
---|
| 530 | |
---|
| 531 | =head1 MANIFEST |
---|
| 532 | |
---|
| 533 | These are the files in the Perl release that contain references to Cygwin. |
---|
| 534 | These very brief notes attempt to explain the reason for all conditional |
---|
| 535 | code. Hopefully, keeping this up to date will allow the Cygwin port to |
---|
| 536 | be kept as clean as possible. |
---|
| 537 | |
---|
| 538 | =over 4 |
---|
| 539 | |
---|
| 540 | =item Documentation |
---|
| 541 | |
---|
| 542 | INSTALL README.cygwin |
---|
| 543 | Changes Changes5.005 Changes5.004 |
---|
| 544 | AUTHORS MAINTAIN MANIFEST README.win32 |
---|
| 545 | pod/perl.pod pod/perlfaq3.pod pod/perlhist.pod pod/perlmodlib.pod |
---|
| 546 | pod/perlport.pod pod/perltoc.pod pod/perl5004delta.pod |
---|
| 547 | |
---|
| 548 | =item Build, Configure, Make, Install |
---|
| 549 | |
---|
| 550 | cygwin/Makefile.SHs |
---|
| 551 | cygwin/ld2.in |
---|
| 552 | cygwin/perlld.in |
---|
| 553 | ext/IPC/SysV/hints/cygwin.pl |
---|
| 554 | ext/NDBM_File/hints/cygwin.pl |
---|
| 555 | ext/ODBM_File/hints/cygwin.pl |
---|
| 556 | hints/cygwin.sh |
---|
| 557 | Configure - help finding hints from uname, |
---|
| 558 | shared libperl required for dynamic loading |
---|
| 559 | Makefile.SH - linklibperl |
---|
| 560 | Porting/patchls - cygwin in port list |
---|
| 561 | installman - man pages with :: translated to . |
---|
| 562 | installperl - install dll/ld2/perlld, install to pods |
---|
| 563 | makedepend.SH - uwinfix |
---|
| 564 | |
---|
| 565 | =item Tests |
---|
| 566 | |
---|
| 567 | t/io/tell.t - binmode |
---|
| 568 | t/lib/glob-basic.t - Win32 directory list access differs from read mode |
---|
| 569 | t/op/magic.t - $^X/symlink WORKAROUND, s/.exe// |
---|
| 570 | t/op/stat.t - no /dev, skip Win32 ftCreationTime quirk |
---|
| 571 | (cache manager sometimes preserves ctime of file |
---|
| 572 | previously created and deleted), no -u (setuid) |
---|
| 573 | |
---|
| 574 | =item Compiled Perl Source |
---|
| 575 | |
---|
| 576 | EXTERN.h - __declspec(dllimport) |
---|
| 577 | XSUB.h - __declspec(dllexport) |
---|
| 578 | cygwin/cygwin.c - os_extras (getcwd) |
---|
| 579 | perl.c - os_extras |
---|
| 580 | perl.h - binmode |
---|
| 581 | doio.c - win9x can not rename a file when it is open |
---|
| 582 | pp_sys.c - do not define h_errno |
---|
| 583 | mg.c - environ WORKAROUND |
---|
| 584 | unixish.h - environ WORKAROUND |
---|
| 585 | util.c - environ WORKAROUND |
---|
| 586 | |
---|
| 587 | =item Compiled Module Source |
---|
| 588 | |
---|
| 589 | ext/POSIX/POSIX.xs - tzname defined externally |
---|
| 590 | ext/SDBM_File/sdbm/pair.c |
---|
| 591 | - EXTCONST needs to be redefined from EXTERN.h |
---|
| 592 | ext/SDBM_File/sdbm/sdbm.c |
---|
| 593 | - binary open |
---|
| 594 | |
---|
| 595 | =item Perl Modules/Scripts |
---|
| 596 | |
---|
| 597 | lib/Cwd.pm - hook to internal Cwd::cwd |
---|
| 598 | lib/ExtUtils/MakeMaker.pm |
---|
| 599 | - require MM_Cygwin.pm |
---|
| 600 | lib/ExtUtils/MM_Cygwin.pm |
---|
| 601 | - canonpath, cflags, manifypods, perl_archive |
---|
| 602 | lib/File/Spec/Unix.pm - preserve //unc |
---|
| 603 | lib/perl5db.pl - use stdin not /dev/tty |
---|
| 604 | utils/perlcc.PL - DynaLoader.a in compile, -DUSEIMPORTLIB |
---|
| 605 | utils/perldoc.PL - version comment |
---|
| 606 | |
---|
| 607 | =back |
---|
| 608 | |
---|
| 609 | =head1 BUGS |
---|
| 610 | |
---|
| 611 | Upon each start, I<make> warns that a rule for F<perlmain.o> is overridden |
---|
| 612 | (but there seems to be no better solution than adding an explicit define). |
---|
| 613 | |
---|
| 614 | `C<make clean>' does not remove library F<.def> and F<.exe.stackdump> |
---|
| 615 | files. |
---|
| 616 | |
---|
| 617 | The I<ld2> script contains references to the source directory. You should |
---|
| 618 | change these to C</usr/local/bin> (or whatever) after install. |
---|
| 619 | |
---|
| 620 | =head1 AUTHORS |
---|
| 621 | |
---|
| 622 | Charles Wilson E<lt>cwilson@ece.gatech.eduE<gt>, |
---|
| 623 | Eric Fifer E<lt>efifer@sanwaint.comE<gt>, |
---|
| 624 | alexander smishlajev E<lt>als@turnhere.comE<gt>, |
---|
| 625 | Steven Morlock E<lt>newspost@morlock.netE<gt>, |
---|
| 626 | Sebastien Barre E<lt>Sebastien.Barre@utc.frE<gt>, |
---|
| 627 | Teun Burgers E<lt>burgers@ecn.nlE<gt>. |
---|
| 628 | |
---|
| 629 | =head1 HISTORY |
---|
| 630 | |
---|
| 631 | Last updated: 1 March 2000 |
---|