1045 lines
39 KiB
XML
1045 lines
39 KiB
XML
<?xml version="1.0" encoding='UTF-8'?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<!-- faq-programming.xml -->
|
|
|
|
<qandadiv id="faq.programming">
|
|
<title>Programming Questions</title>
|
|
|
|
<qandaentry id="faq.programming.packages">
|
|
<question><para>How do I contribute a package?</para></question>
|
|
<answer>
|
|
|
|
<para>If you are willing to be a package maintainer, great! We urgently need
|
|
volunteers to prepare and maintain packages, because the priority of the
|
|
Cygwin Team is Cygwin itself.
|
|
</para>
|
|
<para>The Cygwin Package Contributor's Guide at
|
|
<ulink url="https://cygwin.com/setup.html"/> details everything you need to know
|
|
about being a package maintainer. The quickest way to get started is to
|
|
read the <emphasis>Initial packaging procedure, script-based</emphasis> section on
|
|
that page. The <literal>generic-build-script</literal> found there works well for
|
|
most packages.
|
|
</para>
|
|
<para>For questions about package maintenance, use the cygwin-apps mailing
|
|
list (start at <ulink url="https://cygwin.com/lists.html"/>) <emphasis>after</emphasis>
|
|
searching and browsing the cygwin-apps list archives, of course. Be
|
|
sure to look at the <emphasis>Submitting a package</emphasis> checklist at
|
|
<ulink url="https://cygwin.com/setup.html"/> before sending an ITP (Intent To
|
|
Package) email to cygwin-apps.
|
|
</para>
|
|
<para>You should also announce your intentions to the general cygwin list, in
|
|
case others were thinking the same thing.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.contribute">
|
|
<question><para>How do I contribute to Cygwin?</para></question>
|
|
<answer>
|
|
|
|
<para>If you want to contribute to Cygwin itself, see
|
|
<ulink url="https://cygwin.com/contrib.html"/>.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.huge-executables">
|
|
<question><para>Why are compiled executables so huge?!?</para></question>
|
|
<answer>
|
|
|
|
<para>By default, gcc compiles in all symbols. You'll also find that gcc
|
|
creates large executables on UNIX.
|
|
</para>
|
|
<para>If that bothers you, just use the 'strip' program, part of the binutils
|
|
package. Or compile with the <literal>-s</literal> option to gcc.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.64bitporting">
|
|
<question><para>What do I have to look out for when porting applications to 64 bit Cygwin?</para></question>
|
|
<answer>
|
|
|
|
<para>The Cygwin x86_64 toolchain is using the
|
|
<ulink url="http://en.wikipedia.org/wiki/LLP64#64-bit_data_models">LP64</ulink>
|
|
data model. That means, in contrast to Windows, which uses an
|
|
<ulink url="http://en.wikipedia.org/wiki/LLP64#64-bit_data_models">LLP64</ulink>
|
|
data model, sizeof(long) != sizeof(int), just as on Linux.</para>
|
|
|
|
<para>For comparison:</para>
|
|
|
|
<screen>
|
|
Cygwin Windows Cygwin
|
|
Linux x86_64 Linux
|
|
Windows x86_64
|
|
i686
|
|
|
|
sizeof(int) 4 4 4
|
|
sizeof(long) 4 4 8
|
|
sizeof(size_t) 4 8 8
|
|
sizeof(void*) 4 8 8
|
|
</screen>
|
|
|
|
<para>This difference can result in interesting problems, especially when
|
|
using Win32 functions, especially when using pointers to Windows
|
|
datatypes like LONG, ULONG, DWORD. Given that Windows is LLP64, all of
|
|
the aforementioned types are 4 byte in size, on 32 as well as on 64 bit
|
|
Windows, while `long' on 64 bit Cygwin is 8 bytes.</para>
|
|
|
|
<para>Take the example ReadFile:</para>
|
|
|
|
<screen>
|
|
ReadFile (HANDLE, LPVOID, DWORD, LPDWORD, LPOVERLAPPED);
|
|
</screen>
|
|
|
|
<para>In the 32 bit Cygwin and Mingw-w64 environments, as well as in the 64 bit
|
|
Mingw-w64 environment, it is no problem to substitute DWORD with unsigned
|
|
long:</para>
|
|
|
|
<screen>
|
|
unsigned long number_of_bytes_read;
|
|
[...]
|
|
ReadFile (fhdl, buf, buflen, &number_of_bytes_read, NULL);
|
|
</screen>
|
|
|
|
<para>However, in 64 bit Cygwin, using LP64, number_of_bytes_read is 8 bytes
|
|
in size. But since ReadFile expects a pointer to a 4 byte type, the function
|
|
will only change the lower 4 bytes of number_of_bytes_read on return, while
|
|
the content of the upper 4 bytes stays undefined.</para>
|
|
|
|
<para>Here are a few <emphasis>donts</emphasis> which should help porting
|
|
applications from the known ILP32 data model of 32 bit Cygwin, to the LP64
|
|
data model of 64 bit Cygwin. Note that these are not Cygwin-only problems.
|
|
Many Linux applications suffered the same somewhat liberal handling of
|
|
datatypes when the AMD64 CPU was new.</para>
|
|
|
|
<itemizedlist mark="bullet">
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> mix up int and long in printf/scanf. This:
|
|
|
|
<screen>
|
|
int i; long l;
|
|
printf ("%d %ld\n", l, i);
|
|
</screen>
|
|
|
|
may not print what you think it should. Enable the gcc options -Wformat or
|
|
-Wall, which warn about type mismatches in printf/scanf functions.
|
|
|
|
<note>Using -Wall (optionally with -Werror to drive the point home) makes a
|
|
lot of sense in general, not only when porting code to a new platform.</note>
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> mix int and long pointers.
|
|
|
|
<screen>
|
|
long *long_ptr = (long *) &my_int; /* Uh oh! */
|
|
*long_ptr = 42;
|
|
</screen>
|
|
|
|
The assignment will write 8 bytes to the address of my_int. Since my_int
|
|
is only 4 bytes, <emphasis>something else</emphasis> gets randomly overwritten.
|
|
Finding this kind of bug is very hard, because you will often see a problem
|
|
which has no immediate connection to the actual bug.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> mix int and pointers at all! This will
|
|
<emphasis>not</emphasis> work as expected anymore:
|
|
|
|
<screen>
|
|
void *ptr;
|
|
printf ("Pointer value is %x\n", ptr);
|
|
</screen>
|
|
|
|
%x denotes an int argument. The value printed by printf is a 4 byte value,
|
|
so on x86_64 the printed pointer value is missing its upper 4 bytes; the output
|
|
is very likely wrong. Use %p instead, which portable across architectures:
|
|
|
|
<screen>
|
|
void *ptr;
|
|
printf ("Pointer value is %p\n", ptr);
|
|
</screen>
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
Along the same lines <emphasis>don't</emphasis> use the type int in
|
|
pointer arithmetic. Don't cast pointers to int, don't cast pointer
|
|
differences to int, and don't store pointer differences in an int type.
|
|
Use the types <literal>intptr_t</literal>, <literal>uintptr_t</literal>
|
|
and <literal>ptrdiff_t</literal> instead, they are designed for performing
|
|
architecture-independent pointer arithmetic.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> make blind assumptions about the size of a POSIX
|
|
type. For instance, <literal>time_t</literal> is 8 bytes on 64 bit Cygwin,
|
|
while it is (still, at the time of writing this) 4 bytes on 32 bit Cygwin,
|
|
since time_t is based on the type long.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> use functions returning pointers without declaration.
|
|
For instance
|
|
|
|
<screen>
|
|
printf ("Error message is: %s\n", strerror (errno));
|
|
</screen>
|
|
|
|
This code will <emphasis>crash</emphasis>, unless you included
|
|
<filename>string.h</filename>. The implicit rule in C is that an undeclared
|
|
function is of type int. But int is 4 byte and pointers are 8 byte, so the
|
|
string pointer given to printf is missing the upper 4 bytes.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> use C base types together with Win32 functions.
|
|
Keep in mind that DWORD, LONG, ULONG are <emphasis>not</emphasis> the same
|
|
as long and unsigned long. Try to use only Win32 datatypes in conjunction
|
|
with Win32 API function calls to avoid type problems. See the above
|
|
ReadFile example. Windows functions in printf calls should be treated
|
|
carefully as well. This code is common for 32 bit code, but probably prints
|
|
the wrong value on 64 bit:
|
|
|
|
<screen>
|
|
printf ("Error message is: %lu\n", GetLastError ());
|
|
</screen>
|
|
|
|
Using gcc's -Wformat option would warn about this. Casting to the requested
|
|
base type helps in this case:
|
|
|
|
<screen>
|
|
printf ("Error message is: %lu\n", (unsigned long) GetLastError ());
|
|
</screen>
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Don't</emphasis> mix Windows datatypes with POSIX type-specific
|
|
MIN/MAX values.
|
|
|
|
<screen>
|
|
unsigned long l_max = ULONG_MAX; /* That's right. */
|
|
ULONG w32_biggest = ULONG_MAX; /* Hey, wait! What? */
|
|
ULONG w32_biggest = UINT_MAX; /* Ok, but borderline. */
|
|
</screen>
|
|
|
|
Again, keep in mind that ULONG (or DWORD) is <emphasis>not</emphasis> unsigned
|
|
long but rather unsigned int on 64 bit.
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.64bitporting-fail">
|
|
<question><para>My project doesn't build at all on 64 bit Cygwin. What's up?</para></question>
|
|
<answer>
|
|
|
|
<para>Typically reasons for that are:</para>
|
|
|
|
<itemizedlist mark="bullet">
|
|
|
|
<listitem><para><literal>__CYGWIN32__</literal> is not defined in the
|
|
64 bit toolchain. This may hit a few projects which are around since before
|
|
Y2K. Check your project for occurences of <literal>__CYGWIN32__</literal>
|
|
and change them to <literal>__CYGWIN__</literal>, which is defined in the
|
|
Cygwin toolchain since 1998, to get the same Cygwin-specific code changes done.
|
|
</para></listitem>
|
|
|
|
<listitem><para>The project maintainers took it for granted that Cygwin is
|
|
running only on i686 CPUs and the code is making this assumption blindly.
|
|
You have to check the code for such assumptions and fix them.
|
|
</para></listitem>
|
|
|
|
<listitem><para>The project is using autotools, the
|
|
<filename>config.sub</filename> and <filename>config.guess</filename> files
|
|
are hopelessly outdated and don't recognize
|
|
<literal>x86_64-{pc,unknown}-cygwin</literal> as valid target. Update the
|
|
project configury (cygport will do this by default) and try again.
|
|
</para></listitem>
|
|
|
|
<listitem><para>The project uses Windows functions on Cygwin and it's suffering
|
|
from the problems described in the preceeding FAQ entry.
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<para>In all of this cases, please make sure to fix that upstream, or send
|
|
your patches to the upstream maintainers, so the problems get fixed for the
|
|
future.</para>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.64bitporting-cygwin64">
|
|
<question><para>Why is __CYGWIN64__ not defined for 64 bit?</para></question>
|
|
<answer>
|
|
|
|
<para>There is no <literal>__CYGWIN64__</literal> because we would like to
|
|
have a unified way to handle Cygwin code in portable projects. Using
|
|
<literal>__CYGWIN32__</literal> and <literal>__CYGWIN64__</literal> only
|
|
complicates the code for no good reason. Along the same lines you won't
|
|
find predefined macros <literal>__linux32__</literal> and
|
|
<literal>__linux64__</literal> on Linux.</para>
|
|
|
|
<para>If you really have to differ between 32 and 64 bit in some way, you have
|
|
three choices.</para>
|
|
|
|
<itemizedlist mark="bullet">
|
|
|
|
<listitem><para>If your code depends on the CPU architecture, use the
|
|
predefined compiler definition for the architecture, like this:</para>
|
|
|
|
<screen>
|
|
#ifdef __CYGWIN__
|
|
# ifdef __x86_64__ /* Alternatively __x86_64, __amd64__, __amd64 */
|
|
/* Code specific for AMD64 CPU */
|
|
# elif __X86__
|
|
/* Code specific for ix86 CPUs */
|
|
# else
|
|
# error Unsupported Architecture
|
|
# endif
|
|
#endif
|
|
</screen></listitem>
|
|
|
|
<listitem><para>If your code depends on differences in the data model, you
|
|
should consider to use the <literal>__LP64__</literal> definition
|
|
instead:</para>
|
|
|
|
<screen>
|
|
#ifdef __CYGWIN__
|
|
# ifdef __LP64__ /* Alternatively _LP64 */
|
|
/* Code specific for 64 bit CPUs */
|
|
# else
|
|
/* Code specific for 32 bit CPUs */
|
|
# endif
|
|
#endif
|
|
</screen></listitem>
|
|
|
|
<listitem><para>If your code uses Windows functions, and some of the
|
|
functionality is 64 bit Windows-specific, use <literal>_WIN64</literal>,
|
|
which is defined on 64 bit Cygwin, as soon as you include
|
|
<filename>windows.h</filename>. This should only be used in the most
|
|
desperate of occasions, though, and <emphasis>only</emphasis> if it's
|
|
really about a difference in Windows API functionality!</para>
|
|
|
|
<screen>
|
|
#ifdef __CYGWIN__
|
|
# ifdef _WIN64
|
|
/* Code specific for 64 bit Windows */
|
|
# else
|
|
/* Code specific for 32 bit Windows */
|
|
# endif
|
|
#endif
|
|
</screen></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.glibc">
|
|
<question><para>Where is glibc?</para></question>
|
|
<answer>
|
|
|
|
<para>Cygwin does not provide glibc. It uses newlib instead, which provides
|
|
much (but not all) of the same functionality. Porting glibc to Cygwin
|
|
would be difficult.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.objective-c">
|
|
<question><para>Where is Objective C?</para></question>
|
|
<answer>
|
|
|
|
<para>Support for compiling Objective C is available in the <literal>gcc{4}-objc</literal>
|
|
package; resulting binaries will depend on the <literal>libobjc2</literal>
|
|
package at runtime.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.make-execvp">
|
|
<question><para>Why does my make fail on Cygwin with an execvp error? </para></question>
|
|
<answer>
|
|
|
|
<para>Beware of using non-portable shell features in your Makefiles (see tips
|
|
at <ulink url="https://cygwin.com/faq/faq.html#faq.using.shell-scripts"/>).
|
|
</para>
|
|
<para>Errors of <literal>make: execvp: /bin/sh: Illegal Argument</literal> or
|
|
<literal>make: execvp: /bin/sh: Argument list too long</literal> are often
|
|
caused by the command-line being to long for the Windows execution model.
|
|
To circumvent this, mount the path of the executable using the -X switch
|
|
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 add or change these entries in /etc/fstab:
|
|
</para>
|
|
<screen>
|
|
C:/cygwin/bin /bin ntfs binary,cygexec 0 0
|
|
C:/cygwin/bin /usr/bin ntfs binary,cygexec 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
|
|
cd /bin; for f in `find . -type f -name '*.exe'`; do
|
|
cygcheck $f | (fgrep -qi cygwin1.dll || echo $f)
|
|
done
|
|
</screen>
|
|
|
|
<para>
|
|
See <ulink url="https://cygwin.com/cygwin-ug-net/using.html#mount-table"/>
|
|
for more information on using mount.
|
|
</para>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.ipc">
|
|
<question><para>How can I use IPC, or why do I get a <literal>Bad system call</literal>
|
|
error?</para></question>
|
|
<answer>
|
|
|
|
<para>
|
|
Try running cygserver. Read
|
|
<ulink url="https://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>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.winmain">
|
|
<question><para>Why the undefined reference to <literal>WinMain@16</literal>?</para></question>
|
|
<answer>
|
|
|
|
<para>If you're using <literal>gcc</literal>, try adding an empty main() function to one
|
|
of your sources. Or, perhaps you have <literal>-lm</literal> too early in the
|
|
link command line. It should be at the end:
|
|
</para>
|
|
<screen>
|
|
bash$ gcc hello.c -lm
|
|
bash$ ./a.exe
|
|
Hello World!
|
|
</screen>
|
|
|
|
<para>works, but
|
|
</para>
|
|
<screen>
|
|
bash$ gcc -lm hello.c
|
|
/c/TEMP/ccjLEGlU.o(.text+0x10):hello.c: multiple definition of `main'
|
|
/usr/lib/libm.a(libcmain.o)(.text+0x0):libcmain.c: first defined here
|
|
/usr/lib/libm.a(libcmain.o)(.text+0x6a):libcmain.c: undefined reference to `WinMain@16'
|
|
collect2: ld returned 1 exit status
|
|
</screen>
|
|
|
|
<para>If you're using GCJ, you need to pass a "--main" flag:
|
|
</para>
|
|
<screen>
|
|
gcj --main=Hello Hello.java
|
|
</screen>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.win32-api">
|
|
<question><para>How do I use Win32 API calls?</para></question>
|
|
<answer>
|
|
|
|
<para>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 automatically (because the startup and/or
|
|
built-in code uses it).
|
|
</para>
|
|
<para>For example, to use graphics functions (GDI) you must link
|
|
with gdi32 like this:
|
|
</para>
|
|
<para>gcc -o foo.exe foo.o bar.o -lgdi32
|
|
</para>
|
|
<para>or (compiling and linking in one step):
|
|
</para>
|
|
<para>gcc -o foo.exe foo.c bar.c -lgdi32
|
|
</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 comdlg32.
|
|
</para>
|
|
<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>
|
|
|
|
<note><para>There are a few restrictions for calls to the Win32 API.
|
|
For details, see the User's Guide section
|
|
<ulink url="https://cygwin.com/cygwin-ug-net/setup-env.html#setup-env-win32">Restricted Win32 environment</ulink>,
|
|
as well as the User's Guide section
|
|
<ulink url="https://cygwin.com/cygwin-ug-net/using.html#pathnames-win32-api">Using the Win32 file API in Cygwin applications</ulink>.</para></note>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.win32-no-cygwin">
|
|
<question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question>
|
|
<answer>
|
|
|
|
<para>The compilers provided by the <literal>mingw64-i686-gcc</literal> and
|
|
<literal>mingw64-x86_64-gcc</literal> packages link against standard Microsoft
|
|
DLLs instead of Cygwin. This is desirable for native Windows programs that
|
|
don't need a UNIX emulation layer.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.static-linking">
|
|
<question><para>Can I build a Cygwin program that does not require cygwin1.dll at runtime?</para></question>
|
|
<answer>
|
|
|
|
<para>No. If your program uses the Cygwin API, then your executable cannot
|
|
run without cygwin1.dll. In particular, it is not possible to
|
|
statically link with a Cygwin library to obtain an independent,
|
|
self-contained executable.
|
|
</para>
|
|
<para>If this is an issue because you intend to distribute your Cygwin
|
|
application, then you had better read and understand
|
|
<ulink url="https://cygwin.com/licensing.html"/>, which explains the licensing
|
|
options. Unless you purchase a special commercial license from Red
|
|
Hat, then your Cygwin application must be Open Source.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.msvcrt-and-cygwin">
|
|
<question><para>Can I link with both MSVCRT*.DLL and cygwin1.dll?</para></question>
|
|
<answer>
|
|
|
|
<para>No, you must use one or the other, they are mutually exclusive.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.no-console-window">
|
|
<question><para>How do I make the console window go away?</para></question>
|
|
<answer>
|
|
|
|
<para>The default during compilation is to produce a console application.
|
|
It you are writing a GUI program, you should either compile with
|
|
-mwindows as explained above, or add the string
|
|
"-Wl,--subsystem,windows" to the GCC command line.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.make-spaces">
|
|
<question><para>Why does make complain about a "missing separator"?</para></question>
|
|
<answer>
|
|
|
|
<para>This problem usually occurs as a result of someone editing a Makefile
|
|
with a text editor that replaces tab characters with spaces. Command
|
|
lines must start with tabs. This is not specific to Cygwin.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.win32-headers">
|
|
<question><para>Why can't we redistribute Microsoft's Win32 headers?</para></question>
|
|
<answer>
|
|
|
|
<para>Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks
|
|
like it says that one may not "permit further redistribution of the
|
|
Redistributables to their end users". We take this to mean that we can
|
|
give them to you, but you can't give them to anyone else, which is
|
|
something that we can't agree to. Fortunately, we
|
|
have our own Win32 headers which are pretty complete.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.msvs-mingw">
|
|
<question><para>How do I use <literal>cygwin1.dll</literal> with Visual Studio or Mingw-w64?</para></question>
|
|
<answer>
|
|
|
|
<para>Before you begin, note that Cygwin is licensed under the GNU GPL (as
|
|
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
|
|
more information, see <ulink url="http://gnu.org/licenses/gpl-faq.html"/>. If
|
|
that is not a problem, read on.
|
|
</para>
|
|
<para>If you want to load the DLL dynamically, read
|
|
<literal>winsup/cygwin/how-cygtls-works.txt</literal> and the sample code in
|
|
<literal>winsup/testsuite/cygload</literal> to understand how this works.
|
|
The short version is:
|
|
</para>
|
|
<orderedlist><listitem><para>Make sure you have 4K of scratch space at the bottom of your stack.
|
|
</para></listitem>
|
|
<listitem><para>Invoke <literal>cygwin_dll_init()</literal>:
|
|
<screen>
|
|
HMODULE h = LoadLibrary("cygwin1.dll");
|
|
void (*init)() = GetProcAddress(h, "cygwin_dll_init");
|
|
init();
|
|
</screen>
|
|
</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>If you want to link statically from Visual Studio, to my knowledge
|
|
none of the Cygwin developers have done this, but we have this report
|
|
from the mailing list that it can be done this way:
|
|
</para>
|
|
<orderedlist><listitem><para>Use the impdef program to generate a .def file for the cygwin1.dll
|
|
(if you build the cygwin dll from source, you will already have a def
|
|
file)
|
|
</para>
|
|
<screen>
|
|
impdef cygwin1.dll > cygwin1.def
|
|
</screen>
|
|
|
|
</listitem>
|
|
<listitem><para>Use the MS VS linker (lib) to generate an import library
|
|
</para>
|
|
<screen>
|
|
lib /def=cygwin1.def /out=cygwin1.lib
|
|
</screen>
|
|
|
|
</listitem>
|
|
<listitem><para>Create a file "my_crt0.c" with the following contents
|
|
</para>
|
|
<screen>
|
|
#include <sys/cygwin.h>
|
|
#include <stdlib.h>
|
|
|
|
typedef int (*MainFunc) (int argc, char *argv[], char **env);
|
|
|
|
void
|
|
my_crt0 (MainFunc f)
|
|
{
|
|
cygwin_crt0(f);
|
|
}
|
|
</screen>
|
|
|
|
</listitem>
|
|
<listitem><para>Use gcc in a Cygwin prompt to build my_crt0.c into a DLL
|
|
(e.g. my_crt0.dll). Follow steps 1 and 2 to generate .def and
|
|
.lib files for the DLL.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>Download crt0.c from the cygwin website and include it in
|
|
your sources. Modify it to call my_crt0() instead of
|
|
cygwin_crt0().
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>Build your object files using the MS VC compiler cl.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>Link your object files, cygwin1.lib, and my_crt0.lib (or
|
|
whatever you called it) into the executable.
|
|
</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>Note that if you are using any other Cygwin based libraries
|
|
that you will probably need to build them as DLLs using gcc and
|
|
then generate import libraries for the MS VC linker.
|
|
</para>
|
|
<para>Thanks to Alastair Growcott (alastair dot growcott at bakbone dot co
|
|
dot uk) for this tip.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.linking-lib">
|
|
<question><para>How do I link against a <literal>.lib</literal> file?</para></question>
|
|
<answer>
|
|
|
|
<para>If your <literal>.lib</literal> file is a normal static or import library with
|
|
C-callable entry points, you can list <literal>foo.lib</literal> as an object file for
|
|
gcc/g++, just like any <literal>*.o</literal> file. Otherwise, here are some steps:
|
|
</para>
|
|
<orderedlist><listitem><para>Build a C file with a function table. Put all functions you intend
|
|
to use in that table. This forces the linker to include all the object
|
|
files from the .lib. Maybe there is an option to force LINK.EXE to
|
|
include an object file.
|
|
</para></listitem>
|
|
<listitem><para>Build a dummy 'LibMain'.
|
|
</para></listitem>
|
|
<listitem><para>Build a .def with all the exports you need.
|
|
</para></listitem>
|
|
<listitem><para>Link with your .lib using link.exe.
|
|
</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>or
|
|
</para>
|
|
<orderedlist><listitem><para>Extract all the object files from the .lib using LIB.EXE.
|
|
</para></listitem>
|
|
<listitem><para>Build a dummy C file referencing all the functions you need, either
|
|
with a direct call or through an initialized function pointer.
|
|
</para></listitem>
|
|
<listitem><para>Build a dummy LibMain.
|
|
</para></listitem>
|
|
<listitem><para>Link all the objects with this file+LibMain.
|
|
</para></listitem>
|
|
<listitem><para>Write a .def.
|
|
</para></listitem>
|
|
<listitem><para>Link.
|
|
</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>You can use these methods to use MSVC (and many other runtime libs)
|
|
with Cygwin development tools.
|
|
</para>
|
|
<para>Note that this is a lot of work (half a day or so), but much less than
|
|
rewriting the runtime library in question from specs...
|
|
</para>
|
|
<para>Thanks to Jacob Navia (root at jacob dot remcomp dot fr) for this explanation.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.building-cygwin">
|
|
<question><para>How do I build Cygwin on my own?</para></question>
|
|
<answer>
|
|
|
|
<para>First, you need to make sure you have the necessary build tools
|
|
installed; you at least need <literal>gcc-g++</literal>, <literal>make</literal>,
|
|
<literal>perl</literal>, <literal>cocom</literal>, <literal>gettext</literal>, <literal>gettext-devel</literal>,
|
|
and <literal>zlib-devel</literal>.
|
|
Building for 32-bit Cygwin also requires <literal>libiconv</literal>,
|
|
<literal>mingw64-i686-gcc-g++</literal>, <literal>mingw64-i686-zlib</literal>,
|
|
and <literal>mingw64-x86_64-gcc-core</literal>.
|
|
Building for 64-bit Cygwin also requires <literal>libiconv-devel</literal>,
|
|
<literal>mingw64-x86_64-gcc-g++</literal>, and
|
|
<literal>mingw64-x86_64-zlib</literal>.
|
|
If you want to run the tests, <literal>dejagnu</literal> is also required.
|
|
Normally, building ignores any errors in building the documentation,
|
|
which requires the <literal>dblatex</literal>,
|
|
<literal>docbook-xml45</literal>, <literal>docbook-xsl</literal>, and
|
|
<literal>xmlto</literal> packages. For more information on building the
|
|
documentation, see the README included in the <literal>cygwin-doc</literal> package.
|
|
</para>
|
|
|
|
<para>Next, get the Cygwin source. Ideally, you should check out what you
|
|
need from GIT (<ulink url="https://cygwin.com/git.html"/>). This is the
|
|
<emphasis>preferred method</emphasis> for acquiring the sources. Otherwise,
|
|
if you are trying to duplicate a cygwin release then you should download the
|
|
corresponding source package
|
|
(<literal>cygwin-x.y.z-n-src.tar.bz2</literal>). </para>
|
|
|
|
<para>You <emphasis>must</emphasis> build cygwin in a separate directory from
|
|
the source, so create something like a <literal>build/</literal> directory.
|
|
Assuming you checked out the source in <literal>/oss/src/</literal>, and you
|
|
also want to install to the temporary location <literal>install</literal>:
|
|
</para>
|
|
<screen>
|
|
mkdir /oss/build
|
|
mkdir /oss/install
|
|
cd build
|
|
(/oss/src/configure --prefix=/oss/install -v; make) >& make.out
|
|
make install > install.log 2>&1
|
|
</screen>
|
|
|
|
<para>
|
|
If the build works, install everything <emphasis>except</emphasis> the dll (if
|
|
you can). Then, close down all cygwin programs (including bash windows,
|
|
inetd, etc.), save your old dll, and copy the new dll to the correct
|
|
place. Then start up a bash window, or run a cygwin program from the
|
|
Windows command prompt, and see what happens.
|
|
</para>
|
|
<para>If you get the error "shared region is corrupted" it means that two
|
|
different versions of cygwin1.dll are running on your machine at the
|
|
same time. Remove all but one.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.debugging-cygwin">
|
|
<question><para>I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?</para></question>
|
|
<answer>
|
|
|
|
<para>Debugging symbols are stripped from distibuted Cygwin binaries, so to
|
|
debug with <command>gdb</command> you will need to install the
|
|
<package>cygwin-debuginfo</package> package to obtain the debug symbols for
|
|
<filename>cygwin1.dll</filename>
|
|
</para>
|
|
|
|
<para>
|
|
If your bug causes an exception inside <filename>cygwin1.dll</filename> you will
|
|
need to use the <command>gdb</command> command <userinput>set cygwin-exceptions
|
|
on</userinput> to tell <command>gdb</command> to stop on exceptions inside the
|
|
Cygwin DLL (by default they are ignored, as they may be generated during normal
|
|
operation e.g. when checking a pointer is valid)
|
|
</para>
|
|
|
|
<para>
|
|
It is also a good
|
|
idea to use the latest code in case the bug has been fixed, so we
|
|
recommend trying the latest snapshot from
|
|
<ulink url="https://cygwin.com/snapshots/"/> or building the DLL from git.
|
|
</para>
|
|
|
|
<para>To build a debugging version of the Cygwin DLL, you will need to follow
|
|
the instructions at <ulink url="https://cygwin.com/faq/faq.html#faq.programming.building-cygwin"/>.
|
|
</para>
|
|
|
|
<para>
|
|
You can also contact the mailing list for pointers (a simple test case that
|
|
demonstrates the bug is always welcome).
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.compiling-unsupported">
|
|
<question><para>How can I compile Cygwin for an unsupported platform (PowerPC, Alpha, ARM, Itanium)?</para></question>
|
|
<answer>
|
|
|
|
<para>Unfortunately, this will be difficult. Exception handling and signals
|
|
support semantics and args have been designed for x86 so you would need
|
|
to write specific support for your platform. We don't know of any other
|
|
incompatibilities. Please send us patches if you do this work!
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.adjusting-heap">
|
|
<question><para>How can I adjust the heap/stack size of an application?</para></question>
|
|
<answer>
|
|
|
|
<para>If you need to change the maximum amount of memory available to Cygwin, see
|
|
<ulink url="https://cygwin.com/cygwin-ug-net/setup-maxmem.html"/>. Otherwise,
|
|
just pass heap/stack linker arguments to gcc. To create foo.exe with
|
|
a heap size of 200MB and a stack size of 8MB, you would invoke
|
|
gcc as:
|
|
</para>
|
|
<para><literal>gcc -Wl,--heap,200000000,--stack,8000000 -o foo foo.c</literal>
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.dll-cygcheck">
|
|
<question><para>How can I find out which DLLs are needed by an executable?</para></question>
|
|
<answer>
|
|
|
|
<para><literal>objdump -p</literal> provides this information, but is rather verbose.
|
|
</para>
|
|
<para><literal>cygcheck</literal> will do this much more concisely, and operates
|
|
recursively, provided the command is in your path.
|
|
</para>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.dll-building">
|
|
<question><para>How do I build a DLL?</para></question>
|
|
<answer>
|
|
|
|
<para>There's documentation that explains the process in the Cygwin User's
|
|
Guide here: <ulink url="https://cygwin.com/cygwin-ug-net/dll.html"/>.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.breakpoint">
|
|
<question><para>How can I set a breakpoint at MainCRTStartup?</para></question>
|
|
<answer>
|
|
|
|
<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
|
|
</para>
|
|
<para>Set a breakpoint at *0x401000 in gdb and then run the program in
|
|
question.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.debug">
|
|
<question><para>How can I debug what's going on?</para></question>
|
|
<answer>
|
|
|
|
<para>You can debug your application using <literal>gdb</literal>. Make sure you
|
|
compile it with the -g flag! If your application calls functions in
|
|
MS DLLs, gdb will complain about not being able to load debug information
|
|
for them when you run your program. This is normal since these DLLs
|
|
don't contain debugging information (and even if they did, that debug
|
|
info would not be compatible with gdb).
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.system-trace">
|
|
<question><para>Can I use a system trace mechanism instead?</para></question>
|
|
<answer>
|
|
|
|
<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.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.gdb-signals">
|
|
<question><para>How does gdb handle signals?</para></question>
|
|
<answer>
|
|
|
|
<para>
|
|
gdb maps known Windows exceptions to signals such as SIGSEGV, SIGFPE, SIGTRAP,
|
|
SIGINT and SIGILL. Other Windows exceptions are passed on to the handler (if
|
|
any), and reported as an unknown signal if an unhandled (second chance)
|
|
exception occurs.
|
|
</para>
|
|
|
|
<para>
|
|
There is also an experimental feature to notify gdb of purely Cygwin signals
|
|
like SIGABRT, SIGHUP or SIGUSR1. This currently has some known problems, for
|
|
example, single-stepping from these signals may not work as expected.
|
|
</para>
|
|
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.linker">
|
|
<question><para>The linker complains that it can't find something.</para></question>
|
|
<answer>
|
|
|
|
<para>A common error is to put the library on the command line before
|
|
the thing that needs things from it.
|
|
</para>
|
|
<para>This is wrong <literal>gcc -lstdc++ hello.cc</literal>.
|
|
This is right <literal>gcc hello.cc -lstdc++</literal>.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.stat64">
|
|
<question><para>Why do I get an error using <literal>struct stat64</literal>?</para></question>
|
|
<answer>
|
|
|
|
<para><literal>struct stat64</literal> is not used in Cygwin, just
|
|
use <literal>struct stat</literal>. It's 64 bit aware.</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.libc">
|
|
<question><para>Can you make DLLs that are linked against libc ?</para></question>
|
|
<answer>
|
|
|
|
<para>Yes.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.malloc-h">
|
|
<question><para>Where is malloc.h?</para></question>
|
|
<answer>
|
|
|
|
<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>
|
|
|
|
<qandaentry id="faq.programming.own-malloc">
|
|
<question><para>Can I use my own malloc?</para></question>
|
|
<answer>
|
|
|
|
<para>If you define a function called <literal>malloc</literal> in your own code, and link
|
|
with the DLL, the DLL <emphasis>will</emphasis> call your <literal>malloc</literal>. Needless to
|
|
say, you will run into serious problems if your malloc is buggy.
|
|
</para>
|
|
<para>If you run any programs from the DOS command prompt, rather than from in
|
|
bash, the DLL will try and expand the wildcards on the command line.
|
|
This process uses <literal>malloc</literal> <emphasis>before</emphasis> your main line is started.
|
|
If you have written your own <literal>malloc</literal> to need some initialization
|
|
to occur after <literal>main</literal> is called, then this will surely break.
|
|
</para>
|
|
<para>Moreover, there is an outstanding issue with <literal>_malloc_r</literal> in
|
|
<literal>newlib</literal>. This re-entrant version of <literal>malloc</literal> will be called
|
|
directly from within <literal>newlib</literal>, by-passing your custom version, and
|
|
is probably incompatible with it. But it may not be possible to replace
|
|
<literal>_malloc_r</literal> too, because <literal>cygwin1.dll</literal> does not export it and
|
|
Cygwin does not expect your program to replace it. This is really a
|
|
newlib issue, but we are open to suggestions on how to deal with it.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.msvc-gcc-objects">
|
|
<question><para>Can I mix objects compiled with msvc++ and gcc?</para></question>
|
|
<answer>
|
|
|
|
<para>Yes, but only if you are combining C object files. MSVC C++ uses a
|
|
different mangling scheme than GNU C++, so you will have difficulties
|
|
combining C++ objects.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.gdb-msvc">
|
|
<question><para>Can I use the gdb debugger to debug programs built by VC++?</para></question>
|
|
<answer>
|
|
|
|
<para>No, not for full (high level source language) debugging.
|
|
The Microsoft compilers generate a different type of debugging
|
|
symbol information, which gdb does not understand.
|
|
</para>
|
|
<para>However, the low-level (assembly-type) symbols generated by
|
|
Microsoft compilers are coff, which gdb DOES understand.
|
|
Therefore you should at least be able to see all of your
|
|
global symbols; you just won't have any information about
|
|
data types, line numbers, local variables etc.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.make-scripts">
|
|
<question><para>Shell scripts aren't running properly from my makefiles?</para></question>
|
|
<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.) 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 macros do I need to know about?</para></question>
|
|
<answer>
|
|
|
|
<para>gcc for Cygwin defines __CYGWIN__ when building for a Cygwin
|
|
environment.
|
|
</para>
|
|
<para>Microsoft defines the preprocessor symbol _WIN32 in their Windows
|
|
development environment.
|
|
</para>
|
|
<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
|
|
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>Check out the predefined symbols in detail by running, for example
|
|
</para>
|
|
<screen>
|
|
$ gcc -dM -E -xc /dev/null >gcc.txt
|
|
$ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt
|
|
</screen>
|
|
<para>Then use the diff and grep utilities to check what the difference is.
|
|
</para>
|
|
</answer></qandaentry>
|
|
|
|
<qandaentry id="faq.programming.unix-gui">
|
|
<question><para>How should I port my Unix GUI to Windows?</para></question>
|
|
<answer>
|
|
|
|
<para>Like other Unix-like platforms, the Cygwin distribtion includes many of
|
|
the common GUI toolkits, including X11, X Athena widgets, Motif, Tk, GTK+,
|
|
and Qt. Many programs which rely on these toolkits will work with little, if
|
|
any, porting work if they are otherwise portable. However, there are a few
|
|
things to look out for:</para>
|
|
<orderedlist>
|
|
<listitem><para>Some packages written for both Windows and X11 incorrectly
|
|
treat Cygwin as a Windows platform rather than a Unix variant. Mixing Cygwin's
|
|
Unix APIs with Windows' GDI is best avoided; rather, remove these assumptions
|
|
so that Cygwin is treated like other X11 platforms.</para></listitem>
|
|
<listitem><para>GTK+ programs which use <literal>gtk_builder_connect_signals()</literal>
|
|
or <literal>glade_xml_signal_autoconnect()</literal> need to be able to
|
|
<literal>dlopen()</literal> themselves. In order for this to work, the program
|
|
must be linked with the <literal>-Wl,--export-all-symbols</literal> linker flag.
|
|
This can be added to LDFLAGS manually, or handled automatically with the
|
|
<literal>-export-dynamic</literal> libtool flag (requires libtool 2.2.8) or
|
|
by adding <literal>gmodule-export-2.0</literal> to the pkg-config modules used
|
|
to build the package.</para></listitem>
|
|
<listitem><para>Programs which include their own loadable modules (plugins)
|
|
often must have its modules linked against the symbols in the program. The
|
|
most portable solution is for such programs to provide all its symbols (except
|
|
for <literal>main()</literal>) in a shared library, against which the plugins
|
|
can be linked. Otherwise, the symbols from the executable itself must be
|
|
exported.</para>
|
|
<para>If the package uses the CMake build system, this can be done by adding
|
|
<literal>ENABLE_EXPORTS TRUE</literal> to the executable's <literal>set_target_properties</literal>
|
|
command, then adding the executable's target name to the <literal>target_link_libraries</literal>
|
|
command for the plugins.</para>
|
|
<para>For other build systems, the following steps are required:</para>
|
|
<orderedlist>
|
|
<listitem><para>The executable must be built before its plugins.</para></listitem>
|
|
<listitem><para>Symbols must be exported from the executable with a
|
|
<literal>-Wl,--export-all-symbols,--out-implib,libfoo.exe.a</literal>
|
|
linker flag, where <literal>foo</literal> represents the name of the
|
|
executable.</para></listitem>
|
|
<listitem><para>The plugins must be linked with a <literal>-Wl,/path/to/libfoo.exe.a</literal>
|
|
linker flag.</para></listitem>
|
|
</orderedlist></listitem></orderedlist>
|
|
</answer></qandaentry>
|
|
|
|
</qandadiv>
|