JehanneOS/newlib
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
* 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
Download Patch File Download Diff File Expand all files Collapse all files

139
winsup/doc/faq-programming.xml
View 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