Update URLs for Cygwin packaging information

[newlib-cygwin.git] / winsup / doc / setup-net.xml

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<chapter id="setup-net" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Setting Up Cygwin</title>

<sect1 id="internet-setup">
<title>Internet Setup</title>
<para>To install the Cygwin net release, go to <ulink
url="https://cygwin.com/"/> and run either
<ulink url="https://cygwin.com/setup-x86.exe">setup-x86.exe</ulink>
to install the 32 bit version of Cygwin, or
<ulink url="https://cygwin.com/setup-x86_64.exe">setup-x86_64.exe</ulink>
to install the 64 bit version of Cygwin.  This will download a GUI
installer which can be run to download a complete cygwin installation
via the internet.  Follow the instructions on each screen to install Cygwin.
</para>

<para>
<note>
For easier reading the installer is called <command>setup.exe</command>
throughout the following sections.  This refers likewise to both
installer applications,
<ulink url="https://cygwin.com/setup-x86.exe">setup-x86.exe</ulink>
for 32 bit, as well as
<ulink url="https://cygwin.com/setup-x86_64.exe">setup-x86_64.exe</ulink>
for 64 bit.  Apart from the target architecture they are the same thing.
</note>
</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="https://sourceware.org/git/gitweb.cgi?p=cygwin-setup.git;a=blob_plain;f=README;hb=HEAD">Git <literal>README</literal>
</ulink>. It may already be present in the Git version!
</para>

<para>
On Windows Vista and later, <command>setup.exe</command> will check by
default if it runs with administrative privileges and, if not, will try 
to elevate the process.  If you want to avoid this behaviour and install
under an unprivileged account just for your own usage, run
<command>setup.exe</command> with the <literal>--no-admin</literal> option.
</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="https://cygwin.com/mirrors.html"/>. 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="https://cygwin.com/mirrors.html"/>
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="https://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.
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="https://cygwin.com/problems.html">Reporting
Problems with Cygwin</ulink>.
</para>
</sect2>

</sect1>

<xi:include href="setup-env.xml"/>
<xi:include href="setup-maxmem.xml"/>
<xi:include href="setup-locale.xml"/>
<xi:include href="setup-files.xml"/>
</chapter>