OSDN Git Service

* faq-programming.xml: Revamp (mostely) for Cygwin 1.7.
authorcorinna <corinna>
Wed, 11 Feb 2009 18:22:50 +0000 (18:22 +0000)
committercorinna <corinna>
Wed, 11 Feb 2009 18:22:50 +0000 (18:22 +0000)
* faq-what.xml: Ditto.

winsup/doc/ChangeLog
winsup/doc/faq-programming.xml
winsup/doc/faq-what.xml

index 7719221..b6b3368 100644 (file)
@@ -1,5 +1,10 @@
 2009-02-11  Corinna Vinschen  <corinna@vinschen.de>
 
+       * faq-programming.xml: Revamp (mostely) for Cygwin 1.7.
+       * faq-what.xml: Ditto.
+
+2009-02-11  Corinna Vinschen  <corinna@vinschen.de>
+
        * Makefile.in (FAQ_SOURCES): Define FAQ sources.
        (faq/faq.html): Depend on FAQ sources.
        (faq/faq-nochunks.html): Ditto.
index 9e6fee6..948c59d 100644 (file)
@@ -62,11 +62,10 @@ would be difficult.
 <question><para>Where is Objective C?</para></question>
 <answer>
 
-<para>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.
+<para>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.
 </para>
 </answer></qandaentry>
 
@@ -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 <literal>/bin</literal> and 
-<literal>/usr/bin</literal>, you can use these commands in a batch file:
+<literal>/usr/bin</literal>, you can add or change these entries in /etc/fstab:
 </para>
 <screen>
-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
 </screen>
 
-<para>Note that if you have Tcl/Tk installed, you must specifically exclude 
-<literal>tclsh84</literal> and <literal>wish84</literal>, 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:
+<para>Note that if you have Tcl/Tk installed, you must additionally
+exclude <literal>tclsh84</literal> and <literal>wish84</literal>, which
+are linked to the Cygwin DLL but are not actually Cygwin programs:
+</para>
+
+<screen>
+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
+</screen>
+
+<para>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:
 </para>
 <screen>
 #!/bin/sh
@@ -112,7 +116,7 @@ done
 </screen>
 
 <para>
-See <ulink url="http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount" /> 
+See <ulink url="http://cygwin.com/cygwin-ug-net/using.html#mount-table" /> 
 for more information on using mount.
 </para>
 
@@ -125,7 +129,7 @@ error?</para></question>
 
 <para>
 Try running cygserver.  Read 
-<ulink url="http://www.cygwin.com/cygwin-ug-net/using-cygserver.html" />. If you're
+<ulink url="http://cygwin.com/cygwin-ug-net/using-cygserver.html" />. If you're
 trying to use PostgreSQL, also read 
 <literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>.
 </para>
@@ -168,8 +172,6 @@ gcj --main=Hello Hello.java
 <question><para>How do I use Win32 API calls?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
-</para>
 <para>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:
 </para>
 <para>gcc -o foo.exe foo.c bar.c -lgdi32
 </para>
-<para>The following libraries are available for use in this way:
-</para>
-<para>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
-</para>
 <para>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.
 </para>
-<para>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.
-</para>
-<para>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.
+<para>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.
 </para>
 </answer></qandaentry>
 
@@ -223,6 +200,8 @@ the file that makes the reference.
 <question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question>
 <answer>
 
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
 <para>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.
 <answer>
 
 <para>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:
 <para><literal>cygcheck</literal> will do this much more concisely, and operates
 recursively, provided the command is in your path.
 </para>
-<para>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:
-</para>
-<screen>
-cygcheck c:\\winnt\\system32\\cmd.exe
-</screen>
 
-<para>(Note the windows path separator must be escaped if this is typed in
-bash.)
-</para>
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.dll-building">
@@ -569,7 +537,7 @@ question.
 <question><para>How can I build a relocatable dll?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(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 <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis>
+<para><emphasis role='bold'>(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 <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis>
 </para>
 <para>You must execute the following sequence of five commands, in this
 order:
@@ -689,7 +657,7 @@ info would not be compatible with gdb).
 <para>Yes.  You can use the <literal>strace.exe</literal> utility to run other cygwin
 programs with various debug and trace messages enabled.  For information
 on using <literal>strace</literal>, see the Cygwin User's Guide or the file
-<literal>winsup/utils/utils.sgml</literal>.
+<literal>winsup/utils/utils.sgml</literal> in the Cygwin sources.
 </para>
 </answer></qandaentry>
 
@@ -722,7 +690,7 @@ This is right <literal>gcc hello.cc -lstdc++</literal>.
 <answer>
 
 <para><literal>struct stat64</literal> is not used in Cygwin, just
-use <literal>struct stat</literal>.</para>
+use <literal>struct stat</literal>.  It's 64 bit aware.</para>
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.undeclared-functions">
@@ -746,9 +714,9 @@ the UNICODE stuff for it isn't filled in.
 <question><para>Where is malloc.h?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
-</para>
-<para>Include stdlib.h instead of malloc.h.
+<para>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.
 </para>
 </answer></qandaentry>
 
@@ -809,7 +777,7 @@ data types, line numbers, local variables etc.
 <para>CPU reference manuals for Intel's current chips are available in
 downloadable PDF form on Intel's web site:
 </para>
-<para><ulink url="http://developer.intel.com/design/pro/manuals/">http://developer.intel.com/design/pro/manuals/</ulink>
+<para><ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink>
 </para>
 </answer></qandaentry>
 
@@ -818,41 +786,34 @@ downloadable PDF form on Intel's web site:
 <answer>
 
 <para>If your scripts are in the current directory, you must have <literal>.</literal>
-(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.
 </para>
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.preprocessor">
-<question><para>What preprocessor do I need to know about?</para></question>
+<question><para>What preprocessor macros do I need to know about?</para></question>
 <answer>
 
-<para>We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for
-access to the Cygwin environment provided by the dll.
+<para>gcc for Cygwin defines __CYGWIN__ when building for a Cygwin
+environment.
 </para>
-<para>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++.
+<para>Microsoft defines the preprocessor symbol _WIN32 in their Windows
+development environment.
 </para>
-<para>_WIN32 is only defined when you use either the -mno-cygwin or -mwin32
+<para>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.
 </para>
-<para>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
+<para>Check out the predefined symbols in detail by running, for example
 </para>
 <screen>
        $ gcc  -dM -E -xc /dev/null &gt;gcc.txt
-       $ gcc -mno-cygwin -dM -E -xc /dev/null &gt;gcc-mno-cygwin.txt
        $ gcc -mwin32 -dM -E -xc /dev/null &gt;gcc-mwin32.txt
 </screen>
-<para>Then use the diff and grep utilities to check
-what the difference is.
+<para>Then use the diff and grep utilities to check what the difference is.
 </para>
 </answer></qandaentry>
 
@@ -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.
 </para>
 <para>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
index 64fbad0..571ff3a 100644 (file)
@@ -5,19 +5,20 @@
 
 <para>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.
 </para>
-<para>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
+<para>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.
 </para>
 </answer></qandaentry>
 
@@ -26,8 +27,10 @@ standard Windows command shell.
 <answer>
 
 <para>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.
 </para>
-<para>You can find documentation for the individual GNU tools at
+<para>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
 <ulink url="http://www.gnu.org/manual/" />.  (You should read GNU manuals from a
 local mirror.  Check <ulink url="http://www.gnu.org/server/list-mirrors.html" />
 for a list of them.)
@@ -64,16 +69,17 @@ for a list of them.)
 
 <para>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.
 </para>
 <para>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
-<ulink url="http://cygwin.com/license.html" /> 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 <ulink url="http://cygwin.com/license.html" /> for more
+information.  All other questions should be sent to the public project
 mailing list cygwin@cygwin.com.
 </para>
 <para>Note that when we say "free" we mean freedom, not price.  The goal of
@@ -111,39 +117,30 @@ in the Cygwin User's Guide.
 <question><para>Who's behind the project?</para></question>
 <answer>
 
-<para><emphasis role='bold'>(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.)</emphasis>
-</para>
-<para>Chris Faylor provided the Cygwin signal handler code.  He also maintains
-the <ulink url='http://sourceware.org'>sourceware site</ulink> where the
-cygwin project lives.</para>
-<para>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.
-</para>
-<para>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.
-</para>
-<para>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.
-</para>
-<para>Philippe Giacinti contributed the implementation of dlopen, dlclose,
-dlsym, dlfork, and dlerror in Cygwin.
-</para>
-<para>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.
+<para><emphasis role='bold'>(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.)</emphasis>
+</para>
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+Yaakov Selkowitz is the Cygwin/X coordinator. Jon Turney serves on the
+Cygwin/X team as a developer.
+</para>
+<para>
+The Cygwin setup project is currently maintained by a group of people, most notably, Brian Dessent (brian) and Dave Korn (dave.korn).
 </para>
 <para>Please note that all of us working on Cygwin try to
 be as responsive as possible and deal with patches and questions as we