diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 7719221d9..b6b33687d 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,8 @@ +2009-02-11 Corinna Vinschen + + * faq-programming.xml: Revamp (mostely) for Cygwin 1.7. + * faq-what.xml: Ditto. + 2009-02-11 Corinna Vinschen * Makefile.in (FAQ_SOURCES): Define FAQ sources. diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml index 9e6fee6de..948c59d52 100644 --- a/winsup/doc/faq-programming.xml +++ b/winsup/doc/faq-programming.xml @@ -62,11 +62,10 @@ would be difficult. Where is Objective C? -Objective C is not distributed with the Cygwin version of gcc, and there -are no plans to do so. The gcc package maintainer had difficulty -building it, and once built there were problems using it. It appears -that there is only minimal support for the Objective C front-end in the -main GCC distribution, anyway. +Objective C hasn't been distributed with the Cygwin version of gcc +for a long time. For several reason Cygwin was stuck with gcc version 3.4.4. +Fortunately the latest gcc maintainer is quite busy to create a working +gcc 4.x release which also comes with an Objective C package. @@ -87,22 +86,27 @@ to enable cygexec for all executables in that folder; you will also need to exclude non-cygwin executables with the -x switch. Enabling cygexec causes cygwin executables to talk directly to one another, which increases the command-line limit. To enable cygexec for /bin and -/usr/bin, you can use these commands in a batch file: +/usr/bin, you can add or change these entries in /etc/fstab: -mount -X -b -f c:\cygwin\bin /bin -mount -X -b -f c:\cygwin\bin /usr/bin -mount -x -b -f c:\cygwin\bin\tclsh84.exe /usr/bin/tclsh84.exe -mount -x -b -f c:\cygwin\bin\tclsh84.exe /bin/tclsh84.exe -mount -x -b -f c:\cygwin\bin\wish84.exe /usr/bin/wish84.exe -mount -x -b -f c:\cygwin\bin\wish84.exe /bin/wish84.exe +C:/cygwin/bin /bin ntfs binary,cygexec 0 0 +C:/cygwin/bin /usr/bin ntfs binary,cygexec 0 0 -Note that if you have Tcl/Tk installed, you must specifically exclude -tclsh84 and wish84, which are linked -to the Cygwin DLL but are not actually Cygwin programs. If you have added -other non-Cygwin programs to a path you want to mount cygexec, you can find -them with a script like this: +Note that if you have Tcl/Tk installed, you must additionally +exclude tclsh84 and wish84, which +are linked to the Cygwin DLL but are not actually Cygwin programs: + + + +C:/cygwin/bin/tclsh84.exe /bin/tclsh84.exe ntfs binary,notexec 0 0 +C:/cygwin/bin/tclsh84.exe /usr/bin/tclsh84.exe ntfs binary,notexec 0 0 +C:/cygwin/bin/wish84.exe /bin/wish84.exe ntfs binary,notexec 0 0 +C:/cygwin/bin/wish84.exe /usr/bin/wish84.exe ntfs binary,notexec 0 0 + + +If you have added other non-Cygwin programs to a path you want to mount +cygexec, you can find them with a script like this: #!/bin/sh @@ -112,7 +116,7 @@ done -See +See for more information on using mount. @@ -125,7 +129,7 @@ error? Try running cygserver. Read -. If you're +. If you're trying to use PostgreSQL, also read /usr/share/doc/Cygwin/postgresql-*.README. @@ -168,8 +172,6 @@ gcj --main=Hello Hello.java How do I use Win32 API calls? -(Please note: This section has not yet been updated for the latest net release.) - It's pretty simple actually. Cygwin tools require that you explicitly link the import libraries for whatever Win32 API functions that you are going to use, with the exception of kernel32, which is linked @@ -184,38 +186,13 @@ with gdi32 like this: gcc -o foo.exe foo.c bar.c -lgdi32 -The following libraries are available for use in this way: - -advapi32 largeint ole32 scrnsave vfw32 -cap lz32 oleaut32 shell32 win32spl -comctl32 mapi32 oledlg snmp winmm -comdlg32 mfcuia32 olepro32 svrapi winserve -ctl3d32 mgmtapi opengl32 tapi32 winspool -dlcapi mpr penwin32 th32 winstrm -gdi32 msacm32 pkpd32 thunk32 wow32 -glaux nddeapi rasapi32 url wsock32 -glu32 netapi32 rpcdce4 user32 wst -icmp odbc32 rpcndr uuid -imm32 odbccp32 rpcns4 vdmdbg -kernel32 oldnames rpcrt4 version - The regular setup allows you to use the option -mwindows on the command line to include a set of the basic libraries (and also make your program a GUI program instead of a console program), including user32, gdi32 and, IIRC, comdlg32. -Note that you should never include -lkernel32 on your link line -unless you are invoking ld directly. Do not include the same import -library twice on your link line. Finally, it is a good idea to -put import libraries last on your link line, or at least after -all the object files and static libraries that reference them. - -The first two are related to problems the linker has (as of b18 at least) -when import libraries are referenced twice. Tables get messed up and -programs crash randomly. The last point has to do with the fact that -gcc processes the files listed on the command line in sequence and -will only resolve references to libraries if they are given after -the file that makes the reference. +It is a good idea to put import libraries last on your link line, +or at least after all the object files and static libraries that reference them. @@ -223,6 +200,8 @@ the file that makes the reference. How do I compile a Win32 executable that doesn't use Cygwin? +(Please note: This section has not yet been updated for the latest net release.) + The -mno-cygwin flag to gcc makes gcc link against standard Microsoft DLLs instead of Cygwin. This is desirable for native Windows programs that don't need a UNIX emulation layer. @@ -297,8 +276,8 @@ have our own Win32 headers which are pretty complete. Before you begin, note that Cygwin is licensed under the GNU GPL (as -indeed are all other Cygwin-based libraries). That means that if your -code links against the cygwin dll (and if your program is calling +indeed are many other Cygwin-based libraries). That means that if your +code links against the Cygwin dll (and if your program is calling functions from Cygwin, it must, as a matter of fact, be linked against it), you must apply the GPL to your source as well. Of course, this only matters if you plan to distribute your program in binary form. For @@ -531,18 +510,7 @@ gcc as: cygcheck will do this much more concisely, and operates recursively, provided the command is in your path. -Note there is currently a bug in cygcheck in that it will not report -on a program in a Windows system dir (e.g., C:\Windows or C:\WINNT) even -if it's in your path. To work around this, supply the full Win32 path -to the executable, including the .exe extension: - - -cygcheck c:\\winnt\\system32\\cmd.exe - -(Note the windows path separator must be escaped if this is typed in -bash.) - @@ -569,7 +537,7 @@ question. How can I build a relocatable dll? -(Please note: This section has not yet been updated for the latest net release. However, there was a discussion on the cygwin mailing list recently that addresses this issue. Read http://cygwin.com/ml/cygwin/2000-06/msg00688.html and related messages.) +(Please note: This section has not yet been updated for the latest net release. However, there was a discussion on the cygwin mailing list once that addresses this issue. Read http://cygwin.com/ml/cygwin/2000-06/msg00688.html and related messages.) You must execute the following sequence of five commands, in this order: @@ -689,7 +657,7 @@ info would not be compatible with gdb). Yes. You can use the strace.exe utility to run other cygwin programs with various debug and trace messages enabled. For information on using strace, see the Cygwin User's Guide or the file -winsup/utils/utils.sgml. +winsup/utils/utils.sgml in the Cygwin sources. @@ -722,7 +690,7 @@ This is right gcc hello.cc -lstdc++. struct stat64 is not used in Cygwin, just -use struct stat. +use struct stat. It's 64 bit aware. @@ -746,9 +714,9 @@ the UNICODE stuff for it isn't filled in. Where is malloc.h? -(Please note: This section has not yet been updated for the latest net release.) - -Include stdlib.h instead of malloc.h. +It exists, but you should rather include stdlib.h instead of malloc.h. +stdlib.h is POSIX standard for defining malloc and friends, malloc.h is +definitely non-standard. @@ -809,7 +777,7 @@ data types, line numbers, local variables etc. CPU reference manuals for Intel's current chips are available in downloadable PDF form on Intel's web site: -http://developer.intel.com/design/pro/manuals/ +http://developer.intel.com/ @@ -818,41 +786,34 @@ downloadable PDF form on Intel's web site: If your scripts are in the current directory, you must have . -(dot) in your $PATH. (It is not normally there by default.) Otherwise, -you would need to add /bin/sh in front of each and every shell script -invoked in your Makefiles. +(dot) in your $PATH. (It is not normally there by default.) Better yet, +add /bin/sh in front of each and every shell script invoked in your Makefiles. -What preprocessor do I need to know about? +What preprocessor macros do I need to know about? -We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for -access to the Cygwin environment provided by the dll. +gcc for Cygwin defines __CYGWIN__ when building for a Cygwin +environment. -We chose _WIN32 because this is what Microsoft defines in VC++ and -we thought it would be a good idea for compatibility with VC++ code -to follow their example. We use _MFC_VER to indicate code that should -be compiled with VC++. +Microsoft defines the preprocessor symbol _WIN32 in their Windows +development environment. -_WIN32 is only defined when you use either the -mno-cygwin or -mwin32 +In gcc for Cygwin, _WIN32 is only defined when you use the -mwin32 gcc command line options. This is because Cygwin is supposed to be a -Unix emulation environment and defining _WIN32 confuses some programs -which think that they have to make special concessions for a Windows -environment which Cygwin handles automatically. +POSIX emulation environment in the first place and defining _WIN32 confuses +some programs which think that they have to make special concessions for +a Windows environment which Cygwin handles automatically. -Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to -tell which compiler (or settings) you're running. -Check this out in detail by running, for example +Check out the predefined symbols in detail by running, for example $ gcc -dM -E -xc /dev/null >gcc.txt - $ gcc -mno-cygwin -dM -E -xc /dev/null >gcc-mno-cygwin.txt $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt -Then use the diff and grep utilities to check -what the difference is. +Then use the diff and grep utilities to check what the difference is. @@ -866,7 +827,7 @@ what the difference is. V (and others?). Typically, you will end up with a GUI on Windows that requires some runtime support. With tcl/tk, you'll want to include the necessary library files and the tcl/tk DLLs. In the case of X11, you'll -need everyone using your program to have an X11 server installed. +need everyone using your program to have the X11 server installed. The second method is to rewrite your GUI using Win32 API calls (or MFC with VC++). If your program is written in a fairly modular fashion, you diff --git a/winsup/doc/faq-what.xml b/winsup/doc/faq-what.xml index 64fbad09e..571ff3a7a 100644 --- a/winsup/doc/faq-what.xml +++ b/winsup/doc/faq-what.xml @@ -5,19 +5,20 @@ The Cygwin tools are ports of the popular GNU development tools for Microsoft Windows. They run thanks to the Cygwin library which -provides the UNIX system calls and environment these programs expect. +provides the POSIX system calls and environment these programs expect. -With these tools installed, it is possible to write Win32 console or -GUI applications that make use of the standard Microsoft Win32 API -and/or the Cygwin API. As a result, it is possible to easily -port many significant Unix programs without the need +With these tools installed, it is possible to write Windows console +or GUI applications that make use of significant parts of the POSIX API. +As a result, it is possible to easily port many Unix programs without the need for extensive changes to the source code. This includes configuring and building most of the available GNU software (including the packages -included with the Cygwin development tools themselves). Even if +included with the Cygwin development tools themselves) as well as lots +of BSD tools and packages (including OpenSSH). Even if the development tools are of little to no use to you, you may have -interest in the many standard Unix utilities provided with the package. -They can be used both from the bash shell (provided) or from the -standard Windows command shell. +interest in the many standard POSIX utilities provided with the package. +They can be used from one of the provided Unix shells like bash, tcsh or zsh, +as well as from the standard Windows command shell if you have to for some +sad reason. @@ -26,8 +27,10 @@ standard Windows command shell. Cygwin can be expected to run on all modern 32 bit versions of -Windows, except Windows CE. This includes Windows 95/98/ME/NT/2000/XP/2003 -and the WOW64 32 bit environment on released 64 bit versions of Windows. +Windows, except Windows CE and Windows 95/98/Me. This includes, as of the +time of writing this, Windows NT4, Windows 2000, Windows XP, Windows Server +2003, Windows Vista, Windows Server 2008, as well as the WOW64 32 bit +environment on released 64 bit versions of Windows (XP/2003/Vista/2008). As far as we know no one is working on a native 64 bit version of Cygwin. Since Cygwin is a community-supported free software project, patches to provide support for other versions would be thoughtfully considered. @@ -51,7 +54,9 @@ for download and setup, a current list of mirror sites, a User's Guide, an API Reference, mailing lists and archives, and additional ported software. -You can find documentation for the individual GNU tools at +You can find documentation for the individual GNU tools typically +as man pages or info pages as part of the Cygwin net distribution. +Additionally you can get the latest docs at . (You should read GNU manuals from a local mirror. Check for a list of them.) @@ -64,16 +69,17 @@ for a list of them.) Yes. Parts are GNU software (gcc, gas, ld, etc...), parts are covered by the standard X11 license, some of it is public domain, some of -it was written by Cygnus and placed under the GPL. None of it is -shareware. You don't have to pay anyone to use it but you should be -sure to read the copyright section of the FAQ for more information on -how the GNU General Public License may affect your use of these tools. +it was written by Red Hat (or the former Cygnus Solutions) and placed under +the GPL. None of it is shareware. You don't have to pay anyone to use it +but you should be sure to read the copyright section of the FAQ for more +information on how the GNU General Public License may affect your use of +these tools. In particular, if you intend to port a proprietary (non-GPL'd) application using Cygwin, you will need the proprietary-use license -for the Cygwin library. This is available for purchase; please visit - for more information. -All other questions should be sent to the project +for the Cygwin library. This is available for purchase from Red Hat; +please visit for more +information. All other questions should be sent to the public project mailing list cygwin@cygwin.com. Note that when we say "free" we mean freedom, not price. The goal of @@ -111,39 +117,30 @@ in the Cygwin User's Guide. Who's behind the project? -(Please note that if you have cygwin-specific questions, all of these people will appreciate it if you use the cygwin mailing lists rather than sending personal email.) +(Please note that if you have cygwin-specific +questions, all of these people will appreciate it if you use the cygwin +mailing lists rather than sending personal email.) -Chris Faylor provided the Cygwin signal handler code. He also maintains -the sourceware site where the -cygwin project lives. -Corinna Vinschen has contributed several useful fixes to the path -handling code, console support, improved security handling, and raw -device support. Corinna is currently employed by Red Hat as a -GDB/Cygwin engineer. + +Christopher Faylor (cgf) is one of the project leads. Chris works for +Netapp but all of his Cygwin activities occur on his own time. He is +most notably responsible for the support of signal handling and +fork/exec in Cygwin. He also administer's the site which hosts the +cygwin web site and release. -Steve Chamberlain designed and implemented -Cygwin in 1995-1996 while working for Cygnus. He worked with the Net -to improve the technology, ported/integrated many of the user tools -for the first time to Cygwin, and produced all of the releases up to -beta 14. Steve is not currently employed by Red Hat. + +Corinna Vinschen (corinna) is the other project lead. Corinna is a +senior Red Hat engineer. Corinna is responsible for such important +subsystems as security and networking and has recently added support to +Cygwin for wide characters, increased path length, IPv6, advisory +file locking and more. -Sergey Okhapkin has been an invaluable Net contributor. He implemented -the tty/pty support, has played a significant role in revamping signal -and exception handling, and has made countless contributions throughout -the library. He also provided binaries of the development snapshots to -the Net after the beta 19 release. + +Yaakov Selkowitz is the Cygwin/X coordinator. Jon Turney serves on the +Cygwin/X team as a developer. -Philippe Giacinti contributed the implementation of dlopen, dlclose, -dlsym, dlfork, and dlerror in Cygwin. - -Ian Lance Taylor did a much-needed rework of the path handling code for -beta 18, and has made many assorted fixes throughout the code. Jeremy -Allison made significant contributions in the area of file handling and -process control, and rewrote select from scratch. Doug Evans rewrote -the path-handling code in beta 16, among other things. Kim Knuttila and -Michael Meissner put in many long hours working on the now-defunct -PowerPC port. Jason Molenda and Mark Eichin have also made important -contributions. + +The Cygwin setup project is currently maintained by a group of people, most notably, Brian Dessent (brian) and Dave Korn (dave.korn). Please note that all of us working on Cygwin try to be as responsive as possible and deal with patches and questions as we