1357 lines
55 KiB
Plaintext
1357 lines
55 KiB
Plaintext
@chapter Question and Answers
|
|
|
|
@section Where can I get more information?
|
|
|
|
@subsection Where's the documentation?
|
|
|
|
There are links to quite a lot of it on the main Cygwin project web
|
|
page: @file{http://sources.redhat.com/cygwin/}. Be sure to at least
|
|
read any 'Release Notes' or 'Readme' or 'read this' links on the main
|
|
web page, if there are any.
|
|
|
|
There is a comprehensive Cygwin User's Guide at
|
|
@file{http://sources.redhat.com/cygwin/cygwin-ug-net/cygwin-ug-net.html}
|
|
and an API Reference at
|
|
@file{http://sources.redhat.com/cygwin/cygwin-api/cygwin-api.html}.
|
|
|
|
There is an interesting paper about Cygwin from the 1998 USENIX Windows
|
|
NT Workshop Proceedings at
|
|
@file{http://sources.redhat.com/cygwin/usenix-98/cygwin.html}.
|
|
|
|
You can find documentation for the individual GNU tools at
|
|
@file{http://www.fsf.org/manual/}. (You should read GNU manuals from a
|
|
local mirror, check @file{http://www.fsf.org/server/list-mirrors.html}
|
|
for a list of them.)
|
|
|
|
@subsection What Cygwin mailing lists can I join?
|
|
|
|
Comprehensive information about the Cygwin mailing lists can be found at
|
|
@file{http://sources.redhat.com/cygwin/lists.html}.
|
|
|
|
To subscribe to the main list, send a message to
|
|
cygwin-subscribe@@sources.redhat.com. To unsubscribe from the
|
|
main list, send a message to cygwin-unsubscribe@@sources.redhat.com.
|
|
In both cases, the subject and body of the message are ignored.
|
|
|
|
Similarly, to subscribe to the Cygwin annoucements list, send a message
|
|
to cygwin-announce-subscribe@@sources.redhat.com. To unsubscribe,
|
|
send a message to cygwin-announce-unsubscribe@@sources.redhat.com.
|
|
|
|
If you are going to help develop the Cygwin library by volunteering for
|
|
the project, you will want to subscribe to the Cygwin developers list,
|
|
called cygwin-developers. If you are contributing to Cygwin tools &
|
|
applications, rather than the library itself, then you should subscribe
|
|
to cygwin-apps. The same mechanism as described for the first two lists
|
|
works for these as well. Both cygwin-developers and cygwin-apps are
|
|
by-approval lists.
|
|
|
|
There is a searchable archive of the main mailing list at
|
|
@file{http://sources.redhat.com/ml/cygwin/}. There is an alternate
|
|
archive, also searchable, at @file{http://www.delorie.com/archives/}.
|
|
|
|
Cygwin mailing lists are not gatewayed to USENET, so anti-spam measures
|
|
in your email address are neither required nor appreciated. Also, avoid
|
|
sending HTML content to Cygwin mailing lists.
|
|
|
|
@subsection Posting Guidelines (Or: Why won't you/the mailing list answer my questions?)
|
|
|
|
If you follow these guidelines, you are much more likely to get a
|
|
helpful response from the Cygwin developers and/or the Cygwin community at
|
|
large:
|
|
|
|
@itemize @bullet
|
|
@item Read the User's Guide and the FAQ first.
|
|
@item Check the mailing list archives. Your topic may have come up
|
|
before. (It may even have been answered!) Use the search facilities
|
|
at the links above. Try the alternate site if the main archive is not
|
|
producing search results.
|
|
@item Explain your problem carefully and completely. "I installed Blah
|
|
and it doesn't work!" wastes everybody's time. It provides no
|
|
information for anyone to help you with your problem. You should
|
|
provide:
|
|
|
|
@itemize @bullet
|
|
@item A problem statement: How does it behave, how do you think it
|
|
should behave, and what makes you think it's broken? (Oh yeah, and what
|
|
is @emph{"it"}?)
|
|
@item Information about your Windows OS ("Win95 OSR2" or "NT4/SP3" or
|
|
"Win2K" or "Win98 SE" or ...).
|
|
@item Details about your installation process, or attempts at same. (Internet or
|
|
Directory install? If the former, exactly when and from what mirror?
|
|
If the latter, which packages did you download? Which version of
|
|
setup.exe? Any subsequent updates?)
|
|
@item Details about your Cygwin setup, accomplished by @emph{pasting}
|
|
the output of 'cygcheck -s -v -r' into your message. (Do not send the
|
|
output as a file attachment.)
|
|
@item A valid return address, so that a reply doesn't require manual editing of
|
|
the 'To:' header.
|
|
@end itemize
|
|
|
|
@item Your message must be relevant to the list. Messages that are
|
|
@emph{not} directly related to Cygwin are considered off-topic and are
|
|
unwelcome. For example, the following are off-topic:
|
|
|
|
@itemize @bullet
|
|
@item General programming language questions
|
|
@item General Windows programming questions
|
|
@item General UNIX shell programming questions
|
|
@item General application usage questions
|
|
@item How to make millions by working at home
|
|
@item Announcements from LaserJet toner cartridge suppliers
|
|
@end itemize
|
|
|
|
@end itemize
|
|
|
|
If you do not follow the above guidelines, you may still elicit a
|
|
response, but you may not appreciate it!
|
|
|
|
Inquiries about support contracts and commercial licensing should go to
|
|
info@@cygnus.com. If you want to purchase the Cygwin 1.0 CD-ROM, visit
|
|
@file{http://www.cygnus.com/cygwin/} or write to
|
|
cygwin-info@@cygnus.com. While not strictly @emph{unappreciated} in the
|
|
main cygwin list, you'll get the information you need more quickly if
|
|
you write to the correct address in the first place.
|
|
|
|
Beyond that, perhaps nobody has time to answer your question. Perhaps
|
|
nobody knows the answer.
|
|
|
|
@section Using Cygwin
|
|
|
|
@subsection How should I set my PATH?
|
|
|
|
If you look at the "Cygwin 1.1.0" (or similar) shortcut created in the
|
|
"Cygnus Solutions" programs folder, you'll see that it runs
|
|
@code{C:\cygwin\bin\cygwin.bat} (assuming your root is
|
|
@code{C:\cygwin}). The contents should look something like this:
|
|
|
|
@example
|
|
@@echo off
|
|
SET MAKE_MODE=unix
|
|
SET PATH=C:\cygwin\bin;C:\cygwin\usr\local\bin;%PATH%
|
|
bash
|
|
@end example
|
|
|
|
Effectively, this @strong{prepends} /usr/bin and /usr/local/bin to your
|
|
Windows system path. If you choose to reset your PATH, say in
|
|
$HOME/.bashrc, then you should follow this rule. You @strong{must} have
|
|
@code{/usr/bin} in your PATH @strong{before} any Windows system
|
|
directories. (And you must not omit the Windows system directories!)
|
|
Otherwise you will likely encounter all sorts of problems
|
|
running Cygwin applications.
|
|
|
|
If you haven't messed up the default mounts, then @code{/bin} and
|
|
@code{/usr/bin} are the same location, so you only need one of them in
|
|
your PATH. You should use @code{/usr/local/bin} for installing
|
|
additional Cygwin applications that are not part of the core net
|
|
release. (That is, anything not found in an ftp mirror of @code{latest}
|
|
and installed by @code{setup.exe}.)
|
|
|
|
@subsection How do I convert between Windows and UNIX paths?
|
|
|
|
Use the 'cygpath' utility. Type '@code{cygpath}' with no arguments to
|
|
get usage information. For example (on my installation):
|
|
@example
|
|
bash$ cygpath --windows ~/.bashrc
|
|
D:\starksb\.bashrc
|
|
bash$ cygpath --unix C:/cygwin/bin/cygwin.bat
|
|
/usr/bin/cygwin.bat
|
|
bash$ cygpath --unix C:\\cygwin\\bin\\cygwin.bat
|
|
/usr/bin/cygwin.bat
|
|
@end example
|
|
Note that bash interprets the backslash '\' as an escape character, so
|
|
you must type it twice in the bash shell if you want it to be recognised
|
|
as such.
|
|
|
|
@subsection How do I set /etc up?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
If you want a valid /etc set up (so "ls -l" will display correct
|
|
user information for example) and if you are running NT (preferably
|
|
with an NTFS file system), you should just need to create the /etc
|
|
directory on the filesystem mounted as / and then use mkpasswd and
|
|
mkgroup to create /etc/passwd and /etc/group respectively. Since
|
|
Windows 95/98's Win32 API is less complete, you're out of luck if
|
|
you're running Windows 95/98.
|
|
|
|
@subsection Why doesn't bash read my .bashrc file on startup?
|
|
|
|
Your .bashrc is read from your home directory specified by the HOME
|
|
environment variable. It uses /.bashrc if HOME is not set. So you need
|
|
to set HOME correctly, or move your .bashrc to the top of the drive
|
|
mounted as / in Cygwin.
|
|
|
|
@subsection How can I get bash filename completion to be case insensitive?
|
|
|
|
"shopt -s nocaseglob" should do the trick.
|
|
|
|
@subsection Can I use paths/filenames containing spaces in them?
|
|
|
|
Cygwin does support spaces in filenames and paths. That said, some
|
|
utilities that use the library may not, since files don't typically
|
|
contain spaces in Unix. If you stumble into problems with this, you
|
|
will need to either fix the utilities or stop using spaces in filenames
|
|
used by Cygwin tools.
|
|
|
|
In particular, bash interprets space as a word separator. You would have
|
|
to quote a filename containing spaces, or escape the space character.
|
|
For example:
|
|
@example
|
|
bash-2.03$ cd '/cygdrive/c/Program Files'
|
|
@end example
|
|
or
|
|
@example
|
|
bash-2.03$ cd /cygdrive/c/Program\ Files
|
|
@end example
|
|
|
|
@subsection Why can't I cd into a shortcut to a directory?
|
|
|
|
Cygwin does not follow MS Windows Explorer Shortcuts (*.lnk files). It
|
|
sees a shortcut as a regular file and this you cannot "cd" into it.
|
|
|
|
Some people have suggested replacing the current symbolic link scheme
|
|
with shortcuts. The major problem with this is that .LNK files would
|
|
then be used to symlink Cygwin paths that may or may not be valid
|
|
under native Win32 non-Cygwin applications such as Explorer.
|
|
|
|
@subsection I'm having basic problems with find. Why?
|
|
|
|
Make sure you are using the find that came with Cygwin and that you
|
|
aren't picking up the Win32 find command instead. You can verify that
|
|
you are getting the right one by doing a "type find" in bash.
|
|
|
|
@subsection Why don't cursor keys work under Win95/Win98?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
Careful examination shows that they not just non-functional, but
|
|
rather behave strangely, for example, with NumLock off, keys on numeric
|
|
keyboard work, until you press usual cursor keys, when even numeric
|
|
stop working, but they start working again after hitting alphanumeric
|
|
key, etc. This reported to happen on localized versions of Win98 and
|
|
Win95, and not specific to Cygwin (there're known cases of Alt+Enter
|
|
(fullscreen/windowed toggle) not working and shifts sticking with
|
|
other programs). The cause of this problem is Microsoft keyboard
|
|
localizer which by default installed in 'autoexec.bat'. Corresponding
|
|
line looks like:
|
|
|
|
@example
|
|
keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys
|
|
@end example
|
|
|
|
(That's for russian locale.) You should comment that line if you want
|
|
your keys working properly. Of course, this will deprive you of your
|
|
local alphabet keyboard support, so you should think about
|
|
another localizer. exUSSR users are of course knowledgable of Keyrus
|
|
localizer, and it might work for other locales too, since it has keyboard
|
|
layout editor. But it has russian messages and documentation ;-(
|
|
Reference URL is http://www.hnet.ru/software/contrib/Utils/KeyRus/
|
|
(note the you may need to turn off Windows logo for Keyrus to operate
|
|
properly).
|
|
|
|
@subsection Is it OK to have multiple copies of the DLL?
|
|
|
|
You should only have one copy of the Cygwin DLL on your system. If you
|
|
have multiple versions, they will conflict and cause problems.
|
|
|
|
If you get the error "shared region is corrupted" it means you have
|
|
multiple versions of cygwin1.dll running at the same time. This could
|
|
happen, for example, if you update cygwin1.dll without exiting @emph{all}
|
|
Cygwin apps (including inetd) beforehand.
|
|
|
|
@subsection Where can I find "more"?
|
|
|
|
If you are looking for the "more" pager, you should use the "less" pager
|
|
instead.
|
|
|
|
@subsection Where can I find "which"?
|
|
|
|
There is no "which" command with Cygwin. However, you can use the bash
|
|
shell builtin "type" which does something similar.
|
|
|
|
@subsection How can I access other drives?
|
|
|
|
You have some flexibility here.
|
|
|
|
Cygwin has a builtin "cygdrive prefix" for drives that are not mounted.
|
|
You can access any drive, say Z:, as '/cygdrive/z/'.
|
|
|
|
In some applications (notably bash), you can use the familiar windows
|
|
<drive>:/path/, using posix forward-slashes ('/') instead of Windows
|
|
backward-slashes ('\'). (But see the warning below!) This maps in the
|
|
obvious way to the Windows path, but will be converted internally to use
|
|
the Cygwin path, following mounts (default or explicit). For example:
|
|
@example
|
|
bash-2.03$ cd C:/Windows
|
|
bash-2.03$ pwd
|
|
/cygdrive/c/Windows
|
|
@end example
|
|
and
|
|
@example
|
|
bash-2.03$ cd C:/cygwin
|
|
bash-2.03$ pwd
|
|
/
|
|
@end example
|
|
for a default setup. (You could also use backward-slashes in the
|
|
Windows path, but these would have to be escaped from the shell.)
|
|
|
|
@strong{Warning:} There is some ambiguity in going from a Windows path
|
|
to the posix path, because different posix paths, through different
|
|
mount points, could map to the same Windows directory. This matters
|
|
because different mount points may be binmode or textmode, so the
|
|
behaviour of Cygwin apps will vary depending on the posix path used to
|
|
get there.
|
|
|
|
You can avoid the ambiguity of Windows paths, and avoid typing
|
|
"/cygdrive", by explicitly mounting drives to posix paths. For example:
|
|
@example
|
|
bash$ mkdir /c
|
|
bash$ mount c:/ /c
|
|
bash$ ls /c
|
|
@end example
|
|
Note that you only need to mount drives once. The mapping is kept
|
|
in the registry so mounts stay valid pretty much indefinitely.
|
|
You can only get rid of them with umount (or the registry editor).
|
|
|
|
The '-b' option to mount mounts the mountpoint in binary mode
|
|
("binmode") where text and binary files are treated equivalently. This
|
|
should only be necessary for badly ported Unix programs where binary
|
|
flags are missing from open calls. It is also the setting for /,
|
|
/usr/bin and /usr/lib in a default Cygwin installation. The default for
|
|
new mounts is text mode ("textmode"), which is also the mode for all
|
|
"cygdrive" mounts.
|
|
|
|
@subsection How can I copy and paste into Cygwin console windows?
|
|
|
|
Under Windows NT, open the properties dialog of the console window.
|
|
The options contain a toggle button, named "Quick edit mode". It must
|
|
be ON. Save the properties.
|
|
|
|
Under Windows 9x, open the properties dialog of the console window.
|
|
Select the Misc tab. Uncheck Fast Pasting. Check QuickEdit.
|
|
|
|
@subsection What does "mount failed: Device or resource busy" mean?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
This usually means that you are trying to mount to a location
|
|
already in use by mount. For example, if c: is mounted as '/'
|
|
and you try to mount d: there as well, you will get this error
|
|
message. First "umount" the old location, then "mount" the new one and
|
|
you should have better luck.
|
|
|
|
If you are trying to umount '/' and are getting this message, you may
|
|
need to run @code{regedit.exe} and change the "native" key for the '/'
|
|
mount in one of the mount points kept under
|
|
HKEY_CURRENT_USER/Software/Cygnus Solutions/CYGWIN.DLL setup/<version>
|
|
where <version> is the latest registry version associated with the
|
|
Cygwin library.
|
|
|
|
@subsection How can I share files between Unix and Windows?
|
|
|
|
During development, we have both Unix boxes running Samba and
|
|
NT/Windows 95/98 machines. We often build with cross-compilers
|
|
under Unix and copy binaries and source to the Windows system
|
|
or just toy with them directly off the Samba-mounted partition.
|
|
On dual-boot NT/Windows 9x machines, we usually use the FAT
|
|
filesystem so we can also access the files under Windows 9x.
|
|
|
|
@subsection Are mixed-case filenames possible with Cygwin?
|
|
|
|
Several Unix programs expect to be able to use to filenames
|
|
spelled the same way, but with different case. A prime example
|
|
of this is perl's configuration script, which wants @code{Makefile} and
|
|
@code{makefile}. WIN32 can't tell the difference between files with
|
|
just different case, so the configuration fails.
|
|
|
|
In releases prior to beta 16, mount had a special mixed case option
|
|
which renamed files in such a way as to allow mixed case filenames. We
|
|
chose to remove the support when we rewrote the path handling code for
|
|
beta 16. The standard Windows apps -- explorer.exe,
|
|
cmd.exe/command.com, etc. -- do not distinguish filenames that differed
|
|
only in case, resulting in some (very) undesirable behavior.
|
|
|
|
Sergey Okhapkin had maintained a mixed-case patch ('coolview') until
|
|
about B20.1, but this has not been updated to recent versions of Cygwin.
|
|
|
|
@subsection What about DOS special filenames?
|
|
|
|
Files cannot be named com1, lpt1, or aux (to name a few); either as
|
|
the root filename or as the extension part. If you do, you'll have
|
|
trouble. Unix programs don't avoid these names which can make things
|
|
interesting. E.g., the perl distribution has a file called
|
|
@code{aux.sh}. The perl configuration tries to make sure that
|
|
@code{aux.sh} is there, but an operation on a file with the magic
|
|
letters 'aux' in it will hang.
|
|
|
|
@subsection When it hangs, how do I get it back?
|
|
|
|
If something goes wrong and the tools hang on you for some reason (easy
|
|
to do if you try and read a file called aux.sh), first try hitting ^C to
|
|
return to bash or the cmd prompt.
|
|
|
|
If you start up another shell, and applications don't run, it's a good
|
|
bet that the hung process is still running somewhere. Use the Task
|
|
Manager, pview, or a similar utility to kill the process.
|
|
|
|
And, if all else fails, there's always the reset button/power switch.
|
|
This should never be necessary under Windows NT.
|
|
|
|
@subsection Why the weird directory structure?
|
|
|
|
Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing?
|
|
|
|
Why use mounts instead of symbolic links?
|
|
|
|
Can I use a disk root (e.g., C:\) as Cygwin root? Why is this discouraged?
|
|
|
|
After a new installation in the default location, your mount points will
|
|
look something like this:
|
|
|
|
@example
|
|
Device Directory Type Flags
|
|
C:\cygwin\bin /usr/bin user binmode
|
|
C:\cygwin\lib /usr/lib user binmode
|
|
C:\cygwin / user binmode
|
|
@end example
|
|
|
|
Note that /bin and /usr/bin point to the same location, as do /lib and
|
|
/usr/lib. This is intentional, and you should not undo these mounts
|
|
unless you @emph{really} know what you are doing.
|
|
|
|
Various applications and packages may expect to be installed in /lib or
|
|
/usr/lib (similarly /bin or /usr/bin). Rather than distinguish between
|
|
them and try to keep track of them (possibly requiring the occasional
|
|
duplication or symbolic link), it was decided to maintain only one
|
|
actual directory, with equivalent ways to access it.
|
|
|
|
Symbolic links had been considered for this purpose, but were dismissed
|
|
because they do not always work on Samba drives. Also, mounts are
|
|
faster to process because no disk access is required to resolve them.
|
|
|
|
Note that non-cygwin applications will not observe Cygwin mounts (or
|
|
symlinks for that matter). For example, if you use WinZip to unpack the
|
|
tar distribution of a Cygwin package, it may not get installed to the
|
|
correct Cygwin path. @emph{So don't do this!}
|
|
|
|
It is strongly recommended not to make the Cygwin root directory the
|
|
same as your drive's root directory, unless you know what you are doing
|
|
and are prepared to deal with the consequences. It is generally easier
|
|
to maintain the Cygwin hierarchy if it is isolated from, say, C:\. For
|
|
one thing, you avoid possible collisions with other (non-cygwin)
|
|
applications that may create (for example) \bin and \lib directories.
|
|
(Maybe you have nothing like that installed now, but who knows about
|
|
things you might add in the future?)
|
|
|
|
@subsection How do anti-virus programs like Cygwin?
|
|
|
|
Users have reported that McAfee (now NAI) VirusScan for NT (and others?) is
|
|
incompatible with Cygwin. This is because it tries to scan the
|
|
newly loaded shared memory in the cygwin.dll, which can cause fork()s
|
|
to fail, wreaking havoc on many of the tools.
|
|
|
|
There are also reports of NAI VirusScan causing the system to hang when
|
|
unpacking tar.gz archives. This is surely a bug in VirusScan, and
|
|
should be reported to NAI. The only workaround is to disable VirusScan
|
|
when accessing these files. This can be an issue during setup, and is
|
|
discussed in that FAQ entry.
|
|
|
|
@subsection Why can't I run bash as a shell under NT Emacs?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
Place the following code in your startup file and try again:
|
|
|
|
@smallexample
|
|
(load "comint")
|
|
(fset 'original-comint-exec-1 (symbol-function 'comint-exec-1))
|
|
(defun comint-exec-1 (name buffer command switches)
|
|
(let ((binary-process-input t)
|
|
(binary-process-output nil))
|
|
(original-comint-exec-1 name buffer command switches)))
|
|
@end smallexample
|
|
|
|
@subsection info error "dir: No such file or directory"
|
|
|
|
Cygwin packages install their info documentation in the /usr/info
|
|
directory. But you need to create a @code{dir} file there before the
|
|
standalone info program (probably @code{/usr/bin/info}) can be used to
|
|
read those info files. This is how you do it:
|
|
@example
|
|
bash$ cd /usr/info
|
|
bash$ for f in *.info ; do install-info $f dir ; done
|
|
@end example
|
|
This may generate warnings:
|
|
@example
|
|
install-info: warning: no info dir entry in `gzip.info'
|
|
install-info: warning: no info dir entry in `time.info'
|
|
@end example
|
|
The @code{install-info} command cannot parse these files, so you will
|
|
have to add their entries to @code{/usr/info/dir} by hand.
|
|
|
|
@subsection Why do I get a message saying Out of Queue slots?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
"Out of queue slots!" generally occurs when you're trying to remove
|
|
many files that you do not have permission to remove (either because
|
|
you don't have permission, they are opened exclusively, etc). What
|
|
happens is Cygwin queues up these files with the supposition that it
|
|
will be possible to delete these files in the future. Assuming that
|
|
the permission of an affected file does change later on, the file will
|
|
be deleted as requested. However, if too many requests come in to
|
|
delete inaccessible files, the queue overflows and you get the message
|
|
you're asking about. Usually you can remedy this with a quick chmod,
|
|
close of a file, or other such thing. (Thanks to Larry Hall for
|
|
this explanation).
|
|
|
|
@subsection Why don't symlinks work on samba-mounted filesystems?
|
|
|
|
Symlinks are marked with "system" file attribute. Samba does not
|
|
enable this attribute by default. To enable it, consult your Samba
|
|
documentation and then add these lines to your samba configuration
|
|
file:
|
|
|
|
@smallexample
|
|
map system = yes
|
|
create mask = 0775
|
|
@end smallexample
|
|
|
|
Note that the 0775 can be anything as long as the 0010 bit is set.
|
|
|
|
@subsection Why does df report sizes incorrectly.
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
There is a bug in the Win32 API function GetFreeDiskSpace that
|
|
makes it return incorrect values for disks larger than 2 GB in size.
|
|
Perhaps that may be your problem?
|
|
|
|
@subsection Has the screen program been ported yet?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
Screen requires either unix domain sockets or fifoes. Neither of
|
|
them have been implemented in Cygwin yet.
|
|
|
|
@section Cygwin API Questions
|
|
|
|
@subsection How does everything work?
|
|
|
|
There's a C library which provides a Unix-style API. The
|
|
applications are linked with it and voila - they run on Windows.
|
|
|
|
The aim is to add all the goop necessary to make your apps run on
|
|
Windows into the C library. Then your apps should run on Unix and
|
|
Windows with no changes at the source level.
|
|
|
|
The C library is in a DLL, which makes basic applications quite small.
|
|
And it allows relatively easy upgrades to the Win32/Unix translation
|
|
layer, providing that dll changes stay backward-compatible.
|
|
|
|
For a good overview of Cygwin, you may want to read the paper on Cygwin
|
|
published by the Usenix Association in conjunction with the 2d Usenix NT
|
|
Symposium in August 1998. It is available in html format on the project
|
|
WWW site.
|
|
|
|
@subsection Are development snapshots for the Cygwin library available?
|
|
|
|
Yes. They're made whenever anything interesting happens inside the
|
|
Cygwin library (usually roughly on a nightly basis, depending on how much
|
|
is going on). They are only intended for those people who wish to
|
|
contribute code to the project. If you aren't going to be happy
|
|
debugging problems in a buggy snapshot, avoid these and wait for a real
|
|
release. The snapshots are available from
|
|
http://sources.redhat.com/cygwin/snapshots/
|
|
|
|
|
|
@subsection How is the DOS/Unix CR/LF thing handled?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
Let's start with some background.
|
|
|
|
In UNIX, a file is a file and what the file contains is whatever the
|
|
program/programmer/user told it to put into it. In Windows, a file is
|
|
also a file and what the file contains depends not only on the
|
|
program/programmer/user but also the file processing mode.
|
|
|
|
When processing in text mode, certain values of data are treated
|
|
specially. A \n (new line) written to the file will prepend a \r
|
|
(carriage return) so that if you `printf("Hello\n") you in fact get
|
|
"Hello\r\n". Upon reading this combination, the \r is removed and the
|
|
number of bytes returned by the read is 1 less than was actually read.
|
|
This tends to confuse programs dependant on ftell() and fseek(). A
|
|
Ctrl-Z encountered while reading a file sets the End Of File flags even
|
|
though it truly isn't the end of file.
|
|
|
|
One of Cygwin's goals is to make it possible to easily mix Cygwin-ported
|
|
Unix programs with generic Windows programs. As a result, Cygwin opens
|
|
files in text mode as is normal under Windows. In the accompanying
|
|
tools, tools that deal with binaries (e.g. objdump) operate in unix
|
|
binary mode and tools that deal with text files (e.g. bash) operate in
|
|
text mode.
|
|
|
|
Some people push the notion of globally setting the default processing
|
|
mode to binary via mount point options or by setting the CYGWIN32
|
|
environment variable. But that creates a different problem. In
|
|
binary mode, the program receives all of the data in the file, including
|
|
a \r. Since the programs will no longer deal with these properly for
|
|
you, you would have to remove the \r from the relevant text files,
|
|
especially scripts and startup resource files. This is a porter "cop
|
|
out", forcing the user to deal with the \r for the porter.
|
|
|
|
It is rather easy for the porter to fix the source code by supplying the
|
|
appropriate file processing mode switches to the open/fopen functions.
|
|
Treat all text files as text and treat all binary files as binary.
|
|
To be specific, you can select binary mode by adding @code{O_BINARY} to
|
|
the second argument of an @code{open} call, or @code{"b"} to second
|
|
argument of an @code{fopen} call. You can also call @code{setmode (fd,
|
|
O_BINARY)}.
|
|
|
|
Note that because the open/fopen switches are defined by ANSI, they
|
|
exist under most flavors of Unix; open/fopen will just ignore the switch
|
|
since they have no meaning to UNIX.
|
|
|
|
Also note that @code{lseek} only works in binary mode.
|
|
|
|
Explanation adapted from mailing list email by Earnie Boyd
|
|
<earnie_boyd@@yahoo.com>.
|
|
|
|
@subsection Is the Cygwin library multi-thread-safe?
|
|
|
|
Multi-thread-safe support is turned on by default in 1.1.x releases
|
|
(i.e., in the latest net release). That does not mean that it is bug
|
|
free!
|
|
|
|
There is also limited support for 'POSIX threads', see the file
|
|
@code{cygwin.din} for the list of POSIX thread functions provided.
|
|
|
|
@subsection Why is some functionality only supported in Windows NT?
|
|
|
|
Windows 9x: n.
|
|
32 bit extensions and a graphical shell for a 16 bit patch to an
|
|
8 bit operating system originally coded for a 4 bit microprocessor,
|
|
written by a 2 bit company that can't stand 1 bit of competition.
|
|
|
|
But seriously, Windows 9x lacks most of the security-related calls and
|
|
has several other deficiencies with respect to its version of the Win32
|
|
API. See the calls.texinfo document for more information as to what
|
|
is not supported in Win 9x.
|
|
|
|
@subsection How is fork() implemented?
|
|
|
|
Cygwin fork() essentially works like a non-copy on write version
|
|
of fork() (like old Unix versions used to do). Because of this it
|
|
can be a little slow. In most cases, you are better off using the
|
|
spawn family of calls if possible.
|
|
|
|
Here's how it works:
|
|
|
|
Parent initializes a space in the Cygwin process table for child.
|
|
Parent creates child suspended using Win32 CreateProcess call, giving
|
|
the same path it was invoked with itself. Parent calls setjmp to save
|
|
its own context and then sets a pointer to this in the Cygwin shared
|
|
memory area (shared among all Cygwin tasks). Parent fills in the childs
|
|
.data and .bss subsections by copying from its own address space into
|
|
the suspended child's address space. Parent then starts the child.
|
|
Parent waits on mutex for child to get to safe point. Child starts and
|
|
discovers if has been forked and then longjumps using the saved jump
|
|
buffer. Child sets mutex parent is waiting on and then blocks on
|
|
another mutex waiting for parent to fill in its stack and heap. Parent
|
|
notices child is in safe area, copies stack and heap from itself into
|
|
child, releases the mutex the child is waiting on and returns from the
|
|
fork call. Child wakes from blocking on mutex, recreates any mmapped
|
|
areas passed to it via shared area and then returns from fork itself.
|
|
|
|
@subsection How does wildcarding (globbing) work?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
If an application using CYGWIN.DLL starts up, and can't find the
|
|
@code{PID} environment variable, it assumes that it has been started
|
|
from the a DOS style command prompt. This is pretty safe, since the
|
|
rest of the tools (including bash) set PID so that a new process knows
|
|
what PID it has when it starts up.
|
|
|
|
If the DLL thinks it has come from a DOS style prompt, it runs a
|
|
`globber' over the arguments provided on the command line. This means
|
|
that if you type @code{LS *.EXE} from DOS, it will do what you might
|
|
expect.
|
|
|
|
Beware: globbing uses @code{malloc}. If your application defines
|
|
@code{malloc}, that will get used. This may do horrible things to you.
|
|
|
|
@subsection How do symbolic links work?
|
|
|
|
Cygwin generates link files with a magic header. When
|
|
you open a file or directory that is a link to somewhere else, it
|
|
opens the file or directory listed in the magic header. Because we
|
|
don't want to have to open every referenced file to check symlink
|
|
status, Cygwin marks symlinks with the system attribute. Files
|
|
without the system attribute are not checked. Because remote samba
|
|
filesystems do not enable the system attribute by default, symlinks do
|
|
not work on network drives unless you explicitly enable this
|
|
attribute.
|
|
|
|
@subsection Why do some files, which are not executables have the 'x' type.
|
|
|
|
When working out the unix-style attribute bits on a file, the library
|
|
has to fill out some information not provided by the WIN32 API.
|
|
|
|
It guesses that files ending in .exe and .bat are executable, as are
|
|
ones which have a "#!" as their first characters.
|
|
|
|
@subsection How secure is Cygwin in a multi-user environment?
|
|
|
|
Cygwin is not secure in a multi-user environment. For
|
|
example if you have a long running daemon such as "inetd"
|
|
running as admin while ordinary users are logged in, or if
|
|
you have a user logged in remotely while another user is logged
|
|
into the console, one cygwin client can trick another into
|
|
running code for it. In this way one user may gain the
|
|
priveledge of another cygwin program running on the machine.
|
|
This is because cygwin has shared state that is accessible by
|
|
all processes.
|
|
|
|
(Thanks to Tim Newsham (newsham@@lava.net) for this explanation).
|
|
|
|
@subsection How do the net-related functions work?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
The network support in Cygwin is supposed to provide the Unix API, not
|
|
the Winsock API.
|
|
|
|
There are differences between the semantics of functions with the same
|
|
name under the API.
|
|
|
|
E.g., the select system call on Unix can wait on a standard file handles
|
|
and handles to sockets. The select call in winsock can only wait on
|
|
sockets. Because of this, cygwin.dll does a lot of nasty stuff behind
|
|
the scenes, trying to persuade various winsock/win32 functions to do what
|
|
a Unix select would do.
|
|
|
|
If you are porting an application which already uses Winsock, then
|
|
using the net support in Cygwin is wrong.
|
|
|
|
But you can still use native Winsock, and use Cygwin. The functions
|
|
which cygwin.dll exports are called 'cygwin_<name>'. There
|
|
are a load of defines which map the standard Unix names to the names
|
|
exported by the dll -- check out include/netdb.h:
|
|
|
|
@example
|
|
..etc..
|
|
void cygwin_setprotoent (int);
|
|
void cygwin_setservent (int);
|
|
void cygwin_setrpcent (int);
|
|
..etc..
|
|
#ifndef __INSIDE_CYGWIN_NET__
|
|
#define endprotoent cygwin_endprotoent
|
|
#define endservent cygwin_endservent
|
|
#define endrpcent cygwin_endrpcent
|
|
..etc..
|
|
@end example
|
|
|
|
The idea is that you'll get the Unix->Cygwin mapping if you include
|
|
the standard Unix header files. If you use this, you won't need to
|
|
link with libwinsock.a - all the net stuff is inside the dll.
|
|
|
|
The mywinsock.h file is a standard winsock.h which has been hacked to
|
|
remove the bits which conflict with the standard Unix API, or are
|
|
defined in other headers. E.g., in mywinsock.h, the definition of
|
|
struct hostent is removed. This is because on a Unix box, it lives in
|
|
netdb. It isn't a good idea to use it in your applications.
|
|
|
|
As of the b19 release, this information may be slightly out of date.
|
|
|
|
@subsection I don't want Unix sockets, how do I use normal Win32 winsock?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
To use the vanilla Win32 winsock, you just need to #define Win32_Winsock
|
|
and #include "windows.h" at the top of your source file(s). You'll also
|
|
want to add -lwsock32 to the compiler's command line so you link against
|
|
libwsock32.a.
|
|
|
|
@subsection What version numbers are associated with Cygwin?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
There is a cygwin.dll major version number that gets incremented
|
|
every time we make a new Cygwin release available. This
|
|
corresponds to the name of the release (e.g. beta 19's major
|
|
number is "19"). There is also a cygwin.dll minor version number. If
|
|
we release an update of the library for an existing release, the minor
|
|
number would be incremented.
|
|
|
|
There are also Cygwin API major and minor numbers. The major number
|
|
tracks important non-backward-compatible interface changes to the API.
|
|
An executable linked with an earlier major number will not be compatible
|
|
with the latest DLL. The minor number tracks significant API additions
|
|
or changes that will not break older executables but may be required by
|
|
newly compiled ones.
|
|
|
|
Then there is a shared memory region compatibity version number. It is
|
|
incremented when incompatible changes are made to the shared memory
|
|
region or to any named shared mutexes, semaphores, etc.
|
|
|
|
Finally there is a mount point registry version number which keeps track
|
|
of non-backwards-compatible changes to the registry mount table layout.
|
|
This has been "B15.0" since the beta 15 release.
|
|
|
|
@subsection Why isn't _timezone set correctly?
|
|
|
|
@strong{(Please note: This section has not yet been updated for the latest
|
|
net release.)}
|
|
|
|
Did you explicitly call tzset() before checking the value of _timezone?
|
|
If not, you must do so.
|
|
|
|
@subsection Is there a mouse interface?
|
|
|
|
There is no way to capture mouse events from Cygwin. There are
|
|
currently no plans to add support for this.
|
|
|
|
@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
|
|
|
|
This will normally attempt to build the documentation, which
|
|
additionally requires texinfo, texi2html, db2html and possibly others.
|
|
These tools are not included in the Cygwin distribution, but are readily
|
|
obtainable (or build OOTB).
|
|
|
|
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/}.
|