1692ae3a30
Try to be clearer on POSIX vs. Win32 paths. (unc-paths): New section. (cygdrive): Fix a few SGML qualifiers. * setup-net.sgml: Move ntsec section from here... * using.sgml: ..to here.
265 lines
12 KiB
Plaintext
265 lines
12 KiB
Plaintext
<chapter id="setup-net"><title>Setting Up Cygwin</title>
|
|
|
|
<sect1 id="internet-setup">
|
|
<title>Internet Setup</title>
|
|
<para>To install the Cygwin net release, go to <ulink
|
|
url="http://cygwin.com/">http://cygwin.com/</ulink> and click on <ulink
|
|
url="http://cygwin.com/setup.exe">"Install Cygwin Now!"</ulink>. This will
|
|
download a GUI installer called <command>setup.exe</command> which can
|
|
be run to download a complete cygwin installation via the internet.
|
|
Follow the instructions on each screen to install Cygwin.
|
|
</para>
|
|
|
|
<para>
|
|
The <command>setup.exe</command> installer is designed to be easy
|
|
for new users to understand while remaining flexible for the
|
|
experienced. The volunteer development team is constantly working
|
|
on <command>setup.exe</command>; before requesting a new feature,
|
|
check the wishlist in the <ulink url="http://sourceware.org/cgi-bin/cvsweb.cgi/setup/README?cvsroot=cygwin-apps&rev=2">CVS <literal>README</literal>
|
|
</ulink>. It may already be present in the CVS version!
|
|
</para>
|
|
|
|
<para>
|
|
Since the default value for each option is the logical choice for
|
|
most installations, you can get a working minimal Cygwin environment
|
|
installed by simply clicking the <literal>Next</literal> button
|
|
at each page. The only exception to this is choosing a Cygwin mirror,
|
|
which you can choose by experimenting with those listed at
|
|
<ulink url="http://cygwin.com/mirrors.html">
|
|
http://cygwin.com/mirrors.html
|
|
</ulink>. For more details about each of page of the
|
|
<command>setup.exe</command> installation, read on below.
|
|
Please note that this guide assumes that you have a basic understanding
|
|
of Unix (or a Unix-like OS). If you are new to Unix, you will also want
|
|
to make use of <ulink url="http://www.google.com/search?q=new+to+unix">
|
|
other resources</ulink>.
|
|
</para>
|
|
|
|
<sect2 id="setup-download"><title>Download Source</title>
|
|
<para>
|
|
Cygwin uses packages to manage installing various software. When
|
|
the default <literal>Install from Internet</literal> option is chosen,
|
|
<command>setup.exe</command> creates a local directory to store
|
|
the packages before actually installing the contents.
|
|
<literal>Download from Internet</literal> performs only the first
|
|
part (storing the packages locally), while
|
|
<literal>Install from Local Directory</literal> performs only the
|
|
second (installing the contents of the packages).
|
|
</para>
|
|
<para>
|
|
The <literal>Download from Internet</literal> option is mainly
|
|
for creating a base Cygwin package tree on one computer for
|
|
installation on several machines with
|
|
<literal>Install from Local Directory</literal>; copy the
|
|
entire local package tree to another machine with the directory
|
|
tree intact. For example, you might create a <literal>C:\cache\</literal>
|
|
directory and place <command>setup.exe</command> in it. Run
|
|
<command>setup.exe</command> to <literal>Install from Internet</literal>
|
|
or <literal>Download from Internet</literal>, then copy the whole
|
|
<literal>C:\cache\</literal> to each machine and instead choose
|
|
<literal>Install from Local Directory</literal>.
|
|
</para>
|
|
<para>
|
|
Though this provides some basic mirroring functionality, if you
|
|
are managing a large Cygwin installation, to keep up to date we recommend
|
|
using a mirroring tool such as <command>wget</command>. A helpful user on
|
|
the Cygwin mailing list created a simple demonstration script to accomplish
|
|
this; search the list for <command>mkcygwget</command> for ideas.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-dir"><title>Selecting an Install Directory</title>
|
|
<para>
|
|
The <literal>Root Directory</literal> for Cygwin (default
|
|
<literal>C:\cygwin</literal>) will become <literal>/</literal>
|
|
within your Cygwin installation. You must have write access to
|
|
the parent directory, and any ACLs on the parent directory will
|
|
determine access to installed files.
|
|
</para>
|
|
<para>
|
|
The <literal>Install For</literal> options of <literal>All Users</literal>
|
|
or <literal>Just Me</literal> should always be left on the default
|
|
<literal>All Users</literal>, unless you do not have write access to
|
|
<literal>HKEY_LOCAL_MACHINE</literal> in the registry or the All Users
|
|
Start Menu. This is true even if you are the only user planning to use Cygwin
|
|
on the machine. Selecting <literal>Just Me</literal> will cause problems
|
|
for programs such as <command>crond</command> and <command>sshd</command>.
|
|
If you do not have the necessary permissions, but still want to use these
|
|
programs, consult the Cygwin mailing list archives about others' experiences.
|
|
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-localdir"><title>Local Package Directory</title>
|
|
<para>
|
|
The <literal>Local Package Directory</literal> is the cache where
|
|
<command>setup.exe</command> stores the packages before they are
|
|
installed. The cache must not be the same folder as the Cygwin
|
|
root. Within the cache, a separate directory is created for each
|
|
Cygwin mirror, which allows <command>setup.exe</command> to use
|
|
multiple mirrors and custom packages. After installing Cygwin,
|
|
the cache is no longer necessary, but you may want to retain the
|
|
packages as backups, for installing Cygwin to another system,
|
|
or in case you need to reinstall a package.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-connection"><title>Connection Method</title>
|
|
<para>
|
|
The <literal>Direct Connection</literal> method of downloading will
|
|
directly download the packages, while the IE5 method will leverage your
|
|
IE5 cache for performance. If your organisation uses a proxy server or
|
|
auto-configuration scripts, the IE5 method also uses these settings.
|
|
If you have a proxy server, you can manually type it into
|
|
the <literal>Use Proxy</literal> section. Unfortunately,
|
|
<command>setup.exe</command> does not currently support password
|
|
authorization for proxy servers.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-mirror"><title>Choosing Mirrors</title>
|
|
<para>
|
|
Since there is no way of knowing from where you will be downloading
|
|
Cygwin, you need to choose at least one mirror site. Cygwin mirrors
|
|
are geographically distributed around the world; check the list at <ulink
|
|
url="http://cygwin.com/mirrors.html">http://cygwin.com/mirrors.html</ulink>
|
|
to find one near you. You can select multiple mirrors by holding down
|
|
<literal>CTRL</literal> and clicking on each one. If you have the URL of
|
|
an unlisted mirror (for example, if your organization has an internal Cygwin
|
|
mirror) you can add it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-packages"><title>Choosing Packages</title>
|
|
<para>
|
|
For each selected mirror site, <command>setup.exe</command> downloads a
|
|
small text file called <literal>setup.bz2</literal> that contains a list
|
|
of packages available from that site along with some basic information about
|
|
each package which <command>setup.exe</command> parses and uses to create the
|
|
chooser window. For details about the format of this file, see
|
|
the <ulink url="http://sourceware.org/cygwin-apps/setup.html">
|
|
setup.exe homepage</ulink>.
|
|
</para>
|
|
<para>
|
|
The chooser is the most complex part of <command>setup.exe</command>.
|
|
Packages are grouped into categories, and one package may belong to multiple
|
|
categories (assigned by the volunteer package maintainer). Each package
|
|
can be found under any of those categories in the hierarchical chooser view.
|
|
By default, <command>setup.exe</command>
|
|
will install only the packages in the <literal>Base</literal> category
|
|
and their dependencies, resulting in a minimal Cygwin installation.
|
|
However, this will not include many commonly used tools such as
|
|
<command>gcc</command> (which you will find in the <literal>Devel</literal>
|
|
category). Since <command>setup.exe</command> automatically selects
|
|
dependencies, be careful not to unselect any required packages. In
|
|
particular, everything in the <literal>Base</literal> category is
|
|
required.
|
|
</para>
|
|
<para>
|
|
You can change <command>setup.exe</command>'s view style, which is helpful
|
|
if you know the name of a package you want to install but not which
|
|
category it is in.
|
|
Click on the <literal>View</literal> button and it will rotate between
|
|
<literal>Category</literal> (the default), <literal>Full</literal> (all
|
|
packages), and <literal>Pending</literal> (only packages to be
|
|
installed, removed or upgraded).
|
|
If you are familiar with Unix, you will probably want to at least glance
|
|
through the <literal>Full</literal> listing for your favorite tools.
|
|
</para>
|
|
<para>
|
|
Once you have an existing Cygwin installation, the <command>setup.exe</command>
|
|
chooser is also used to manage your Cygwin installation.
|
|
Information on installed packages is kept in the
|
|
<literal>/etc/setup/</literal> directory of your Cygwin installation; if
|
|
<command>setup.exe</command> cannot find this directory it will act as if
|
|
you have no Cygwin installation. If <command>setup.exe</command>
|
|
finds a newer version of an installed package available, it will automatically
|
|
mark it to be upgraded.
|
|
To <literal>Uninstall</literal>, <literal>Reinstall</literal>, or get the
|
|
<literal>Source</literal> for an existing package, click on
|
|
<literal>Keep</literal> to toggle it.
|
|
Also, to avoid the need to reboot after upgrading, make sure
|
|
to close all Cygwin windows and stop all Cygwin processes before
|
|
<command>setup.exe</command> begins to install the upgraded package.
|
|
</para>
|
|
<para>
|
|
To avoid unintentionally upgrading, use the <literal>Pending</literal>
|
|
view to see which packages have been marked for upgrading. If you
|
|
don't want to upgrade a package, click on the new version number to
|
|
toggle it until it says <literal>Keep</literal>. All packages can be
|
|
set to stay at the installed version by pressing the <literal>Keep</literal>
|
|
button in the top right part of the chooser window.
|
|
</para>
|
|
<para>
|
|
A previous version of each package is usually available, in case downgrading
|
|
is required to avoid a serious bug in the current version of the package.
|
|
Packages also occasionally have testing (or "experimental") versions available.
|
|
Previous and experimental versions can be chosen by clicking on the package's
|
|
<literal>New</literal> column until the required version appears.
|
|
</para>
|
|
<para>
|
|
All available experimental packages can be selected by pressing the
|
|
<literal>Exp</literal> in the top right part of the chooser window.
|
|
Be warned, however, that the next time you run <command>setup.exe</command>
|
|
it will try to replace all old or experimental versions with the current
|
|
version, unless told otherwise.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-progress"><title>Download and Installation Progress</title>
|
|
<para>
|
|
First, <command>setup.exe</command> will download all selected packages
|
|
to the local directory chosen earlier. Before installing,
|
|
<command>setup.exe</command> performs a checksum on each package. If the
|
|
local directory is a slow medium (such as a network drive) this can take
|
|
a long time. During the download and installation, <command>setup.exe</command>
|
|
shows progress bars for the current task and total remaining disk space.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-icons"><title>Shortcuts</title>
|
|
<para>
|
|
You may choose to install "Cygwin Terminal" shortcuts on the Desktop
|
|
and/or Start Menu. These shortcuts run <command>mintty</command>,
|
|
which will start your default shell as specified
|
|
in <filename>/etc/passwd</filename>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="setup-postinstall"><title>Post-Install Scripts</title>
|
|
<para>
|
|
Last of all, <command>setup.exe</command> will run any post-install
|
|
scripts to finish correctly setting up installed packages. Since each
|
|
script is run separately, several windows may pop up. If you are
|
|
interested in what is being done, see the Cygwin Package Contributor's
|
|
Guide at <ulink
|
|
url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink>
|
|
When the last post-install script is completed, <command>setup.exe</command>
|
|
will display a box announcing the completion. A few packages, such as
|
|
the OpenSSH server, require some manual site-specific configuration.
|
|
Relevant documentation can be found in the <literal>/usr/doc/Cygwin/</literal>
|
|
or <literal>/usr/share/doc/Cygwin/</literal> directory.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="setup-troubleshooting"><title>Troubleshooting</title>
|
|
<para>
|
|
Unfortunately, the complex setup process means that odd problems can
|
|
occur. If you're having trouble downloading packages, it may be network
|
|
congestion, so try a different mirror and/or a different protocol (i.e.,
|
|
HTTP instead of FTP). If you notice something is not working after
|
|
running setup, you can check the <command>setup.exe</command> log file
|
|
at <literal>/var/log/setup.log.full</literal>. Make a backup of this
|
|
file before running <command>setup.exe</command> again, and follow the
|
|
steps for <ulink url="http://cygwin.com/problems.html">Reporting
|
|
Problems with Cygwin</ulink>.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
DOCTOOL-INSERT-setup-env
|
|
DOCTOOL-INSERT-setup-maxmem
|
|
DOCTOOL-INSERT-setup-locale
|
|
DOCTOOL-INSERT-setup-files
|
|
</chapter>
|