Installation Instructions
*************************

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 `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.

Installation using "Cygwin Setup"
=================================

   The Cygwin Setup program is the _only_ recommended way to install
Cygwin.

Why not install in C:\?
-----------------------

   The Cygwin Setup program will prompt you for a "root" directory.
The default is `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.)

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 `cygwin1.dll' on your
system.

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

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 `setup'.  Read the next entry for a fairly safe way to do this.

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:

  1. Download `setup.exe' and scan it explicitly.

  2. Turn off the anti-virus software.

  3. Run setup to download and extract all the tar files.

  4. 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.


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

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 `http://cygwin.com/packages/'
for a searchable list of available packages.

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

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:

  1. 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 _everything_, not just what it thinks you
     should have by default.

  2. 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.


   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:

  1. 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...

  2. 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 _don't_ want.

  3. 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 _really_ want to install everything!


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 `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.

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 `http://cygwin.com/'.

   If you are downloading from the internet, setup will fail if it
cannot download the list of mirrors at
`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
`setup.log' and `setup.log.full' in `/var/log' (`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.

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 `USER' and `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 `login' package or anything else that reads
/etc/passwd, you may need to make corresponding changes there.  See the
README file for that package.)

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".

How do I uninstall *all* of Cygwin?
-----------------------------------

   Setup has no automatic uninstall facility.  Just delete everything
manually:

   * Cygwin shortcuts on the Desktop and Start Menu

   * The registry tree `Software\Cygnus Solutions' under
     `HKEY_LOCAL_MACHINE' and/or `HKEY_CURRENT_USER'.

   * Anything under the Cygwin root folder, `C:\cygwin' by default.

   * Anything created by setup in its temporary working directory.


   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.

How do I install snapshots?
---------------------------

   First, are you sure you want to do this?  Snapshots are risky.  They
have not been tested.  Use them *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 *all* Cygwin
applications, including shells and services (e.g. inetd, sshd), before
updating `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 `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 `/usr/bin/cygwin1.dll',
but it should succeed with everything else.

  1. Download the snapshot, and run:
          	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

  2. After closing all Cygwin apps (see above), use Explorer or the
     Windows command shell to move `C:\cygwin\tmp\usr\bin\cygwin1.dll'
     to `C:\cygwin\bin\cygwin1.dll'.


Can Cygwin Setup maintain a "mirror"?
-------------------------------------

   NO.  Cygwin Setup cannot do this for you.  Use a tool designed for
this purpose.  See `http://rsync.samba.org/',
`http://sunsite.org.uk/packages/mirror/', `http://wget.sunsite.dk/' for
utilities that can do this for you.

Release Information
*******************

   *(Please note: This section has not yet been updated for the latest
net release.)*

Release Beta 20.1 (Dec 4 1998)
==============================

   This is a bug fix update to the Beta 20 release.

   The main change is an improved version of the Cygwin library although
there are also a couple of other minor changes to the tools.

Changes in specific tools:
--------------------------

   The "-mno-cygwin" flag to gcc now include the correct headers.  In
20.0, it included the Cygwin headers which was incorrect.

   The "-pipe" flag to gcc works correctly now.

   The cygcheck program now reassures users that not finding cpp is the
correct behavior.

   The "-b" flag to md5sum can now be used to generate correct checksums
of binary files.

   The libtermcap library has been added to the compiler tools sources.
It is the new source of the termcap library and /etc/termcap file.

   The less pager (using libtermcap) has been added to the binary
distribution.

Changes in the Cygwin API (cygwin.dll):
---------------------------------------

   This version of Cygwin is backwards-compatible with the beta 20 and
19 releases.  The library is now much more stable under Windows 9x and
the bugs affecting configures under 9x (and NT to a lesser extent) have
also been fixed.

   The bug that made it necessary to start the value of the CYGWIN
environment variable with two leading spaces has been fixed.

   The serial support in the select call has been fixed.

   Handling of DLLs loaded by non-cygwin apps has been improved.  Bugs
in dlopen have been fixed.

   Passing _SC_CHILD_MAX to the sysconf function now yields CHILD_MAX
(63) instead of _POSIX_CHILD_MAX (3).

   Several minor path bugs have been fixed.  Including the one that
caused "mkdir a/" to fail.

   The include file sys/sysmacros.h has been added.  Added missing
protos for wcslen and wcscmp to wchar.h.

   __P is now defined in include/sys/cdefs.h.  To support that last
change, the top-level Makefile.in now sets CC_FOR_TARGET and
CXX_FOR_TARGET differently.

   Cygwin now exports the following newlib bessel functions: j1, jn, y1,
yn.

   Several tty ioctl options have been added: TCGETA, TCSETA, TCSETAW,
and TCSETAF.

   Several functions cope with NULL pointer references more gracefully.

   Problems with execution of relative paths via #! should be fixed.

Release Beta 20 (Oct 30 1998)
=============================

   This is a significant update to the Beta 19 release.  In addition to
an EGCS-based compiler and updated tools, this release includes a new
version of the Cygwin library that contains many improvements and
bugfixes over the last one.

The project has a new name!
---------------------------

   Starting with this release, we are retiring the "GNU-Win32" name for
the releases.  We have also dropped the "32" from Cygwin32.  This means
that you should now refer to the tools as "the Cygwin toolset", the
library as "the Cygwin library" or "the Cygwin DLL", and the library's
interface as "the Cygwin API".

   Because of this name change, we have changed any aspects of the
library that involved the name "Cygwin32".  For example, the CYGWIN32
environment variable is now the CYGWIN environment variable.  API
functions starting with cygwin32_ are still available under that form
for backwards-compatibility as well as under the new cygwin_-prefixed
names.  The same goes for the change of preprocessor define from
__CYGWIN32__ to __CYGWIN__.  We will remove the old names in a future
release so please take the minute or two that it will take to remove
those "32"s.  Thanks and I apologize for the hassle this may cause
people.  We would have changed the name to "Bob" but that name's already
taken by Microsoft...  :-)

   Why change it?  For one thing, not all of the software included in
the distributions is GNU software, including the Cygwin library itself.
So calling the project "GNU-Win32" has always been a bit of a
misnomer.  In addition, we think that calling the tools the "Cygwin
tools" that use the "Cygwin library" will be less confusing to people.

   Also notice that we are now on the spiffy new sourceware.cygnus.com
web/ftp site.  The old address will work for some unknown period of
time (hopefully at least until we get all of the mirrors adjusted).

Changes in specific tools:
--------------------------

   The latest public EGCS release is now the basis for the compiler used
in Cygwin distributions.  As a result, EGCS 1.1 is the compiler in this
release, with a few additional x86/Cygwin-related patches.

   Those of you who are more interested in native Windows development
than in porting Unix programs will be glad to know that a new gcc flag
"-mno-cygwin" will link in the latest Mingw32 libs and produce an
executable that does not use Cygwin.

   All of the other development tools have been updated to their latest
versions.  The linker (ld) includes many important bug fixes.  It is now
possible to safely strip a DLL with a .reloc section.  The windres
resource compiler is significantly improved.

   Beta 20 also includes upgrades to a number of packages: ash-0.3.2-4,
bash 2.02.1, grep-2.2, ncurses 4.2, and less 332.  We have added bzip2
0.9.0 to the distribution.  And you'll now find that the df utility has
joined its other friends from the fileutils package.

   The sh executable is still ash from the Debian Linux distribution
but no longer has the problematic quoting bug that was present in the
Beta 19 release.  Control-Cs in the bash shell no longer kill
background tasks.

   Tcl/tk are upgraded to version 8.1a2 (with additional patches).
Compatible versions of tix and itcl are included.  These all include
Cygwin-compatible configury files so you can do a Unix-style build of
the Win32 ports of tcl/tk.  expect has been upgraded to 5.26 with some
additional Cygwin patches.

   In response to customer requests and feedback, Cygnus has developed a
better graphical front end to GDB than GDBtk or WinGDB.  This tcl-based
GUI is shipping today to customers of the GNUPro Toolkit.  The
instrumentation changes to GDB and the tcl interpreter that was built
into GDB are part of the GPL'd source base.  But the tcl scripts are not
being made available to the net at this time.  For this reason, you will
only find a command-line version of gdb in this Cygwin release.

   DJ Delorie has written a new "cygcheck" program that will print out
useful information about how your Cygwin environment is set up, what
DLLs a named executable is loading from where, etc.  We hope this will
make it easier to help diagnose common setup problems.

   The ps utility has been upgraded.  It now has several options
including shorter and longer output formats.

Changes in the Cygwin API (cygwin.dll):
---------------------------------------

   This version of Cygwin is backwards-compatible with the beta 19
release.  You can use the new "cygwin1.dll" with your old B19-compiled
executables if you move the old "cygwinb19.dll" out of the way and
install a copy of "cygwin1.dll" as "cygwinb19.dll".

   Quite a lot of the Cygwin internals have been rewritten or modified
to address various issues.  If you have a question about specific
changes, the winsup/ChangeLog file in the development tools sources
lists all changes made to the DLL over the last three years.  Following
are a few highlights:

   We are now using a new versioning scheme for Cygwin.  There is now a
separate version number for the DLL, the API, the shared memory region
interfaces, and the registry interface.  This will hopefully make it
easier for multiple Cygwin toolsets to coexist in one user environment.

   Windows 98 is now supported (it is like Windows 95 from Cygwin's
perspective).  We still recommend upgrading to Windows NT.

   While there is still a lot left to do in improving Cygwin's runtime
performance, we have put some effort into this prior to the B20 release.
Hopefully you will find that the latest version of Cygwin is faster than
ever.  In addition, we have plugged several nasty handle leaks
associated with opening/closing files and with using ttys.

   The lseek call now uses WriteFile to fill gaps with zeros whenever a
write is done past an EOF, rather than leaving "undefined" data as Win32
specifies.

   Significant work has been done to improve the Cygwin header files.

   The Cygwin Support for Unix-style serial I/O is much improved.

   Path handling has had another round of fixes/rewrites.  We no longer
use NT Extended Attributes by default for storing Unix
permissions/execute status because the file NT creates on FAT
partitions is not scalable to thousands of files (everything slows to a
crawl).

   Signal handling has also gotten a fair amount of attention.
Unfortunately, there are still some problems combining itimers and
Windows 9x.

   The number of ttys has been upped from 16 to 128.

   New API calls included in the DLL: sethostent, endhostent.

   As mentioned earlier, all cygwin32_-prefixed functions are now
exported with a cygwin_ prefix instead.  Please adjust your code to
call the newly named functions.

   reads of `slow' devices are now correctly interrupted by signals,
i.e.  a read will receive an EINTR.

Known Problems in the Latest Net Release
****************************************

Aware of the problem, no solution known.
========================================

Pipe key (`|') doesn't work on non-US keyboards in Win9x/ME
-----------------------------------------------------------

   This might get fixed someday, but meanwhile, just use rxvt, which
does not have this problem.  This is no real loss, because rxvt has many
other advantages.  (Do not attempt to use the "broken" pipe key (`')
as a substitute, it is a different character.)

Cannot access tape devices with mt on Win9x
-------------------------------------------

   Win9x does not support the API used by the Cygwin fhandler_dev_tape
class.  Details at
`http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html'.

On Win9x, scp leaves ssh processes running.
-------------------------------------------

Fixed in the Next Release
=========================

   (Nothing to report.)

