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.

The following packages are available with the latest net release:

ash, bash, binutils, bison, byacc, bzip2, clear, common, cygwin,
dejagnu, diff, expect, fileutils, findutils, flex, gawk, gcc, gdb,
gperf, grep, groff, gzip, inetutils, less, libpng, login, m4, make, man,
patch, sed, shellutils, tar, tcltk, termcap, texinfo, textutils, time,
zlib

Full source code is available for all packages and tools.

There are a few different ways to install the Cygwin net release, and
we'll try to cover them all here.  It is strongly recommended to use the
automatic @code{setup.exe} program if you can.

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

@strong{IMPORTANT: If you run @code{setup.exe} on an existing Cygwin
installation, Setup will overwrite the contents of mounted directories.
There is no recovery from this.  If you are upgrading from an older
version of Cygwin, you may wish to back up your current installation and
unmount old mount points in order to isolate them.  Then you can
re-install Cygwin in a new location with new mount points, if this is
what you want.}

The @code{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}.

You have a few options when using @code{setup.exe}.  

The @code{setup.exe} program will prompt you for a "root" directory.
The default is 'C:\cygwin', but you can change it.  (You are strongly
urged @strong{not} to choose something like 'C:\'.)  It will contain the
necessary files and directory structure, and will be mounted to '/' as
part of the installation process.

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.  Currently,
@code{setup.exe} creates only binary mounts, but future versions will be
more flexible.

You can let @code{setup.exe} download all the files for you on the fly.
This is the 'internet' installation.  Or you can download all (or some)
of the packages ahead of time, and instruct @code{setup.exe} to install
Cygwin from those files.  This is the 'directory' installation.  You
must use this method if you want to install only a subset of the
available packages.

Note that you cannot combine methods.  If you use the directory
installation, @code{setup.exe} will install @strong{only} the packages
it finds in the directory; it will not also be able to download packages
from the internet in the same pass.  If you have not carefully chosen
which packages to download, you may not end up with a working Cygwin
installation.  You can, however, add and update packages later.  See
below.

Whichever you choose, the first step is to open an ftp mirror site near
you from @file{http://sourceware.cygnus.com/cygwin/mirrors.html}.  Then
go to the 'latest' directory, download @code{setup.exe} and save that to
an @strong{empty temporary directory}.  While you're there, download the
README file and read it.  Then read it again.

Then proceed according to your choice below.

@subsection Internet installation with @code{setup.exe}

Shut down @strong{all cygwin applications} (including inetd, etc.).

Then, @strong{in a command window} ("MS-DOS Prompt" in Windows 95/98),
'@code{cd}' to the temporary directory and type '@code{setup.exe}'.

When prompted, specify the location of the root directory, or accept the
default.

At the next prompt, choose to install from the Internet ('i').  This is
the default.

Setup will connect to sourceware.cygnus.com to read a list of mirror
sites.  Choose one from the list, or choose 'other' to supply your own.
If you supply your own, you must provide a full URL, not just the ftp
hostname.  Setup will then proceed to download all packages from the ftp
site.  Of course this may take a while if you have a slow connection.

When finished, Setup will have created a "Cygnus Solutions" folder on
your Start Menu, containing a shortcut to @code{cygwin.bat}, which
invokes bash with various environment variables set correctly.  The
"Uninstall Cygwin" shortcut, if present, is unlikely to do a complete
job.  If you want to completely uninstall Cygwin, you will probably have
to delete some things by hand.

@subsection Directory installation with @code{setup.exe}

Before proceeding, you must download packages into the temporary
directory containing @code{setup.exe}.  These are in subdirectories of
'latest' and end in .tar.gz and not in -src.tar.gz.  If there is more
than one in a given directory, pick the one with the highest version
number.  Put them together in the temporary directory containing
@code{setup.exe}.  You may preserve the directory structure of 'latest',
and include the -src.tar.gz files, without ill effect.

Whatever subset you think is appropriate, it @strong{must} contain the
'cygwin' package, or you will not end up with a working Cygwin
installation.

When you have all the necessary tar files together with
@code{setup.exe}, proceed as you would for an internet installation,
except choose directory installation ('d') when prompted.  Setup will
install from the tar files that it finds there.  Here are the details
again:

Shut down @strong{all cygwin applications} (including inetd, etc.).

Then, @strong{in a command window} ("MS-DOS Prompt" in Windows 95/98),
'@code{cd}' to the temporary directory and type '@code{setup.exe}'.

When prompted, specify the location of the root directory, or accept the
default.

At the next prompt, choose to install from the current directory ('d').
This is @strong{not} the default.

When finished, Setup will have created a "Cygnus Solutions" folder on
your Start Menu, containing a shortcut to @code{cygwin.bat}, which
invokes bash with various environment variables set correctly.  The
"Uninstall Cygwin" shortcut, if present, is unlikely to do a complete
job.  If you want to completely uninstall Cygwin, you will probably have
to delete some things by hand.

@subsection Adding or updating packages

Later versions of @code{setup.exe} permit you to add and/or update
packages to an existing cygwin installation.

To update your installation, create an empty directory, cd to it, and
download the latest version of @code{setup.exe} from the @code{latest}
directory at a Cygwin mirror near you.

Once you've downloaded @code{setup.exe}, type
@example
	./setup <pkg>
@end example
where "<pkg>" is the name of the package you wish to update, such as
"cygwin" or "gdb" or "make" or ...

Answer the questions as you did when you first installed Cygwin.  This
will update the package.  As with the initial installation, you can
update from the (i)nternet or from the (d)irectory.  The latter requires
that you download the @code{.tar.gz} file of the package ahead of time,
along with @code{setup.exe}.

If you are updating "cygwin", then you must close @strong{all} Cygwin
applications (including @code{inetd}, for example), and run
@code{setup.exe} from the Windows command prompt.

If you supply the @code{-u} option to @code{setup.exe}, then
@code{setup.exe} will only update the package if an older version is
currently installed.  For example:
@example
	./setup -u gdb
@end example
However, if you currently have a development snapshot installed, setup
may fail to update the package, because development snapshots have their
version numbers "bumped" to the next release number.  In this case, you
should not use @code{-u}.  Omitting @code{-u} forces @code{setup.exe} to
perform the update, regardless of whether @code{setup.exe} deems it
necessary.

@subsection Problems running @code{setup.exe}

@subsubsection Error message: "Unable to retrieve the list of cygwin mirrors..."

This means that @code{setup.exe} could not make an http connection to
@file{http://sourceware.cygnus.com/cygwin/mirrors.html}.  This is
required for an (i)nternet install.  Either sourceware.cygnus.com was
too busy, or there is a problem with your network.  Note that
@code{setup.exe} has very limited proxy functionality for firewalls, and
depends on IE4 or later being installed and configured properly.  If you
cannot get the (i)nternet installation to work, just download the
packages yourself and do a (d)irectory install.

@subsubsection System hangs when unpacking tar archives

Your anti-virus software is interfering with @code{setup.exe}.  You will
have to disable it before running setup.  In that case, you will
probably want to:

@enumerate
@item download all the .tar.gz files for the packages, along with @code{setup.exe}
@item scan it all for viruses
@item disable the anti-virus software
@item perform a (d)irectory install
@item scan everything below your Cygwin root directory (@code{C:\cygwin} by default)
@end enumerate