newlib/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 only one recommended way to install Cygwin, which is to use the GUI
installer ``Cygwin Setup''.  It is flexible and easy to use.

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 ``Cygwin Setup''

The Cygwin Setup program is the @emph{only} recommended way to install
Cygwin.

@subsection Why not install in C:\?

The Cygwin Setup 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 Cygwin 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 Cygwin Setup.  The
overall structure has changed so much that it would be pointless to
try to accomodate old installations of Cygwin.  You will 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.  Make sure you
don't end up with two different versions of @samp{cygwin1.dll} on your
system.

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

@subsection Is Cygwin Setup, 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 run Cygwin Setup!

Both Network Associates (formerly McAfee) and Norton anti-virus
products have been reported to "hang" when extracting Cygwin tar
archives.  If this happens to you, consider disabling your anti-virus
software when running Cygwin 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), or your entire hard
disk if you are paranoid.

@end enumerate

This should be safe, but only if Cygwin Setup is not substituted by
something malicious, and no mirror has been compromised.

@subsection What packages should I download?

When using Cygwin Setup for the first time, the default is to install
a minimal subset of packages.  If you want anything beyond that, you
will have to select it explicitly.  See
@file{http://cygwin.com/packages/} for a searchable list of available
packages.

If you want to build programs, of course you'll need @samp{gcc},
@samp{binutils}, @samp{make} and probably other packages from the
``Devel'' category.

@subsection How do I just get everything?

In the past, the default was to install everything, much to the
irritation of many users.  Now the default is to install only a basic
core of packages.  Cygwin Setup is designed to make it easy to browse
categories and select what you want to install or omit from those
categories.  It's also easy to install everything:

@enumerate

@item At the ``Select Packages'' screen, in ``Categories'' view, at the line 
marked ``All'', click on the word ``default'' so that it changes to
``install''.  (Be patient, there is some computing to do at this step.
It may take a few seconds to register the change.)  This tells Setup
to install @emph{everything}, not just what it thinks you should have
by default.

@item Now click on the ``View'' button (twice) until you get the
``Partial'' view.  This shows exactly which packages are about to be
downloaded and installed.

@end enumerate

This procedure only works for packages that are currently available.
There is no way to tell Cygwin Setup to install all packages by
default from now on.  As new packages become available that would not
be installed by default, you have to repeat the above procedure to get
them.

In general, a better method (in my opinion), is to:

@enumerate

@item First download & install all packages that would normally be
installed by default.  This includes fundamental packages and any
updates to what you have already installed.  Then...

@item Run Cygwin Setup again, and apply the above technique to get all
new packages that would not be installed by default.  You can check
the list in the Partial View before proceeding, in case there's
something you really @emph{don't} want.

@end enumerate

@subsection How much disk space does Cygwin require?

That depends, obviously, on what you've chosen to download and
install.  A full installation today is probably larger than 800MB
installed, not including the package archives themselves nor the source
code.

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 subdirectories there.  These
directories will have very wierd looking names, being encoded with
their URLs.

@subsection What if setup fails?

First, make sure that you are using the latest version of Cygwin
Setup.  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 @code{/var/log}
(@code{C:\cygwin\var\log} 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 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 Cygwin Setup as you would to install packages.  In the list of
packages to install, browse the relevant category or click on the
``View'' button to get a full listing.  Click on the cycle glyph until
the action reads ``Uninstall''.  Proceed by clicking ``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\Cygnus Solutions} 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 How do I install snapshots?

First, are you sure you want to do this?  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.

Before installing a snapshot, you must first Close @strong{all} Cygwin
applications, including shells and services (e.g. inetd, sshd), before
updating @code{cygwin1.dll}.  You may have to restart Windows to clear
the DLL from memory.

You cannot use Setup to install a snapshot.

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.

@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 above), 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