diff options
Diffstat (limited to 'winsup/doc/how-programming.texinfo')
| -rw-r--r-- | winsup/doc/how-programming.texinfo | 686 |
1 files changed, 0 insertions, 686 deletions
diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo deleted file mode 100644 index 8c548af49..000000000 --- a/winsup/doc/how-programming.texinfo +++ /dev/null @@ -1,686 +0,0 @@ -@section Programming Questions - -@subsection How do I contribute a package? - -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. - -The Cygwin Package Contributor's Guide is at -@file{http://cygwin.com/setup.html}, which details everything you need -to know about being a package maintainer. Use the cygwin-apps mailing -list (start at @file{http://cygwin.com/lists.html}) for -questions about package maintenance, @emph{after} searching and browsing the -cygwin-apps list archives, of course. Charles Wilson posted a short -recipe of what is involved, using texinfo as an example, available at -@file{http://cygwin.com/ml/cygwin-apps/2000-11/msg00055.html}. This -should give you an idea of what is required. - -You should announce your intentions to the general cygwin list, in case -others were thinking the same thing. - -@subsection How do I contribute to Cygwin? - -If you want to contribute to Cygwin itself, see -@file{http://cygwin.com/contrib.html}. - -@subsection Why are compiled executables so huge?!? - -By default, gcc compiles in all symbols. You'll also find that gcc -creates large executables on UNIX. - -If that bothers you, just use the 'strip' program, part of the binutils -package. Or compile with the @samp{-s} option to gcc. - -@subsection Where is glibc? - -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. - -@subsection Where is Objective C? - -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. - -@subsection Why is make behaving badly? - -First of all, if you are using @samp{make -j[N]}, then stop. It doesn't -work well. - -Otherwise, read on... - -Make has two operating modes, UNIX and WIN32. You need to make sure -that you are operating in the right mode. - -In UNIX mode, make uses sh.exe as a subshell. The path list separator -is ':', '\' is the escape character, POSIX paths are expected, and -Cygwin mounts will be understood. Use this for Makefiles written for -UNIX. - -In WIN32 mode, make uses the "native" command shell (cmd.exe or -command.com), with all the restrictions that implies. The path list -separator is ';', the path separator is '\', "copy" and "del" work, but -the Cygwin mount table is not understood. Use this for nmake-style -Makefiles. - -The default mode for the Net Release of make (the one installed by -@code{setup.exe}) is UNIX. The default mode for commercial releases to -Redhat (formerly Cygnus) customers is WIN32. - -You can override the default by setting the environment variable -MAKE_MODE to "UNIX" (actually case is not significant) or "WIN32" -(actually anything other than "UNIX"). You can also specify the options ---unix or --win32 on the make command line. - -@subsection Why the undefined reference to @samp{WinMain@@16}? - -If you're using @samp{gcc}, try adding an empty main() function to one -of your sources. Or, perhaps you have @samp{-lm} too early in the -link command line. It should be at the end: - -@example - bash$ gcc hello.c -lm - bash$ ./a.exe - Hello World! -@end example - -works, but - -@example - 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 -@end example - -This is an artifact of libm.a being a symbolic link to libcygwin.a. - -If you're using GCJ, you need to pass a "--main" flag: - -@example -gcj --main=Hello Hello.java -@end example - -@subsection How do I use Win32 API calls? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -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 -automatically (because the startup and/or built-in code uses it). - -For example, to use graphics functions (GDI) you must link -with gdi32 like this: - -gcc -o foo.exe foo.o bar.o -lgdi32 - -or (compiling and linking in one step): - -gcc -o foo.exe foo.c bar.c -lgdi32 - -The following libraries are available for use in this way: - -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 - -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. - -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. - -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. - -@subsection How do I compile a Win32 executable that doesn't use Cygwin? - -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. - -This is not to be confused with 'MinGW' (Minimalist GNU for Windows), -which is a completely separate effort. That project's home page is -@file{http://www.mingw.org/index.shtml}. - -@subsection Can I build a Cygwin program that does not require cygwin1.dll at runtime? - -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. - -If this is an issue because you intend to distribute your Cygwin -application, then you had better read and understand -@file{http://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. - -@subsection Can I link with both MSVCRT*.DLL and cygwin1.dll? - -No, you must use one or the other, they are mutually exclusive. - -@subsection How do I make the console window go away? - -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. - -@subsection Why does make complain about a "missing separator"? - -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. - -@subsection Why can't we redistribute Microsoft's Win32 headers? - -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 Red Hat can't agree to. Fortunately, we -have our own Win32 headers which are pretty complete. - -@subsection How do I link against @samp{cygwin1.dll} with 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: - -@enumerate -@item 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) - -@example -impdef cygwin1.dll > cygwin1.def -@end example - -@item Use the MS VS linker (lib) to generate an import library - -@example -lib /def=cygwin1.def /out=cygwin1.lib -@end example - -@item Create a file "my_crt0.c" with the following contents - -@example -#include <sys/cygwin.h> -#include <stdlib.h> - -typedef int (*MainFunc) (int argc, char *argv[], char **env); - -void - my_crt0 (MainFunc f) - @{ - cygwin_crt0(f); - @} -@end example - -@item 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. - -@item Download crt0.c from the cygwin website and include it in - your sources. Modify it to call my_crt0() instead of - cygwin_crt0(). Since you are using Cygwin source code, your - resulting program will be licensed under the GNU GPL. For more - information, see @file{http://gnu.org/licenses/gpl-faq.html}. - -@item Build your object files using the MS VC compiler cl. - -@item Link your object files, cygwin1.lib, and my_crt0.lib (or - whatever you called it) into the executable. -@end enumerate - -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. - -Thanks to Alastair Growcott (alastair dot growcott at bakbone dot co -dot uk) for this tip. - -@subsection How do I link against a @samp{.lib} file? - -If your @samp{.lib} file is a normal static or import library with -C-callable entry points, you can list @samp{foo.lib} as an object file for -gcc/g++, just like any @samp{*.o} file. Otherwise, here are some steps: - -@enumerate -@item 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. -@item Build a dummy 'LibMain'. -@item Build a .def with all the exports you need. -@item Link with your .lib using link.exe. -@end enumerate - -or - -@enumerate -@item Extract all the object files from the .lib using LIB.EXE. -@item Build a dummy C file referencing all the functions you need, either - with a direct call or through an initialized function pointer. -@item Build a dummy LibMain. -@item Link all the objects with this file+LibMain. -@item Write a .def. -@item Link. -@end enumerate - -You can use these methods to use MSVC (and many other runtime libs) -with Cygwin development tools. - -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... - -Thanks to Jacob Navia (root at jacob dot remcomp dot fr) for this explanation. - -@subsection How do I rebuild the tools on my NT box? - -Install all required components in one directory (we'll call it /src). -Ideally, you should check out what you need from CVS -(@file{http://cygwin.com/cvs.html}). This is the @emph{preferred -method} for acquiring the sources. Otherwise, you can install the -appropriate source packages from the cygwin distribution. - -As of this writing, you need to install at least the cygwin source -package and the w32api source package. The winsup source package -should be extracted first and the w32api source directory should -be extracted into the resulting 'winsup' directory. Then rename -w32api-whatever to w32api. - -It is possible that the cygwin source package may require a newer -version of the w32api package since the release of the packages is -not always in lock step (another reason to just use CVS). - -You @emph{must} build cygwin in a separate directory from the source. -So, create something like a /obj directory. You'll be performing -your build in that directory: - -@example -bash -cd /obj -/src/configure --prefix=/install -v > configure.log 2>&1 -make > make.log 2>&1 -make install > install.log 2>&1 -@end example - -Normally, this procedure ignore errors in building the documentation, -which requires tools which are not included in the Cygwin distribution. -If you want to build the documentation on Linux, on most distributions a -package named docbook-utils should get you most of what you need. For -more information on building the documentation, see the README included -in the cygwin-doc package. - -To check a cygwin1.dll, run "make check" in the winsup/cygwin directory. -If that works, install everything @emph{except} 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. - -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. - -@subsection How can I compile a powerpc NT toolchain? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -Unfortunately, this will be difficult. It hasn't been built for -some time (late 1996) since Microsoft has dropped development of -powerpc NT. Exception handling/signals support semantics/args have been -changed for x86 and not updated for ppc so the ppc specific support would -have to be rewritten. We don't know of any other incompatibilities. -Please send us patches if you do this work! - -@subsection How can I compile an Alpha NT toolchain? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -We have not ported the tools to Alpha NT and do not have plans to -do so at the present time. We would be happy to add support -for Alpha NT if someone contributes the changes to us. - -@subsection How can I adjust the heap/stack size of an application? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -Pass heap/stack linker arguments to gcc. To create foo.exe with -a heap size of 1024 and a stack size of 4096, you would invoke -gcc as: - -@code{gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c} - -@subsection How can I find out which DLLs are needed by an executable? - -@samp{objdump -p} provides this information, but is rather verbose. - -@samp{cygcheck} will do this much more concisely, and operates -recursively, provided the command is in your path. - -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: - -@example -cygcheck c:\\winnt\\system32\\cmd.exe -@end example - -(Note the windows path separator must be escaped if this is typed in -bash.) - -@subsection How do I build a DLL? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -There's documentation that explains the process on the main Cygwin -project web page (http://cygwin.com/). - -@subsection How can I set a breakpoint at MainCRTStartup? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -Set a breakpoint at *0x401000 in gdb and then run the program in -question. - -@subsection How can I build a relocatable dll? - -@strong{(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 -@file{http://cygwin.com/ml/cygwin/2000-06/msg00688.html} and -related messages.)} - -You must execute the following sequence of five commands, in this -order: - -@example -$(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ - --base-file BASEFILE --output-exp EXPFILE - -$(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ - --base-file BASEFILE --output-exp EXPFILE - -$(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY -@end example - -In this example, $(LD) is the linker, ld. - -$(DLLTOOL) is dlltool. - -$(AS) is the assembler, as. - -DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll. - -OBJS is the list of object files you want to put into the DLL. - -LIBS is the list of libraries you want to link the DLL against. For -example, you may or may not want -lcygwin. You may want -lkernel32. -Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32 --lkernel32. - -DEFFILE is the name of your definitions file. A simple DEFFILE would -consist of ``EXPORTS'' followed by a list of all symbols which should -be exported from the DLL. Each symbol should be on a line by itself. -Other programs will only be able to access the listed symbols. - -BASEFILE is a temporary file that is used during this five stage -process, e.g., tcl.base. - -EXPFILE is another temporary file, e.g., tcl.exp. - -ENTRY is the name of the function which you want to use as the entry -point. This function should be defined using the WINAPI attribute, -and should take three arguments: - int WINAPI startup (HINSTANCE, DWORD, LPVOID) - -This means that the actual symbol name will have an appended @@12, so if -your entry point really is named @samp{startup}, the string you should -use for ENTRY in the above examples would be @samp{startup@@12}. - -If your DLL calls any Cygwin API functions, the entry function will need -to initialize the Cygwin impure pointer. You can do that by declaring -a global variable @samp{_impure_ptr}, and then initializing it in the -entry function. Be careful not to export the global variable -@samp{_impure_ptr} from your DLL; that is, do not put it in DEFFILE. - -@example -/* This is a global variable. */ -struct _reent *_impure_ptr; -extern struct _reent *__imp_reent_data; - -int entry (HINSTANT hinst, DWORD reason, LPVOID reserved) -@{ - _impure_ptr = __imp_reent_data; - /* Whatever else you want to do. */ -@} -@end example - -You may put an optional `--subsystem windows' on the $(LD) lines. The -Tcl build does this, but I admit that I no longer remember whether -this is important. Note that if you specify a --subsytem <x> flag to ld, -the -e entry must come after the subsystem flag, since the subsystem flag -sets a different default entry point. - -You may put an optional `--image-base BASEADDR' on the $(LD) lines. -This will set the default image base. Programs using this DLL will -start up a bit faster if each DLL occupies a different portion of the -address space. Each DLL starts at the image base, and continues for -whatever size it occupies. - -Now that you've built your DLL, you may want to build a library so -that other programs can link against it. This is not required: you -could always use the DLL via LoadLibrary. However, if you want to be -able to link directly against the DLL, you need to create a library. -Do that like this: - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE - -$(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above. Make -sure you use the same DLLNAME and DEFFILE, or things won't work right. - -LIBFILE is the name of the library you want to create, e.g., -libtcl80.a. You can then link against that library using something -like -ltcl80 in your linker command. - -@subsection How can I debug what's going on? - -You can debug your application using @code{gdb}. 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). - -@subsection Can I use a system trace mechanism instead? - -Yes. You can use the @code{strace.exe} utility to run other cygwin -programs with various debug and trace messages enabled. For information -on using @code{strace}, see the Cygwin User's Guide or the file -@code{winsup/utils/utils.sgml}. - -@subsection Why doesn't gdb handle signals? - -Unfortunately, there is only minimal signal handling support in gdb -currently. Signal handling only works with Windows-type signals. -SIGINT may work, SIGFPE may work, SIGSEGV definitely does. You cannot -'stop', 'print' or 'nopass' signals like SIGUSR1 or SIGHUP to the -process being debugged. - -@subsection The linker complains that it can't find something. - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -A common error is to put the library on the command line before -the thing that needs things from it. - -This is wrong @code{gcc -lstdc++ hello.cc}. -This is right @code{gcc hello.cc -lstdc++}. - -@subsection I use a function I know is in the API, but I still get a link error. - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -The function probably isn't declared in the header files, or -the UNICODE stuff for it isn't filled in. - -@subsection Can you make DLLs that are linked against libc ? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -Yes. - -@subsection Where is malloc.h? - -@strong{(Please note: This section has not yet been updated for the latest -net release.)} - -Include stdlib.h instead of malloc.h. - -@subsection Can I use my own malloc? - -If you define a function called @code{malloc} in your own code, and link -with the DLL, the DLL @emph{will} call your @code{malloc}. Needless to -say, you will run into serious problems if your malloc is buggy. - -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 @code{malloc} @emph{before} your main line is started. -If you have written your own @code{malloc} to need some initialization -to occur after @code{main} is called, then this will surely break. - -Moreover, there is an outstanding issue with @code{_malloc_r} in -@code{newlib}. This re-entrant version of @code{malloc} will be called -directly from within @code{newlib}, by-passing your custom version, and -is probably incompatible with it. But it may not be possible to replace -@code{_malloc_r} too, because @code{cygwin1.dll} 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. - -@subsection Can I mix objects compiled with msvc++ and gcc? - -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. - -@subsection Can I use the gdb debugger to debug programs built by VC++? - -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. - -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. - -@subsection Where can I find info on x86 assembly? - -CPU reference manuals for Intel's current chips are available in -downloadable PDF form on Intel's web site: - -@file{http://developer.intel.com/design/pro/manuals/} - -@subsection Shell scripts aren't running properly from my makefiles? - -If your scripts are in the current directory, you must have @samp{.} -(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. - -@subsection What preprocessor do I need to know about? - -We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for -access to the Cygwin environment provided by the dll. - -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++. - -_WIN32 is only defined when you use either the -mno-cygwin or -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. - -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 - -@example - $ gcc -dM -E -xc /dev/null >gcc.txt - $ gcc -mno-cygwin -dM -E -xc /dev/null >gcc-mno-cygwin.txt - $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt -@end example -Then use the diff and grep utilities to check -what the difference is. - -@subsection How should I port my Unix GUI to Windows? - -There are two basic strategies for porting Unix GUIs to Windows. - -The first is to use a portable graphics library such as tcl/tk, X11, or -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. - -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 -may still want to use Cygwin if your program contains a lot of shared -(non-GUI-related) code. That way you still gain some of the portability -advantages inherent in using Cygwin. - -@subsection Why not use DJGPP ? - -DJGPP is a similar idea, but for DOS instead of Win32. DJGPP uses a -"DOS extender" to provide a more reasonable operating interface for its -applications. The Cygwin toolset doesn't have to do this since all of -the applications are native WIN32. Applications compiled with the -Cygwin tools can access the Win32 API functions, so you can write -programs which use the Windows GUI. - -You can get more info on DJGPP by following -@file{http://www.delorie.com/}. |