New files, contents of how.texinfo has been split into these.

1 files changed, 536 insertions, 0 deletions

diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo
new file mode 100644
index 000000000..7b74b7b8f
--- /dev/null
+++ b/winsup/doc/how-programming.texinfo
@@ -0,0 +1,536 @@
+@section Programming Questions
+
+@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.
+
+@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 Why is make behaving badly?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Starting with the beta 19 release, make defaults to a win32 mode in
+which backslashes in filenames are permitted and cmd.exe/command.com
+is used as the sub-shell.  In this mode, escape characters aren't
+allowed among other restrictions.  For this reason, you must set
+the environment variable MAKE_MODE to UNIX to run make on ordinary Unix
+Makefiles.  Here is the full scoop:
+
+MAKE_MODE selects between native Win32 make mode (the default) and
+a Unix mode where it behaves like a Unix make.  The Unix mode does
+allow specifying Win32-style paths but only containing forward slashes
+as the path separator.  The path list separator character is a colon
+in Unix mode.
+
+Win32 mode expects path separators to be either / or \.  Thus no
+Unix-style \s as escape are allowed.  Win32 mode also uses
+cmd.exe/command.com as the subshell which means "copy" and "del"
+(and other shell builtins) will work.  The path list separator
+character is semi-colon in Win32 mode.  People who want an nmake-like
+make might want to use this mode but no one should expect Unix
+Makefiles to compile in this mode.  That is why the default b19
+install sets MAKE_MODE to UNIX.
+
+@subsection Why the undefined reference to "WinMain@@16"?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Try adding an empty main() function to one of your sources.
+
+@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 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 commandline.
+
+@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 Cygnus (err... Red Hat) can't agree to.  Fortunately, we
+have our own Win32 headers which are pretty complete.
+
+@subsection How do I link against .lib files?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+1. 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.
+2. Build a dummy 'LibMain'.
+3. Build a .def with all the exports you need.
+4. Link with your .lib using link.exe.
+
+or
+
+1. Extract all the object files from the .lib using LIB.EXE.
+2. Build a dummy C file referencing all the functions you need, either
+with a direct call or through an initialized function pointer.
+3. Build a dummy LibMain.
+4. Link all the objects with this file+LibMain.
+5. Write a .def.
+6. Link.
+
+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@@jacob.remcomp.fr) for this explanation)
+
+@subsection How do I rebuild the tools on my NT box?
+
+@strong{Note:} You must build in a directory @emph{outside} the source
+tree.
+
+Assuming that you have the src installed as /src, will build in
+the directory /obj, and want to install the tools in /install:
+
+@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 will also attempt to build the documentation, which
+additionally requires db2html, texi2html and possibly others.
+These tools are not included in the Cygwin distribution, but are readily
+obtainable:
+
+@table @samp
+@item db2html
+Part of docbook, from @file{http://sources.redhat.com/docbook-tools/}.
+@item texi2html
+From @file{http://www.mathematik.uni-kl.de/~obachman/Texi2html/}.
+@end table
+
+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 @emph{all} the
+places where the old dll was (if there is more than one on your
+machine).  Then start up a bash window and see what happens.  (Or better,
+run a cygwin program from the Windows command prompt.)
+
+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.
+
+@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?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+objdump -p provides this information.
+
+@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://sources.redhat.com/cygwin/).
+
+@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://sources.redhat.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}.
+
+Alternatively, you can set the @code{STRACE} environment variable to
+@code{1}, and get a whole load of debug information on your screen
+whenever a Cygwin app runs.  This is an especially useful tool to use
+when tracking bugs down inside the Cygwin library.  @code{STRACE} can be
+set to different values to achieve different amounts of granularity.
+You can set it to @code{0x10} for information about syscalls or
+@code{0x800} for signal/process handling-related info, to name two.  The
+strace mechanism is well documented in the Cygwin library sources in the
+file @code{winsup/cygwin/include/sys/strace.h}.
+
+@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?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+You need to have . (dot) in your $PATH.  You should NOT 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?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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++.
+
+@subsection Where can I get f77 and objc components for B20 EGCS 1.1?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+B20-compatible versions of the f77 and objc components are available
+from @file{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/}.
+
+@subsection How should I port my Unix GUI to Windows?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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/}.