* faq-programming.xml: Revamp (mostely) for Cygwin 1.7.

* faq-what.xml: Ditto.
This commit is contained in:
Corinna Vinschen 2009-02-11 18:22:50 +00:00
parent bb549dfed8
commit c2da1d6ebf
3 changed files with 100 additions and 137 deletions

View File

@ -1,3 +1,8 @@
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> 2009-02-11 Corinna Vinschen <corinna@vinschen.de>
* Makefile.in (FAQ_SOURCES): Define FAQ sources. * Makefile.in (FAQ_SOURCES): Define FAQ sources.

View File

@ -62,11 +62,10 @@ would be difficult.
<question><para>Where is Objective C?</para></question> <question><para>Where is Objective C?</para></question>
<answer> <answer>
<para>Objective C is not distributed with the Cygwin version of gcc, and there <para>Objective C hasn't been distributed with the Cygwin version of gcc
are no plans to do so. The gcc package maintainer had difficulty for a long time. For several reason Cygwin was stuck with gcc version 3.4.4.
building it, and once built there were problems using it. It appears Fortunately the latest gcc maintainer is quite busy to create a working
that there is only minimal support for the Objective C front-end in the gcc 4.x release which also comes with an Objective C package.
main GCC distribution, anyway.
</para> </para>
</answer></qandaentry> </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 to exclude non-cygwin executables with the -x switch. Enabling cygexec
causes cygwin executables to talk directly to one another, which increases causes cygwin executables to talk directly to one another, which increases
the command-line limit. To enable cygexec for <literal>/bin</literal> and 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> </para>
<screen> <screen>
mount -X -b -f c:\cygwin\bin /bin C:/cygwin/bin /bin ntfs binary,cygexec 0 0
mount -X -b -f c:\cygwin\bin /usr/bin C:/cygwin/bin /usr/bin ntfs binary,cygexec 0 0
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
</screen> </screen>
<para>Note that if you have Tcl/Tk installed, you must specifically exclude <para>Note that if you have Tcl/Tk installed, you must additionally
<literal>tclsh84</literal> and <literal>wish84</literal>, which are linked exclude <literal>tclsh84</literal> and <literal>wish84</literal>, which
to the Cygwin DLL but are not actually Cygwin programs. If you have added are linked to the Cygwin DLL but are not actually Cygwin programs:
other non-Cygwin programs to a path you want to mount cygexec, you can find </para>
them with a script like this:
<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> </para>
<screen> <screen>
#!/bin/sh #!/bin/sh
@ -112,7 +116,7 @@ done
</screen> </screen>
<para> <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. for more information on using mount.
</para> </para>
@ -125,7 +129,7 @@ error?</para></question>
<para> <para>
Try running cygserver. Read 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 trying to use PostgreSQL, also read
<literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>. <literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>.
</para> </para>
@ -168,8 +172,6 @@ gcj --main=Hello Hello.java
<question><para>How do I use Win32 API calls?</para></question> <question><para>How do I use Win32 API calls?</para></question>
<answer> <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 <para>It's pretty simple actually. Cygwin tools require that you explicitly
link the import libraries for whatever Win32 API functions that you link the import libraries for whatever Win32 API functions that you
are going to use, with the exception of kernel32, which is linked are going to use, with the exception of kernel32, which is linked
@ -184,38 +186,13 @@ with gdi32 like this:
</para> </para>
<para>gcc -o foo.exe foo.c bar.c -lgdi32 <para>gcc -o foo.exe foo.c bar.c -lgdi32
</para> </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 <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 command line to include a set of the basic libraries (and also
make your program a GUI program instead of a console program), make your program a GUI program instead of a console program),
including user32, gdi32 and, IIRC, comdlg32. including user32, gdi32 and, IIRC, comdlg32.
</para> </para>
<para>Note that you should never include -lkernel32 on your link line <para>It is a good idea to put import libraries last on your link line,
unless you are invoking ld directly. Do not include the same import or at least after all the object files and static libraries that reference them.
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> </para>
</answer></qandaentry> </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> <question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question>
<answer> <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 <para>The -mno-cygwin flag to gcc makes gcc link against standard Microsoft
DLLs instead of Cygwin. This is desirable for native Windows programs DLLs instead of Cygwin. This is desirable for native Windows programs
that don't need a UNIX emulation layer. that don't need a UNIX emulation layer.
@ -297,8 +276,8 @@ have our own Win32 headers which are pretty complete.
<answer> <answer>
<para>Before you begin, note that Cygwin is licensed under the GNU GPL (as <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 indeed are many other Cygwin-based libraries). That means that if your
code links against the cygwin dll (and if your program is calling 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 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 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 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 <para><literal>cygcheck</literal> will do this much more concisely, and operates
recursively, provided the command is in your path. recursively, provided the command is in your path.
</para> </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> </answer></qandaentry>
<qandaentry id="faq.programming.dll-building"> <qandaentry id="faq.programming.dll-building">
@ -569,7 +537,7 @@ question.
<question><para>How can I build a relocatable dll?</para></question> <question><para>How can I build a relocatable dll?</para></question>
<answer> <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>
<para>You must execute the following sequence of five commands, in this <para>You must execute the following sequence of five commands, in this
order: 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 <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 programs with various debug and trace messages enabled. For information
on using <literal>strace</literal>, see the Cygwin User's Guide or the file 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> </para>
</answer></qandaentry> </answer></qandaentry>
@ -722,7 +690,7 @@ This is right <literal>gcc hello.cc -lstdc++</literal>.
<answer> <answer>
<para><literal>struct stat64</literal> is not used in Cygwin, just <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> </answer></qandaentry>
<qandaentry id="faq.programming.undeclared-functions"> <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> <question><para>Where is malloc.h?</para></question>
<answer> <answer>
<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> <para>It exists, but you should rather include stdlib.h instead of malloc.h.
</para> stdlib.h is POSIX standard for defining malloc and friends, malloc.h is
<para>Include stdlib.h instead of malloc.h. definitely non-standard.
</para> </para>
</answer></qandaentry> </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 <para>CPU reference manuals for Intel's current chips are available in
downloadable PDF form on Intel's web site: downloadable PDF form on Intel's web site:
</para> </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> </para>
</answer></qandaentry> </answer></qandaentry>
@ -818,41 +786,34 @@ downloadable PDF form on Intel's web site:
<answer> <answer>
<para>If your scripts are in the current directory, you must have <literal>.</literal> <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, (dot) in your $PATH. (It is not normally there by default.) Better yet,
you would need to add /bin/sh in front of each and every shell script add /bin/sh in front of each and every shell script invoked in your Makefiles.
invoked in your Makefiles.
</para> </para>
</answer></qandaentry> </answer></qandaentry>
<qandaentry id="faq.programming.preprocessor"> <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> <answer>
<para>We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for <para>gcc for Cygwin defines __CYGWIN__ when building for a Cygwin
access to the Cygwin environment provided by the dll. environment.
</para> </para>
<para>We chose _WIN32 because this is what Microsoft defines in VC++ and <para>Microsoft defines the preprocessor symbol _WIN32 in their Windows
we thought it would be a good idea for compatibility with VC++ code development environment.
to follow their example. We use _MFC_VER to indicate code that should
be compiled with VC++.
</para> </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 gcc command line options. This is because Cygwin is supposed to be a
Unix emulation environment and defining _WIN32 confuses some programs POSIX emulation environment in the first place and defining _WIN32 confuses
which think that they have to make special concessions for a Windows some programs which think that they have to make special concessions for
environment which Cygwin handles automatically. a Windows environment which Cygwin handles automatically.
</para> </para>
<para>Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to <para>Check out the predefined symbols in detail by running, for example
tell which compiler (or settings) you're running.
Check this out in detail by running, for example
</para> </para>
<screen> <screen>
$ gcc -dM -E -xc /dev/null &gt;gcc.txt $ 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 $ gcc -mwin32 -dM -E -xc /dev/null &gt;gcc-mwin32.txt
</screen> </screen>
<para>Then use the diff and grep utilities to check <para>Then use the diff and grep utilities to check what the difference is.
what the difference is.
</para> </para>
</answer></qandaentry> </answer></qandaentry>
@ -866,7 +827,7 @@ what the difference is.
V (and others?). Typically, you will end up with a GUI on Windows that 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 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 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>
<para>The second method is to rewrite your GUI using Win32 API calls (or MFC <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 with VC++). If your program is written in a fairly modular fashion, you

View File

@ -5,19 +5,20 @@
<para>The Cygwin tools are ports of the popular GNU development tools for <para>The Cygwin tools are ports of the popular GNU development tools for
Microsoft Windows. They run thanks to the Cygwin library which 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>
<para>With these tools installed, it is possible to write Win32 console or <para>With these tools installed, it is possible to write Windows console
GUI applications that make use of the standard Microsoft Win32 API or GUI applications that make use of significant parts of the POSIX API.
and/or the Cygwin API. As a result, it is possible to easily As a result, it is possible to easily port many Unix programs without the need
port many significant Unix programs without the need
for extensive changes to the source code. This includes configuring for extensive changes to the source code. This includes configuring
and building most of the available GNU software (including the packages 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 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. interest in the many standard POSIX utilities provided with the package.
They can be used both from the bash shell (provided) or from the They can be used from one of the provided Unix shells like bash, tcsh or zsh,
standard Windows command shell. as well as from the standard Windows command shell if you have to for some
sad reason.
</para> </para>
</answer></qandaentry> </answer></qandaentry>
@ -26,8 +27,10 @@ standard Windows command shell.
<answer> <answer>
<para>Cygwin can be expected to run on all modern 32 bit versions of <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 Windows, except Windows CE and Windows 95/98/Me. This includes, as of the
and the WOW64 32 bit environment on released 64 bit versions of Windows. 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. 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 Since Cygwin is a community-supported free software project, patches to
provide support for other versions would be thoughtfully considered. 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 Guide, an API Reference, mailing lists and archives, and additional
ported software. ported software.
</para> </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 <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" /> local mirror. Check <ulink url="http://www.gnu.org/server/list-mirrors.html" />
for a list of them.) 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 <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 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 it was written by Red Hat (or the former Cygnus Solutions) and placed under
shareware. You don't have to pay anyone to use it but you should be the GPL. None of it is shareware. You don't have to pay anyone to use it
sure to read the copyright section of the FAQ for more information on but you should be sure to read the copyright section of the FAQ for more
how the GNU General Public License may affect your use of these tools. information on how the GNU General Public License may affect your use of
these tools.
</para> </para>
<para>In particular, if you intend to port a proprietary (non-GPL'd) <para>In particular, if you intend to port a proprietary (non-GPL'd)
application using Cygwin, you will need the proprietary-use license application using Cygwin, you will need the proprietary-use license
for the Cygwin library. This is available for purchase; please visit for the Cygwin library. This is available for purchase from Red Hat;
<ulink url="http://cygwin.com/license.html" /> for more information. please visit <ulink url="http://cygwin.com/license.html" /> for more
All other questions should be sent to the project information. All other questions should be sent to the public project
mailing list cygwin@cygwin.com. mailing list cygwin@cygwin.com.
</para> </para>
<para>Note that when we say "free" we mean freedom, not price. The goal of <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> <question><para>Who's behind the project?</para></question>
<answer> <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><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>
<para>Chris Faylor provided the Cygwin signal handler code. He also maintains <para>
the <ulink url='http://sourceware.org'>sourceware site</ulink> where the Christopher Faylor (cgf) is one of the project leads. Chris works for
cygwin project lives.</para> Netapp but all of his Cygwin activities occur on his own time. He is
<para>Corinna Vinschen has contributed several useful fixes to the path most notably responsible for the support of signal handling and
handling code, console support, improved security handling, and raw fork/exec in Cygwin. He also administer's the site which hosts the
device support. Corinna is currently employed by Red Hat as a cygwin web site and release.
GDB/Cygwin engineer.
</para> </para>
<para>Steve Chamberlain designed and implemented <para>
Cygwin in 1995-1996 while working for Cygnus. He worked with the Net Corinna Vinschen (corinna) is the other project lead. Corinna is a
to improve the technology, ported/integrated many of the user tools senior Red Hat engineer. Corinna is responsible for such important
for the first time to Cygwin, and produced all of the releases up to subsystems as security and networking and has recently added support to
beta 14. Steve is not currently employed by Red Hat. Cygwin for wide characters, increased path length, IPv6, advisory
file locking and more.
</para> </para>
<para>Sergey Okhapkin has been an invaluable Net contributor. He implemented <para>
the tty/pty support, has played a significant role in revamping signal Yaakov Selkowitz is the Cygwin/X coordinator. Jon Turney serves on the
and exception handling, and has made countless contributions throughout Cygwin/X team as a developer.
the library. He also provided binaries of the development snapshots to
the Net after the beta 19 release.
</para> </para>
<para>Philippe Giacinti contributed the implementation of dlopen, dlclose, <para>
dlsym, dlfork, and dlerror in Cygwin. The Cygwin setup project is currently maintained by a group of people, most notably, Brian Dessent (brian) and Dave Korn (dave.korn).
</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> </para>
<para>Please note that all of us working on Cygwin try to <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 be as responsive as possible and deal with patches and questions as we