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.  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.  For the time being, the
procedure is sufficiently well described in these messages from the cygwin
mailing list:

@itemize @bullet
@item @file{http://sourceware.cygnus.com/ml/cygwin/2000-05/msg00433.html}
@item @file{http://sourceware.cygnus.com/ml/cygwin/2000-05/msg00445.html}
@end itemize