"Installation Instructions" for FAQ, first update for current net release.

1 files changed, 154 insertions, 172 deletions

diff --git a/winsup/doc/install.texinfo b/winsup/doc/install.texinfo
index 2efd88e31..02f4d5a58 100644
--- a/winsup/doc/install.texinfo
+++ b/winsup/doc/install.texinfo
@@ -1,178 +1,160 @@
 @chapter Installation Instructions
 @section Contents
 
-@strong{(Please note: This section has not yet been updated for the latest
-net release.)}
+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:
 
-The following packages are included in the full release:
+@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
 
-Development tools:
-binutils, bison, byacc, dejagnu, diff, expect, flex, gas, gcc, gdb,
-itcl, ld, libstdc++, make, patch, tcl, tix, tk
 
-User tools:
-ash, bash, bzip2, diff, fileutils, findutils, gawk, grep, gzip, m4,
-sed, shellutils, tar, textutils, time
-
-The user tools release only contains the user tools.
-
-Full source code is available for these tools.  It is split into
-these two units.
-
-@section Installing the binary release:
-
-@strong{(Please note: This section has not yet been updated for the latest
-net release.)}
-
-Important!  Be sure to remove any older versions of the Cygwin tools
-from your PATH environment variable so you do not execute them by
-mistake.
-
-To download the cygwin files, you may use whatever ftp, browser, or
-other transfer program you are familiar with.  To download multiple
-files without interaction, you may wish to try the @code{wget}
-program.  Visit the cygwin home page's software listings to find a
-pre-built copy of it.
-
-Connect to one of the ftp servers listed above and cd to the directory
-containing the latest release.  A list of mirror sites is at:
-
-@file{http://sourceware.cygnus.com/cygwin/mirrors.html}.
-
-If you want the development tools and the programs necessary to run
-the GNU configure mechanism, you should download the full binary release
-called @file{full.exe}.  If you only care about the user tools
-listed above, download @file{usertools.exe} instead.
-
-If you have an unreliable connection, download the appropriate binary in
-smaller chunks instead.  For the split cdk installer, get the files in
-the @file{full-split} subdirectory.  Once downloaded, combine the
-split files at the command prompt by doing a:
-
-@smallexample
-copy /b xaa + xab + xac + ... + xak + xal full.exe
-del xa*.*
-@end smallexample
-
-A similar process can be used for the user tools.
-
-Once you have an install executable on your system, run it.  If
-a previous version of the software is detected, it will offer to
-uninstall it for you.
-
-Next it will ask you to choose an install location.  The default is
-@file{<system-drive>:\cygnus\cygwin-b20}.  Feel free to choose another
-location if you would prefer.
-
-Finally, it will ask you for the name of the Program Files folder
-shortcut to add.  By default, the installer will create
-a @file{Cygwin B20} entry in a
-folder called @file{Cygnus Solutions}.  When this step is completed, it
-will install the tools and exit.
-
-At this point, you should be able to look under the start menu and
-select "Cygwin B20".  This will pop up a bash shell with all special
-environment variables set up for you.  If you are running Windows 95 or
-98 and are faced with the error message "Out of environment space", you
-need to increase the amount of environment space in your config.sys and
-try again.  Adding the line @code{shell=C:\command.com /e:4096 /p}
-should do the trick if @code{C:} is your system drive letter.
-
-There are two remaining thing you should do from this prompt.
-First, you need to type @code{mkdir -p /tmp} to ensure that a directory
-for temporary files exists for programs that expect to find one there.
-
-Second, if you are installing the full distribution
-(@file{full.exe}), various programs will need to be able to find
-@file{/bin/sh}.  You should @file{mkdir -p /bin} and put a copy of
-@file{sh.exe} there, removing the older version, if present.  You can
-use the @file{mount} utility to select which drive letter is mounted as
-@file{/}. See the Frequently Asked Questions (FAQ) file for more
-information on @file{mount}.
-
-If you should ever want to uninstall the tools, you may do so
-via the "Add/Remove Programs" control panel.
-
-@section Installing the source code
-
-@strong{(Please note: This section has not yet been updated for the latest
-net release.)}
-
-Before downloading the source code corresponding to the release,
-you should install the latest release of the tools (either the full
-release or just the user tools).
-
-Create the directory that will house the source code.  @file{cd}
-there.
-
-Connect to one of the ftp servers listed above and cd to the directory
-containing the latest release.  A list of mirror sites is at:
-
-@file{http://sourceware.cygnus.com/cygwin/mirrors.html}.
-
-If you want the user tools source code, @file{cd} into the
-@file{user-src-split} subdirectory.  Download the files there.  If you
-want the development tools sources, @file{cd} into the
-@file{dev-src-split} subdirectory.  Download the files there.
-
-Back in the Windows command shell, for the user tools source:
-
-@smallexample
-copy /b xba + xbb + xbc + xbd + xbe + xbf + xbg user-src.tar.bz2
-del xb*.*
-bunzip2 user-src.tar.bz2
-tar xvf user-src.tar
-@end smallexample
-
-For the development tools source:
-
-@smallexample
-copy /b xca + xcb + xcc + xcd + ... + xck + xcl dev-src.tar.bz2
-del xc*.*
-bunzip2 dev-src.tar.bz2
-tar xvf dev-src.tar
-@end smallexample
-
-Both expand into a directory called @file{src}.
-
-Note: if you want the sources corresponding to everything in the
-full.exe binary installer, you will need to download and expand both
-the user-src.tar.bz2 and dev-src.tar.bz2 source archives!
-
-And you should be done...
-
-@section Upgrading to B20.1
-
-@strong{(Please note: This section has not yet been updated for the latest
-net release.  Even the section's title is wrong!)}
-
-If you downloaded the original B20.0 release, you should definitely at
-least upgrade the Cygwin library to the version present in B20.1.  To do
-this, download the file
-@file{cygwin-b20/cygwin1-20.1.dll.bz2} from one of our mirror sites,
-decompress it with bunzip2, and then install the dll, replacing
-the file cygwin-b20/H-i586-cygwin32/bin/cygwin1.dll in your original
-installation of 20.0.
-
-There are some additional patches in a few of the other tools
-(including a gcc change that makes -mno-cygwin find the correct header
-files).  In addition, the tools have been built with a compiled-in path
-of /cygnus/cygwin-b20/ which will make some tools such as bison find
-their library files without help from environment variables.
-To install the full 20.1 release, you will need to download the
-correct installer from scratch.  It will offer to uninstall the existing
-release and replace it with 20.1 (You should choose to uninstall b20 and
-proceed).
-
-We have diff files on the ftp site that can be used to upgrade the
-original B20.0 sources.  20.0-20.1-dev-src.diff.bz2 upgrades the
-development tools sources.  20.0-20.1-user-src.diff.bz2 upgrades the
-user tools sources.  They come compressed so you'll need to bunzip2 them
-before proceeding.  As an example, if the development tools are in the
-directory called "src" and the patch is in the directory above it, apply
-the patch as follows:
-
-@smallexample
-cd src
-patch -p1 -E < ../20.0-20.1-dev-src.diff
-@end smallexample