newlib-cygwin/winsup/doc/install.texinfo

@chapter Installation Instructions
@section Contents

Unlike previous net releases such as B20.1 and earlier, there is no
monolithic "full" or "usertools" installation.  Rather, you can pick and
choose the packages you wish to install, and update them individually.

For a searchable list of packages that can be installed with Cygwin,
see @file{http://cygwin.com/packages/}.

Full source code is available for all packages and tools.

There is one recommended way to install Cygwin, which is to use the GUI
installer @samp{setup.exe}.  There are some variations on how you go
about that.

Do it any other way, and you're on your own!  That said, keep in mind
that the GUI installer is a "work in progress", so there might be a few
difficulties, especially if you are behind a firewall or have other
specific requirements.  If something doesn't work right for you, and
it's not covered here or elsewhere, then by all means report it to the
mailing list.

@section Installation using the @samp{setup.exe} program

The @samp{setup.exe} program is the recommended way to install Cygwin,
but it is still a work in progress.  Expect features and functionality
to change.  For this reason, it is a good idea to note the version and
build time reported by @code{setup.exe} when you run it.  This will help
diagnose problems, should you have any.  Check the cygwin mailing list
for the latest news about @code{setup.exe}.

@subsection Why not install in C:\?

The @code{setup.exe} program will prompt you for a "root" directory.
The default is @samp{C:\cygwin}, but you can change it.  You are urged not to
choose something like 'C:\' (the root directory on the system drive) for
your Cygwin root.  If you do, then critical Cygwin system directories
like 'etc', 'lib' and 'bin' could easily be corrupted by other (non-Cygwin)
applications or packages that use \etc, \lib or \bin.  Perhaps there is
no conflict now, but who knows what you might install in the future?
It's also just good common sense to segregate your Cygwin "filesystems"
from the rest of your Windows system disk.  (In the past, there had been
genuine bugs that would cause problems for people who installed in C:\,
but we believe those are gone now.)

@subsection Can I use the new setup to update a B18, B19, B20, B20.1 or CD-ROM (1.0) installation of Cygwin?

No, you must start from scratch with the new setup.  The overall
structure has changed so much that it would be silly to try to
accomodate old installations of Cygwin.  You'll probably be much better
off with a whole new installation anyway.  You may backup or rename your
old installation first, or just install the new one somewhere else.  Be
sure to make note of your current mount table, because this will be
overwritten during the new setup.

Once you've installed the latest net release, the new setup will update
just the individual packages that need it.

@subsection Is @code{setup.exe}, or one of the packages, infected with a virus?

Unlikely.  Unless you can confirm it, please don't report it to the
mailing list.  Anti-virus products have been known to detect false
positives when extracting compressed tar archives.  If this causes
problems for you, consider disabling your anti-virus software when
running @code{setup}.  Read the next entry for a fairly safe way to do
this.

@subsection My computer hangs when I try to run @code{setup.exe}!

Network Associates (formerly McAfee) products have been reported to
"hang" when extracting Cygwin tar archives.  Consider disabling your
anti-virus software when running @code{setup}.  The following
procedure should be a fairly safe way to do that:

@enumerate
@item Download @code{setup.exe} and scan it explicitly.

@item Turn off the anti-virus software.

@item Run setup to download and extract all the tar files.

@item Re-activate your anti-virus software and scan everything
in C:\cygwin (or wherever you chose to install).  If you're concerned
about a malicious package, say if a mirror is compromised, then you
should scan your entire hard disk after running setup.

@end enumerate

This should be safe provided setup.exe is not substituted by something
malicious.

@subsection What packages should I download?

Just get everything, if you have room for it.  But if you must be
selective:

@table @samp

@item cygwin
This is the minimum core, consisting of the cygwin1.dll and a few
commands (like @code{mount}).  Not much else, and no shell!

@item bash
This is the default interactive command shell for cygwin.  If you don't
install @samp{bash}, then the "Cygwin Bash Shell" shortcut that setup
creates for you won't actually do anything.

@item ash
This is often forgotten because it's not obvious that @samp{ash}
contains @code{/bin/sh}, which is essential for running scripts (and
@samp{make} and ...).

@end table

If you want to build programs, of course you'll need @samp{gcc}, but
you'll also need @samp{binutils}, probably @samp{make} and
@samp{fileutils}, and possibly lots more.  (Again, consider just getting
everything!)

@subsection How much disk space does Cygwin require?

All the packages listed above comprise about 55MB when downloaded.
This expands to about 230MB in your ``install root directory''
(@code{C:\cygwin} by default).  If you download source archives for
all packages, that's an additional 110MB.  These estimates are based
on measurements taken 22 Sep 2001.

After installation, the package archives remain in your ``Local Package
Directory'', by default the location of @code{setup.exe}.  You may
conserve disk space by deleting the @code{contrib} and @code{latest}
subdirectories there.

@subsection What if setup fails?

First, make sure that you are using the latest version of
@code{setup.exe}.  It's a work in progress, with improvements and
bugfixes being made often.  The latest version is always available from
the 'Install Cygwin now' link on the Cygwin Home Page at
@file{http://cygwin.com/}.

If you are downloading from the internet, setup will fail if it cannot
download the list of mirrors at
@file{http://cygwin.com/mirrors.html}.  It could be that
the network is too busy.  Similarly for an ftp download site that isn't
working.  Try another mirror, or try again later.

If setup refuses to download a package that you know needs to be
upgraded, try deleting that package's entry from /etc/setup.  If you are
reacting quickly to an announcement on the mailing list, it could be
that the mirror you are using doesn't have the latest copy yet.  Try
another mirror, or try again tomorrow.

If setup has otherwise behaved strangely, check the files
@samp{setup.log} and @samp{setup.log.full} in the Cygwin root directory
(@code{C:\cygwin} by default).  It may provide some clues as to what
went wrong and why.

If you're still baffled, search the Cygwin mailing list for clues.
Others may have the same problem, and a solution may be posted there.
If that search proves fruitless, send a query to the Cygwin mailing
list.  You must provide complete details in your query: version of
setup, options you selected, contents of setup.log and setup.log.full,
what happened that wasn't supposed to happen, etc.

@subsection What's the difference between packages in @samp{latest} and @samp{contrib}?

There is no difference as far as @code{setup.exe} is concerned, and you
should not worry about this either.  The distinction is more historical
than practical.

@subsection My Windows logon name has a space in it, will this cause problems?

Most definitely yes!  UNIX shells (and thus Cygwin) use the space
character as a word delimiter.  Under certain circumstances, it is
possible to get around this with various shell quoting mechanisms, but
you are much better off if you can avoid the problem entirely.

In particular, the environment variables @samp{USER} and @samp{HOME} are
set for you in /etc/profile.  By default these derive from your Windows
logon name.  You may edit this file and set them explicitly to something
without spaces.

(If you use the @samp{login} package or anything else that reads
/etc/passwd, you may need to make corresponding changes there.  See the
README file for that package.)

@subsection How do I uninstall individual packages?

Run @code{setup.exe} as you would to install packages.  In the list of
packages to install, click on the @samp{Full/Part} button to get a
full listing, if the package you want to uninstall is not already
listed.  Click on the cycle glyph until the action reads
@samp{Uninstall}.  Proceed with @samp{Next}.

@subsection How do I uninstall @strong{all} of Cygwin?

Setup has no automatic uninstall facility.  Just delete everything
manually:

@itemize @bullet
@item Cygwin shortcuts on the Desktop and Start Menu

@item The registry tree @samp{Software\Red Hat, Inc.} under
@code{HKEY_LOCAL_MACHINE} and/or @code{HKEY_CURRENT_USER}.

@item Anything under the Cygwin root folder, @samp{C:\cygwin} by
default.

@item Anything created by setup in its temporary working directory.

@end itemize

It's up to you to deal with other changes you made to your system, such
as installing the inetd service, altering system paths, etc.  Setup
would not have done any of these things for you.

@subsection Can I use setup to install snapshots?

No.  It used to be possible, but not any more.

If experimenting with developer snapshots from
@file{http://cygwin.com/snapshots/}, you should generally install the
full @code{cygwin-inst-YYYYMMDD.tar.bz2} update, rather than just the
DLL, otherwise some components may be out of sync.  Cygwin tar won't be
able to update @code{/usr/bin/cygwin1.dll}, but it should succeed with
everything else.  The following steps should work:

@enumerate

@item Download the snapshot, and run:
@example
	cd /
        tar jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 --exclude=usr/bin/cygwin1.dll
        cd /tmp
        tar jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 usr/bin/cygwin1.dll
@end example

@item After closing all Cygwin apps (see below), use Explorer or the
Windows command shell to move @code{C:\cygwin\tmp\usr\bin\cygwin1.dll}
to @code{C:\cygwin\bin\cygwin1.dll}.

@end enumerate

The obvious warnings about updating the cygwin package and using developer
snapshots apply:

@enumerate

@item Close all Cygwin apps, including shells and services
(e.g. inetd), before updating @code{cygwin1.dll}.  You may have to
restart Windows to clear the DLL from memory.

@item Snapshots are risky.  They have not been tested.  Use them
@strong{only} if there is a feature or bugfix that you need to try,
and you are willing to deal with any problems.

@item If you cannot download a snapshot from the main ftp distribution
site, use a mirror, and look in the @samp{snapshots} directory.  You may
have to hunt for one that has a copy of the latest snapshot.  Start at
@file{http://cygwin.com/mirrors.html}.

@end enumerate