From 8142972d870f24ae9683238889aa63bb395d3698 Mon Sep 17 00:00:00 2001 From: Warren Young Date: Wed, 1 May 2013 23:30:25 +0000 Subject: Modernized user guide, API reference, and FAQ generation. Overall effect is to move away from DocBook SGML and DJ Delorie's doctool and toward pure DocBook XSL. (There remains just one use of doctool, and we have plans for replacing it, too.) See ChangeLog for details. --- winsup/doc/setup-net.xml | 269 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 winsup/doc/setup-net.xml (limited to 'winsup/doc/setup-net.xml') diff --git a/winsup/doc/setup-net.xml b/winsup/doc/setup-net.xml new file mode 100644 index 000000000..877489b9c --- /dev/null +++ b/winsup/doc/setup-net.xml @@ -0,0 +1,269 @@ + + + + +Setting Up Cygwin + + +Internet Setup +To install the Cygwin net release, go to http://cygwin.com/ and click on "Install Cygwin Now!". This will +download a GUI installer called setup.exe which can +be run to download a complete cygwin installation via the internet. +Follow the instructions on each screen to install Cygwin. + + + +The setup.exe 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 setup.exe; before requesting a new feature, +check the wishlist in the CVS README +. It may already be present in the CVS version! + + + +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 Next button +at each page. The only exception to this is choosing a Cygwin mirror, +which you can choose by experimenting with those listed at + +http://cygwin.com/mirrors.html +. For more details about each of page of the +setup.exe 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 +other resources. + + +Download Source + +Cygwin uses packages to manage installing various software. When +the default Install from Internet option is chosen, +setup.exe creates a local directory to store +the packages before actually installing the contents. +Download from Internet performs only the first +part (storing the packages locally), while +Install from Local Directory performs only the +second (installing the contents of the packages). + + +The Download from Internet option is mainly +for creating a base Cygwin package tree on one computer for +installation on several machines with +Install from Local Directory; copy the +entire local package tree to another machine with the directory +tree intact. For example, you might create a C:\cache\ +directory and place setup.exe in it. Run +setup.exe to Install from Internet +or Download from Internet, then copy the whole +C:\cache\ to each machine and instead choose +Install from Local Directory. + + +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 wget. A helpful user on +the Cygwin mailing list created a simple demonstration script to accomplish +this; search the list for mkcygwget for ideas. + + + +Selecting an Install Directory + +The Root Directory for Cygwin (default +C:\cygwin) will become / +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. + + +The Install For options of All Users +or Just Me should always be left on the default +All Users, unless you do not have write access to +HKEY_LOCAL_MACHINE 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 Just Me will cause problems +for programs such as crond and sshd. +If you do not have the necessary permissions, but still want to use these +programs, consult the Cygwin mailing list archives about others' experiences. + + + + +Local Package Directory + +The Local Package Directory is the cache where +setup.exe 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 setup.exe 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. + + + +Connection Method + +The Direct Connection 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 Use Proxy section. Unfortunately, +setup.exe does not currently support password +authorization for proxy servers. + + + +Choosing Mirrors + +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 http://cygwin.com/mirrors.html +to find one near you. You can select multiple mirrors by holding down +CTRL 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. + + + +Choosing Packages + +For each selected mirror site, setup.exe downloads a +small text file called setup.bz2 that contains a list +of packages available from that site along with some basic information about +each package which setup.exe parses and uses to create the +chooser window. For details about the format of this file, see +the +setup.exe homepage. + + +The chooser is the most complex part of setup.exe. +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, setup.exe +will install only the packages in the Base category +and their dependencies, resulting in a minimal Cygwin installation. +However, this will not include many commonly used tools such as +gcc (which you will find in the Devel +category). Since setup.exe automatically selects +dependencies, be careful not to unselect any required packages. In +particular, everything in the Base category is +required. + + +You can change setup.exe'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 View button and it will rotate between +Category (the default), Full (all +packages), and Pending (only packages to be +installed, removed or upgraded). +If you are familiar with Unix, you will probably want to at least glance +through the Full listing for your favorite tools. + + +Once you have an existing Cygwin installation, the setup.exe +chooser is also used to manage your Cygwin installation. +Information on installed packages is kept in the +/etc/setup/ directory of your Cygwin installation; if +setup.exe cannot find this directory it will act as if +you have no Cygwin installation. If setup.exe +finds a newer version of an installed package available, it will automatically +mark it to be upgraded. +To Uninstall, Reinstall, or get the +Source for an existing package, click on +Keep 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 +setup.exe begins to install the upgraded package. + + +To avoid unintentionally upgrading, use the Pending +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 Keep. All packages can be +set to stay at the installed version by pressing the Keep +button in the top right part of the chooser window. + + +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 +New column until the required version appears. + + +All available experimental packages can be selected by pressing the +Exp in the top right part of the chooser window. +Be warned, however, that the next time you run setup.exe +it will try to replace all old or experimental versions with the current +version, unless told otherwise. + + + +Download and Installation Progress + +First, setup.exe will download all selected packages +to the local directory chosen earlier. Before installing, +setup.exe 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, setup.exe +shows progress bars for the current task and total remaining disk space. + + + +Shortcuts + +You may choose to install "Cygwin Terminal" shortcuts on the Desktop +and/or Start Menu. These shortcuts run mintty, +which will start your default shell as specified +in /etc/passwd. + + + +Post-Install Scripts + +Last of all, setup.exe 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 http://cygwin.com/setup.html +When the last post-install script is completed, setup.exe +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 /usr/doc/Cygwin/ +or /usr/share/doc/Cygwin/ directory. + + +Troubleshooting + +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 setup.exe log file +at /var/log/setup.log.full. Make a backup of this +file before running setup.exe again, and follow the +steps for Reporting +Problems with Cygwin. + + + + + + + + + + -- cgit v1.2.3