1 @section Programming Questions
3 @subsection Why are compiled executables so huge?!?
5 By default, gcc compiles in all symbols. You'll also find that gcc
6 creates large executables on UNIX.
8 If that bothers you, just use the 'strip' program, part of the binutils
9 package. Or compile with the @samp{-s} option to gcc.
11 @subsection Where is glibc?
13 Cygwin does not provide glibc. It uses newlib instead, which provides
14 much (but not all) of the same functionality. Porting glibc to Cygwin
17 @subsection Why is make behaving badly?
19 @strong{(Please note: This section has not yet been updated for the latest
22 Starting with the beta 19 release, make defaults to a win32 mode in
23 which backslashes in filenames are permitted and cmd.exe/command.com
24 is used as the sub-shell. In this mode, escape characters aren't
25 allowed among other restrictions. For this reason, you must set
26 the environment variable MAKE_MODE to UNIX to run make on ordinary Unix
27 Makefiles. Here is the full scoop:
29 MAKE_MODE selects between native Win32 make mode (the default) and
30 a Unix mode where it behaves like a Unix make. The Unix mode does
31 allow specifying Win32-style paths but only containing forward slashes
32 as the path separator. The path list separator character is a colon
35 Win32 mode expects path separators to be either / or \. Thus no
36 Unix-style \s as escape are allowed. Win32 mode also uses
37 cmd.exe/command.com as the subshell which means "copy" and "del"
38 (and other shell builtins) will work. The path list separator
39 character is semi-colon in Win32 mode. People who want an nmake-like
40 make might want to use this mode but no one should expect Unix
41 Makefiles to compile in this mode. That is why the default b19
42 install sets MAKE_MODE to UNIX.
44 @subsection Why the undefined reference to "WinMain@@16"?
46 @strong{(Please note: This section has not yet been updated for the latest
49 Try adding an empty main() function to one of your sources.
51 @subsection How do I use Win32 API calls?
53 @strong{(Please note: This section has not yet been updated for the latest
56 It's pretty simple actually. Cygwin tools require that you explicitly
57 link the import libraries for whatever Win32 API functions that you
58 are going to use, with the exception of kernel32, which is linked
59 automatically (because the startup and/or built-in code uses it).
61 For example, to use graphics functions (GDI) you must link
64 gcc -o foo.exe foo.o bar.o -lgdi32
66 or (compiling and linking in one step):
68 gcc -o foo.exe foo.c bar.c -lgdi32
70 The following libraries are available for use in this way:
72 advapi32 largeint ole32 scrnsave vfw32
73 cap lz32 oleaut32 shell32 win32spl
74 comctl32 mapi32 oledlg snmp winmm
75 comdlg32 mfcuia32 olepro32 svrapi winserve
76 ctl3d32 mgmtapi opengl32 tapi32 winspool
77 dlcapi mpr penwin32 th32 winstrm
78 gdi32 msacm32 pkpd32 thunk32 wow32
79 glaux nddeapi rasapi32 url wsock32
80 glu32 netapi32 rpcdce4 user32 wst
81 icmp odbc32 rpcndr uuid
82 imm32 odbccp32 rpcns4 vdmdbg
83 kernel32 oldnames rpcrt4 version
85 The regular setup allows you to use the option -mwindows on the
86 command line to include a set of the basic libraries (and also
87 make your program a GUI program instead of a console program),
88 including user32, gdi32 and, IIRC, comdlg32.
90 Note that you should never include -lkernel32 on your link line
91 unless you are invoking ld directly. Do not include the same import
92 library twice on your link line. Finally, it is a good idea to
93 put import libraries last on your link line, or at least after
94 all the object files and static libraries that reference them.
96 The first two are related to problems the linker has (as of b18 at least)
97 when import libraries are referenced twice. Tables get messed up and
98 programs crash randomly. The last point has to do with the fact that
99 gcc processes the files listed on the command line in sequence and
100 will only resolve references to libraries if they are given after
101 the file that makes the reference.
103 @subsection How do I compile a Win32 executable that doesn't use Cygwin?
105 The -mno-cygwin flag to gcc makes gcc link against standard Microsoft
106 DLLs instead of Cygwin. This is desirable for native Windows programs
107 that don't need a UNIX emulation layer.
109 This is not to be confused with 'MinGW' (Minimalist GNU for Windows),
110 which is a completely separate effort. That project's home page is
111 @file{http://www.mingw.org/index.shtml}.
113 @subsection Can I link with both MSVCRT*.DLL and cygwin1.dll?
115 No, you must use one or the other, they are mutually exclusive.
117 @subsection How do I make the console window go away?
119 The default during compilation is to produce a console application.
120 It you are writing a GUI program, you should either compile with
121 -mwindows as explained above, or add the string
122 "-Wl,--subsystem,windows" to the GCC commandline.
124 @subsection Why does make complain about a "missing separator"?
126 This problem usually occurs as a result of someone editing a Makefile
127 with a text editor that replaces tab characters with spaces. Command
128 lines must start with tabs. This is not specific to Cygwin.
130 @subsection Why can't we redistribute Microsoft's Win32 headers?
132 Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks
133 like it says that one may not "permit further redistribution of the
134 Redistributables to their end users". We take this to mean that we can
135 give them to you, but you can't give them to anyone else, which is
136 something that Cygnus (err... Red Hat) can't agree to. Fortunately, we
137 have our own Win32 headers which are pretty complete.
139 @subsection How do I link against .lib files?
141 @strong{(Please note: This section has not yet been updated for the latest
144 1. Build a C file with a function table. Put all functions you intend
145 to use in that table. This forces the linker to include all the object
146 files from the .lib. Maybe there is an option to force LINK.EXE to
147 include an object file.
148 2. Build a dummy 'LibMain'.
149 3. Build a .def with all the exports you need.
150 4. Link with your .lib using link.exe.
154 1. Extract all the object files from the .lib using LIB.EXE.
155 2. Build a dummy C file referencing all the functions you need, either
156 with a direct call or through an initialized function pointer.
157 3. Build a dummy LibMain.
158 4. Link all the objects with this file+LibMain.
162 You can use these methods to use MSVC (and many other runtime libs)
163 with Cygwin development tools.
165 Note that this is a lot of work (half a day or so), but much less than
166 rewriting the runtime library in question from specs...
168 (thanks to Jacob Navia (root@@jacob.remcomp.fr) for this explanation)
170 @subsection How do I rebuild the tools on my NT box?
172 @strong{Note:} You must build in a directory @emph{outside} the source
175 Assuming that you have the src installed as /src, will build in
176 the directory /obj, and want to install the tools in /install:
181 /src/configure --prefix=/install -v > configure.log 2>&1
183 make install > install.log 2>&1
186 Normally, this will also attempt to build the documentation, which
187 additionally requires db2html, texi2html and possibly others.
188 These tools are not included in the Cygwin distribution, but are readily
193 Part of docbook, from @file{http://sources.redhat.com/docbook-tools/}.
195 From @file{http://www.mathematik.uni-kl.de/~obachman/Texi2html/}.
198 To check a cygwin1.dll, run "make check" in the winsup/cygwin directory.
199 If that works, install everything @emph{except} the dll (if you can).
200 Then, close down all cygwin programs (including bash windows, inetd,
201 etc.), save your old dll, and copy the new dll to @emph{all} the
202 places where the old dll was (if there is more than one on your
203 machine). Then start up a bash window and see what happens. (Or better,
204 run a cygwin program from the Windows command prompt.)
206 If you get the error "shared region is corrupted" it means that two
207 different versions of cygwin1.dll are running on your machine at the
210 @subsection How can I compile a powerpc NT toolchain?
212 @strong{(Please note: This section has not yet been updated for the latest
215 Unfortunately, this will be difficult. It hasn't been built for
216 some time (late 1996) since Microsoft has dropped development of
217 powerpc NT. Exception handling/signals support semantics/args have been
218 changed for x86 and not updated for ppc so the ppc specific support would
219 have to be rewritten. We don't know of any other incompatibilities.
220 Please send us patches if you do this work!
222 @subsection How can I compile an Alpha NT toolchain?
224 @strong{(Please note: This section has not yet been updated for the latest
227 We have not ported the tools to Alpha NT and do not have plans to
228 do so at the present time. We would be happy to add support
229 for Alpha NT if someone contributes the changes to us.
231 @subsection How can I adjust the heap/stack size of an application?
233 @strong{(Please note: This section has not yet been updated for the latest
236 Pass heap/stack linker arguments to gcc. To create foo.exe with
237 a heap size of 1024 and a stack size of 4096, you would invoke
240 @code{gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c}
242 @subsection How can I find out which dlls are needed by an executable?
244 @samp{objdump -p} provides this information, but is rather verbose.
246 @samp{cygcheck} will do this much more concisely, and operates
247 recursively, provided the command is in your path.
249 Note there is currently a bug in cygcheck in that it will not report
250 on a program in a Windows system dir (e.g., C:\Windows or C:\WINNT) even
251 if it's in your path. To work around this, supply the full Win32 path
252 to the executable, including the .exe extension:
255 cygcheck c:\\winnt\\system32\\cmd.exe
258 (Note the windows path separator must be escaped if this is typed in
261 @subsection How do I build a DLL?
263 @strong{(Please note: This section has not yet been updated for the latest
266 There's documentation that explains the process on the main Cygwin
267 project web page (http://sources.redhat.com/cygwin/).
269 @subsection How can I set a breakpoint at MainCRTStartup?
271 @strong{(Please note: This section has not yet been updated for the latest
274 Set a breakpoint at *0x401000 in gdb and then run the program in
277 @subsection How can I build a relocatable dll?
279 @strong{(Please note: This section has not yet been updated for the
280 latest net release. However, there was a discussion on the cygwin
281 mailing list recently that addresses this issue. Read
282 @file{http://sources.redhat.com/ml/cygwin/2000-06/msg00688.html} and
285 You must execute the following sequence of five commands, in this
289 $(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY
291 $(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \
292 --base-file BASEFILE --output-exp EXPFILE
294 $(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY
296 $(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \
297 --base-file BASEFILE --output-exp EXPFILE
299 $(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY
302 In this example, $(LD) is the linker, ld.
304 $(DLLTOOL) is dlltool.
306 $(AS) is the assembler, as.
308 DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll.
310 OBJS is the list of object files you want to put into the DLL.
312 LIBS is the list of libraries you want to link the DLL against. For
313 example, you may or may not want -lcygwin. You may want -lkernel32.
314 Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32
317 DEFFILE is the name of your definitions file. A simple DEFFILE would
318 consist of ``EXPORTS'' followed by a list of all symbols which should
319 be exported from the DLL. Each symbol should be on a line by itself.
320 Other programs will only be able to access the listed symbols.
322 BASEFILE is a temporary file that is used during this five stage
323 process, e.g., tcl.base.
325 EXPFILE is another temporary file, e.g., tcl.exp.
327 ENTRY is the name of the function which you want to use as the entry
328 point. This function should be defined using the WINAPI attribute,
329 and should take three arguments:
330 int WINAPI startup (HINSTANCE, DWORD, LPVOID)
332 This means that the actual symbol name will have an appended @@12, so if
333 your entry point really is named @samp{startup}, the string you should
334 use for ENTRY in the above examples would be @samp{startup@@12}.
336 If your DLL calls any Cygwin API functions, the entry function will need
337 to initialize the Cygwin impure pointer. You can do that by declaring
338 a global variable @samp{_impure_ptr}, and then initializing it in the
339 entry function. Be careful not to export the global variable
340 @samp{_impure_ptr} from your DLL; that is, do not put it in DEFFILE.
343 /* This is a global variable. */
344 struct _reent *_impure_ptr;
345 extern struct _reent *__imp_reent_data;
347 int entry (HINSTANT hinst, DWORD reason, LPVOID reserved)
349 _impure_ptr = __imp_reent_data;
350 /* Whatever else you want to do. */
354 You may put an optional `--subsystem windows' on the $(LD) lines. The
355 Tcl build does this, but I admit that I no longer remember whether
356 this is important. Note that if you specify a --subsytem <x> flag to ld,
357 the -e entry must come after the subsystem flag, since the subsystem flag
358 sets a different default entry point.
360 You may put an optional `--image-base BASEADDR' on the $(LD) lines.
361 This will set the default image base. Programs using this DLL will
362 start up a bit faster if each DLL occupies a different portion of the
363 address space. Each DLL starts at the image base, and continues for
364 whatever size it occupies.
366 Now that you've built your DLL, you may want to build a library so
367 that other programs can link against it. This is not required: you
368 could always use the DLL via LoadLibrary. However, if you want to be
369 able to link directly against the DLL, you need to create a library.
372 $(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE
374 $(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above. Make
375 sure you use the same DLLNAME and DEFFILE, or things won't work right.
377 LIBFILE is the name of the library you want to create, e.g.,
378 libtcl80.a. You can then link against that library using something
379 like -ltcl80 in your linker command.
381 @subsection How can I debug what's going on?
383 You can debug your application using @code{gdb}. Make sure you
384 compile it with the -g flag! If your application calls functions in
385 MS dlls, gdb will complain about not being able to load debug information
386 for them when you run your program. This is normal since these dlls
387 don't contain debugging information (and even if they did, that debug
388 info would not be compatible with gdb).
390 @subsection Can I use a system trace mechanism instead?
392 Yes. You can use the @code{strace.exe} utility to run other cygwin
393 programs with various debug and trace messages enabled. For information
394 on using @code{strace}, see the Cygwin User's Guide or the file
395 @code{winsup/utils/utils.sgml}.
397 Alternatively, you can set the @code{STRACE} environment variable to
398 @code{1}, and get a whole load of debug information on your screen
399 whenever a Cygwin app runs. This is an especially useful tool to use
400 when tracking bugs down inside the Cygwin library. @code{STRACE} can be
401 set to different values to achieve different amounts of granularity.
402 You can set it to @code{0x10} for information about syscalls or
403 @code{0x800} for signal/process handling-related info, to name two. The
404 strace mechanism is well documented in the Cygwin library sources in the
405 file @code{winsup/cygwin/include/sys/strace.h}.
407 @subsection Why doesn't gdb handle signals?
409 Unfortunately, there is only minimal signal handling support in gdb
410 currently. Signal handling only works with Windows-type signals.
411 SIGINT may work, SIGFPE may work, SIGSEGV definitely does. You cannot
412 'stop', 'print' or 'nopass' signals like SIGUSR1 or SIGHUP to the
413 process being debugged.
415 @subsection The linker complains that it can't find something.
417 @strong{(Please note: This section has not yet been updated for the latest
420 A common error is to put the library on the command line before
421 the thing that needs things from it.
423 This is wrong @code{gcc -lstdc++ hello.cc}.
424 This is right @code{gcc hello.cc -lstdc++}.
426 @subsection I use a function I know is in the API, but I still get a link error.
428 @strong{(Please note: This section has not yet been updated for the latest
431 The function probably isn't declared in the header files, or
432 the UNICODE stuff for it isn't filled in.
434 @subsection Can you make DLLs that are linked against libc ?
436 @strong{(Please note: This section has not yet been updated for the latest
441 @subsection Where is malloc.h?
443 @strong{(Please note: This section has not yet been updated for the latest
446 Include stdlib.h instead of malloc.h.
448 @subsection Can I use my own malloc?
450 If you define a function called @code{malloc} in your own code, and link
451 with the DLL, the DLL @emph{will} call your @code{malloc}. Needless to
452 say, you will run into serious problems if your malloc is buggy.
454 If you run any programs from the DOS command prompt, rather than from in
455 bash, the DLL will try and expand the wildcards on the command line.
456 This process uses @code{malloc} @emph{before} your main line is started.
457 If you have written your own @code{malloc} to need some initialization
458 to occur after @code{main} is called, then this will surely break.
460 Moreover, there is an outstanding issue with @code{_malloc_r} in
461 @code{newlib}. This re-entrant version of @code{malloc} will be called
462 directly from within @code{newlib}, by-passing your custom version, and
463 is probably incompatible with it. But it may not be possible to replace
464 @code{_malloc_r} too, because @code{cygwin1.dll} does not export it and
465 Cygwin does not expect your program to replace it. This is really a
466 newlib issue, but we are open to suggestions on how to deal with it.
468 @subsection Can I mix objects compiled with msvc++ and gcc?
470 Yes, but only if you are combining C object files. MSVC C++ uses a
471 different mangling scheme than GNU C++, so you will have difficulties
472 combining C++ objects.
474 @subsection Can I use the gdb debugger to debug programs built by VC++?
476 No, not for full (high level source language) debugging.
477 The Microsoft compilers generate a different type of debugging
478 symbol information, which gdb does not understand.
480 However, the low-level (assembly-type) symbols generated by
481 Microsoft compilers are coff, which gdb DOES understand.
482 Therefore you should at least be able to see all of your
483 global symbols; you just won't have any information about
484 data types, line numbers, local variables etc.
486 @subsection Where can I find info on x86 assembly?
488 CPU reference manuals for Intel's current chips are available in
489 downloadable PDF form on Intel's web site:
491 @file{http://developer.intel.com/design/pro/manuals/}
493 @subsection Shell scripts aren't running properly from my makefiles?
495 If your scripts are in the current directory, you must have @samp{.}
496 (dot) in your $PATH. (It is not normally there by default.) Otherwise,
497 you would need to add /bin/sh in front of each and every shell script
498 invoked in your Makefiles.
500 @subsection What preprocessor do I need to know about?
502 @strong{(Please note: This section has not yet been updated for the latest
505 We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for
506 access to the Cygwin environment provided by the dll.
508 We chose _WIN32 because this is what Microsoft defines in VC++ and
509 we thought it would be a good idea for compatibility with VC++ code
510 to follow their example. We use _MFC_VER to indicate code that should
511 be compiled with VC++.
513 @subsection Where can I get f77 and objc components for B20 EGCS 1.1?
515 @strong{(Please note: This section has not yet been updated for the latest
518 B20-compatible versions of the f77 and objc components are available
519 from @file{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/}.
521 @subsection How should I port my Unix GUI to Windows?
523 @strong{(Please note: This section has not yet been updated for the latest
526 There are two basic strategies for porting Unix GUIs to Windows.
528 The first is to use a portable graphics library such as tcl/tk, X11, or
529 V (and others?). Typically, you will end up with a GUI on Windows that
530 requires some runtime support. With tcl/tk, you'll want to include the
531 necessary library files and the tcl/tk DLLs. In the case of X11, you'll
532 need everyone using your program to have an X11 server installed.
534 The second method is to rewrite your GUI using Win32 API calls (or MFC
535 with VC++). If your program is written in a fairly modular fashion, you
536 may still want to use Cygwin if your program contains a lot of shared
537 (non-GUI-related) code. That way you still gain some of the portability
538 advantages inherent in using Cygwin.
540 @subsection Why not use DJGPP ?
542 DJGPP is a similar idea, but for DOS instead of Win32. DJGPP uses a
543 "DOS extender" to provide a more reasonable operating interface for its
544 applications. The Cygwin toolset doesn't have to do this since all of
545 the applications are native WIN32. Applications compiled with the
546 Cygwin tools can access the Win32 API functions, so you can write
547 programs which use the Windows GUI.
549 You can get more info on DJGPP by following
550 @file{http://www.delorie.com/}.