newlib/winsup/doc/install.texinfo

@chapter Installation Instructions
@section Contents

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.  
You can pick and choose the packages you wish to install, and update
them individually.  Full source code is available for all packages and
tools.  More information on using Cygwin Setup may be found at
@file{http://cygwin.com/cygwin-ug-net/setup-net.html}.

If you do it any other way, 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 in the latest development snapshot at
@file{http://cygwin.com/setup/}, then by all means report it to the
mailing list.

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

@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 @samp{C:\} (the root directory on the system drive) for
your Cygwin root.  If you do, then critical Cygwin system directories
like @samp{etc}, @samp{lib} and @samp{bin} could easily be corrupted by
other (non-Cygwin) applications or packages that use @samp{\etc},
@samp{\lib} or @samp{\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 @samp{C:\}, but we believe those are gone
now.)

@subsection Can I use Cygwin Setup to get old versions of packages (like gcc-2.95)?

Cygwin Setup can be used to install any packages that are on a
Cygwin mirror, which usually includes one version previous to the
current one. The complete list may be searched at 
@file{http://cygwin.com/packages/}.  There is no complete archive of
older packages. If you have a problem with the current version of
a Cygwin package, please report it to the mailing list using the 
guidelines at @file{http://cygwin.com/problems.html}.

That said, if you really need an older package, you may be able to find
an outdated or archival mirror by searching the web for an old package
version (for example, @samp{gcc2-2.95.3-10-src.tar.bz2}), but keep in
mind that this older version will not be supported by the mailing list
and that installing the older version will not help improve Cygwin.

@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? Where are 'make', 'gcc', 'vi', etc?  
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. Text editors can be found under ``Editors''.

@subsection How do I just get everything?

Long ago, the default was to install everything, much to the
irritation of most 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 second or two 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.

@item In the latest version of Cygwin Setup, if you click the ``View''
button (twice) more, it shows packages not currently installed.  You
ought to check whether you @emph{really} want to install everything!

@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 weird 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.  Something similar could be the cause of a
download site not 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.

On Windows NT/2000/XP you have two choices:
@enumerate

@item You can rename the user in the Windows User Manager GUI and then
run mkpasswd.

@item You can simply edit the /etc/passwd file and change the Cygwin user name 
(first field). It's also a good idea to avoid spaces in the home directory.

@end enumerate

On Windows 95/98/ME you can create a new user and run mkpasswd, 
or you can delete the offending entry from /etc/passwd. 
Cygwin will then use the name in the default entry with uid 500.

@subsection My @samp{HOME} environment variable is not what I want.

When starting Cygwin from Windows, @samp{HOME} is determined as follows
in order of decreasing priority:

@enumerate

@item @samp{HOME} from the Windows environment, translated to POSIX form.

@item The entry in /etc/passwd

@item @samp{HOMEDRIVE} and @samp{HOMEPATH} from the Windows environment

@item /

@end enumerate

When using Cygwin from the network (telnet, ssh,...), @samp{HOME} is set 
from /etc/passwd.

If your @samp{HOME} is set to a value such as /cygdrive/c, it is likely 
that it was set in Windows. Start a DOS Command Window and type 
"set HOME" to verify if this is the case.

Access to shared drives is often restricted when starting from the network,
thus Domain users may wish to have a different @samp{HOME} in the 
Windows environment (on shared drive) than in /etc/passwd (on local drive).
Note that ssh only considers /etc/passwd, disregarding @samp{HOME}. 

@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.  The recommended method to remove all 
of Cygwin is as follows:

@enumerate

@item Remove all Cygwin services.  If a service is currently running, it must 
first be stopped with @samp{cygrunsrv -E name}, where @samp{name} 
is the name of the service.  Then use @samp{cygrunsrv -R name} to uninstall the 
service from the registry.  Repeat this for all services that you installed.  
Common services that might have been installed are @code{sshd}, @code{cron}, 
@code{cygserver}, @code{inetd}, @code{apache}, and so on.

@item Stop the X11 server if it is running, and terminate any Cygwin programs 
that might be running in the background.  Remove all mount information by typing 
@samp{umount -A} and then exit the command prompt and ensure that no Cygwin 
processes remain.  Note: If you want to save your mount points for a later 
reinstall, first save the output of @samp{mount -m} as described at 
@file{http://cygwin.com/cygwin-ug-net/using-utils.html#mount}.

@item Delete the Cygwin root folder and all subfolders.  If you get an error 
that an object is in use, then ensure that you've stopped all services and 
closed all Cygwin programs.  If you get a 'Permission Denied' error then you 
will need to modify the permissions and/or ownership of the files or folders 
that are causing the error.  For example, sometimes files used by system 
services end up owned by the SYSTEM account and not writable by regular users.  

The quickest way to delete the entire tree if you run into this problem is to 
change the ownership of all files and folders to your account.  To do this in 
Windows Explorer, right click on the root Cygwin folder, choose Properties, then 
the Security tab.  Select Advanced, then go to the Owner tab and make sure your 
account is listed as the owner.  Select the 'Replace owner on subcontainers and 
objects' checkbox and press Ok.  After Explorer applies the changes you should 
be able to delete the entire tree in one operation.  Note that you can also 
achieve this in Cygwin by typing @samp{chown -R user /} or by using other tools 
such as CACLS.EXE.

@item Delete the Cygwin shortcuts on the Desktop and Start Menu, and anything 
left by setup.exe in the download directory.  However, if you plan to reinstall 
Cygwin it's a good idea to keep your setup.exe download directory since you can 
reinstall the packages left in its cache without redownloading them.

@item If you added Cygwin to your system path, you should remove it unless you 
plan to reinstall Cygwin to the same location.  Similarly, if you set your 
CYGWIN environment variable system-wide and don't plan to reinstall, you should 
remove it.

@item Finally, if you want to be thorough you can delete the registry tree 
@samp{Software\Cygnus Solutions} under @code{HKEY_LOCAL_MACHINE} and/or 
@code{HKEY_CURRENT_USER}.  However, if you followed the directions above you 
will have already removed all the mount information which is typically the only 
thing stored in the registry.

@end enumerate

@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

@subsection Can Cygwin Setup maintain a ``mirror''?

NO.  Cygwin Setup cannot do this for you.  Use a tool designed for
this purpose.  See @file{http://rsync.samba.org/},
@file{http://wget.sunsite.dk/} for utilities that can do this for you.
For more information on setting up a custom Cygwin package server, see
the Cygwin Setup homepage at
@file{http://sources.redhat.com/cygwin-apps/setup.html}.

@subsection How can I make my own portable Cygwin on CD?

While some users have successfully done this, for example Indiana
University's XLiveCD @file{http://xlivecd.indiana.edu/}, there is no
easy way to do it. Full instructions for constructing a porttable Cygwin
on CD by hand can be found on the mailing list at
@file{http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html}.  (Thanks
to fergus at bonhard dot uklinux dot net for these instructions.)

@subsection How do I save, restore, delete, or modify the Cygwin information stored in the registry?

Currently Cygwin stores its mount table information in the registry.  It
is recommended that you use the @samp{mount} and @samp{umount} commands
to manipulate the mount information instead of directly modifying the
registry.

To save the mount information to a file for later restoration, use
@samp{mount -m > mounts.bat} To remove all mount information use
@samp{umount -A}.  To reincorporate saved mount information just run the
batch file. For more information on using @samp{mount}, see
@file{http://cygwin.com/cygwin-ug-net/using-utils.html#mount}.