From 7d37d0459e69585b90a27d82380aebc3a2a82a84 Mon Sep 17 00:00:00 2001 From: Joshua Daniel Franklin Date: Sat, 22 Mar 2003 20:03:41 +0000 Subject: [PATCH] * setup-net.sgml: Document setup.exe --- winsup/doc/ChangeLog | 4 + winsup/doc/setup-net.sgml | 201 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 548a60759..e904ce8dd 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,7 @@ +2003-03-22 Joshua Daniel Franklin + + * setup-net.sgml: Document setup.exe + 2003-02-07 Christopher Faylor * how.texinfo: Add more w32api words. diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml index 547439249..968494796 100644 --- a/winsup/doc/setup-net.sgml +++ b/winsup/doc/setup-net.sgml @@ -7,6 +7,207 @@ URL="http://cygwin.com/">"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. + + +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. +Though this provides some basic mirroring functionality, if you +are managing a wide Cygwin installation 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. All Windows drives can be accessed +with the /cygdrive/X/ virtual directory and +Cygwin's mount utility. + + +The Install For options of +All Users or +Just Me are especially for multiuser systems +or Domain users. If you have a single-user workstation, this +option probably does not concern you. If you are seeking to rollout +Cygwin on a large Domain, you will want to think carefully +about the implications of each type and possibly consult the Cygwin +mailing list archives about others' experiences. + + +The Default Text File Type should be left on +Unix (that is, \n) unless you +have a very good reason to switch it to +DOS (that is, \r\n). + + + +Local Package Directory + +The Local Package Directory is the cache where +setup.exe stores the packages before they are +installed. The cache should 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 + +For most users, the Direct Connection method +of downloading is the best choice. If you have a proxy server, +you can use the Use IE5 Settings if it is +already set up in Internet Exlporer, or 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.ini that contains a list +of packages available from that site along with some basic information about +each package (version number, dependencies, checksum, etc.) which +setup.exe parses and uses to create the chooser window. + + +The chooser is the most complex part of setup.exe. +Packages are divided into categories. By default setup.exe +will install only the packages in the Base category +and their dependencies, resulting in a very basic Cygwin installation. +However, this will not include many commonly used tools such as +gcc (which you will find in the Devel +category). + + +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 Partial (only packages to be 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 just like +you had 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. + + +The final feature of the setup.exe chooser is for +Previous and Experimental packages. +By default the chooser shows only the current version of each package, +though mirrors have at least one previous version and occasionally there +is a testing or beta version of a package available. To see these package, +click on the Prev or Exp radio button. +Be warned, however, that the next time you run setup.exe +it will try to replace old or experimental versions with the latest. + + + +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 +show progress bars for the current task and total remaining disk space. + + + +Icons + +You may choose to install shortcuts on the Desktop and/or Start Menu +to start a bash shell. If you prefer to use a different +shell or the native Windows version of rxvt, you can +use these shortcuts as a guide to creating your own. + + + +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, the scripts are kept in the +/etc/postinstall/ directory, renamed with a +done extension after being run. 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 +directory. + + + DOCTOOL-INSERT-setup-env