[PATCH] Proposed clarification of the snapshot installation FAQ
Igor Peshansky
pechtcha@cs.nyu.edu
Thu Jan 12 02:40:00 GMT 2006
As mentioned in <http://cygwin.com/ml/cygwin/2006-01/msg00537.html>,
here's a patch to the FAQ to clarify the section on installing snapshots.
I didn't know whether the various *.texinfo files are still used, so I
ported the modifications there as well, just in case.
The ChangeLog is below.
Igor
===============================================================================
2006-01-11 Igor Peshansky <pechtcha@cs.nyu.edu>
* faq-setup.xml (faq.setup.setup): Correct URL typo.
(faq.setup.snapshots): Clarify.
* install.texinfo (Contents): Correct URL typo.
(How do I install snapshots): Clarify.
--
http://cs.nyu.edu/~pechtcha/
|\ _,,,---,,_ pechtcha@cs.nyu.edu | igor@watson.ibm.com
ZZZzz /,`.-'`' -. ;-;;,_ Igor Peshansky, Ph.D. (name changed!)
|,4- ) )-,_. ,\ ( `'-' old name: Igor Pechtchanski
'---''(_/--' `-'\_) fL a.k.a JaguaR-R-R-r-r-r-.-.-. Meow!
"Las! je suis sot... -Mais non, tu ne l'es pas, puisque tu t'en rends compte."
"But no -- you are no fool; you call yourself a fool, there's proof enough in
that!" -- Rostand, "Cyrano de Bergerac"
-------------- next part --------------
Index: faq-setup.xml
===================================================================
RCS file: /cvs/src/src/winsup/doc/faq-setup.xml,v
retrieving revision 1.2
diff -u -p -r1.2 faq-setup.xml
--- faq-setup.xml 4 Dec 2005 03:55:28 -0000 1.2
+++ faq-setup.xml 12 Jan 2006 02:33:20 -0000
@@ -15,7 +15,7 @@ that the GUI installer is a "work in pro
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 in the latest development snapshot at
-<ulink url="http://cygwin.com/setup/">http://cygwin.com/setup/</ulink>, then by all means report it to the
+<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>, then by all means report it to the
mailing list.
</para>
<para>For a searchable list of packages that can be installed with Cygwin,
@@ -392,37 +392,54 @@ thing stored in the registry.
<para>First, are you sure you want to do this? Snapshots are risky. They
have not been tested. Use them <emphasis role='bold'>only</emphasis> if there is a feature or
bugfix that you need to try, and you are willing to deal with any
-problems.
-</para>
-<para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin
-applications, including shells and services (e.g. inetd, sshd), before
-updating <literal>cygwin1.dll</literal>. You may have to restart Windows to clear
-the DLL from memory.
-</para>
-<para>You cannot use Setup to install a snapshot.
+problems, or at the request of a Cygwin developer.
</para>
<para>You should generally install the full
<literal>cygwin-inst-YYYYMMDD.tar.bz2</literal> update, rather than just the DLL,
-otherwise some components may be out of sync. Cygwin tar won't be
-able to update <literal>/usr/bin/cygwin1.dll</literal>, but it should succeed with
-everything else.
+otherwise some components may be out of sync.
</para>
-<orderedlist>
-<listitem><para>Download the snapshot, and run:
+<para>You cannot use Cygwin Setup to install a snapshot.
+</para>
+<para>First, you will need to download the snapshot from the snapshots
+page at <ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>. Note the directory where
+you saved the snapshot tarball.
+</para>
+<para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin
+applications, including shells and services (e.g., <literal>inetd</literal>, <literal>sshd</literal>).
+You will not be able to replace <literal>cygwin1.dll</literal> if any Cygwin process is
+running. You may have to restart Windows to clear the DLL from memory
+(beware of automatic service startup).
+</para>
+<para>Most of the downloaded snapshot can be installed using <literal>tar</literal>. Cygwin
+<literal>tar</literal> won't be able to update <literal>/usr/bin/cygwin1.dll</literal> (because it's
+used by <literal>tar</literal> itself), but it should succeed with everything else. If
+you are only installing the DLL snapshot, skip the first tar command. Open
+a <literal>bash</literal> shell (it should be the only running Cygwin process) and issue
+the following commands:
<screen>
- 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
+ /bin/tar -C/ -jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 --exclude=usr/bin/cygwin1.dll
+ /bin/tar -C/tmp -jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 usr/bin/cygwin1.dll
+ /bin/mv /bin/cygwin1.dll /bin/cygwin1-prev.dll
</screen>
</para>
-</listitem>
-<listitem><para>After closing all Cygwin apps (see above), use Explorer or the
+<para>Note that after the "<literal>mv</literal>" command you will not be able to run any
+Cygwin programs. Exit the bash shell, and use Explorer or the
Windows command shell to move <literal>C:\cygwin\tmp\usr\bin\cygwin1.dll</literal>
-to <literal>C:\cygwin\bin\cygwin1.dll</literal>.
+to <literal>C:\cygwin\bin\cygwin1.dll</literal> (assuming you installed Cygwin in
+<literal>C:\cygwin</literal>).
+</para>
+<para>The operative word in trying the snapshots is "<emphasis>trying</emphasis>". If you
+notice a problem with the snapshot that was not present in the release
+DLL (what we call a "regression"), please report it to the Cygwin
+mailing list (see <ulink url="http://cygwin.com/problems.html">http://cygwin.com/problems.html</ulink> for problem
+reporting guidelines). If you wish to go back to the older version of the
+DLL, again, close all Cygwin processes, delete
+<literal>C:\cygwin\bin\cygwin1.dll</literal>, and
+rename <literal>C:\cygwin\bin\cygwin1-prev.dll</literal> back to
+<literal>C:\cygwin\bin\cygwin1.dll</literal> (again assuming that your "<literal>/</literal>" is
+<literal>C:\cygwin</literal>). To restore the rest of the snapshot
+files, reinstall the "<literal>cygwin</literal>" package using Setup.
</para>
-</listitem>
-</orderedlist>
</answer></qandaentry>
Index: install.texinfo
===================================================================
RCS file: /cvs/src/src/winsup/doc/install.texinfo,v
retrieving revision 1.53
diff -u -p -r1.53 install.texinfo
--- install.texinfo 18 May 2005 11:56:27 -0000 1.53
+++ install.texinfo 12 Jan 2006 02:33:20 -0000
@@ -13,7 +13,7 @@ that the GUI installer is a "work in pro
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 in the latest development snapshot at
-@file{http://cygwin.com/setup/}, then by all means report it to the
+@file{http://cygwin.com/snapshots/}, then by all means report it to the
mailing list.
For a searchable list of packages that can be installed with Cygwin,
@@ -311,36 +311,54 @@ thing stored in the registry.
First, are you sure you want to do this? Snapshots are risky. They
have not been tested. Use them @strong{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 @strong{all} Cygwin
-applications, including shells and services (e.g. inetd, sshd), before
-updating @code{cygwin1.dll}. You may have to restart Windows to clear
-the DLL from memory.
-
-You cannot use Setup to install a snapshot.
+problems, or at the request of a Cygwin developer.
You should generally install the full
@code{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 @code{/usr/bin/cygwin1.dll}, but it should succeed with
-everything else.
+otherwise some components may be out of sync.
-@enumerate
+You cannot use Cygwin Setup to install a snapshot.
+
+First, you will need to download the snapshot from the snapshots
+page at @file{http://cygwin.com/snapshots/}. Note the directory where
+you saved the snapshot tarball.
+
+Before installing a snapshot, you must first Close @strong{all} Cygwin
+applications, including shells and services (e.g., @code{inetd}, @code{sshd}).
+You will not be able to replace @code{cygwin1.dll} if any Cygwin process is
+running. You may have to restart Windows to clear the DLL from memory
+(beware of automatic service startup).
+
+Most of the downloaded snapshot can be installed using @code{tar}. Cygwin
+@code{tar} won't be able to update @code{/usr/bin/cygwin1.dll} (because it's
+used by @code{tar} itself), but it should succeed with everything else. If
+you are only installing the DLL snapshot, skip the first tar command. Open
+a @code{bash} shell (it should be the only running Cygwin process) and issue
+the following commands:
-@item Download the snapshot, and run:
@example
- 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
+ /bin/tar -C/ -jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 --exclude=usr/bin/cygwin1.dll
+ /bin/tar -C/tmp -jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 usr/bin/cygwin1.dll
+ /bin/mv /bin/cygwin1.dll /bin/cygwin1-prev.dll
@end example
-@item After closing all Cygwin apps (see above), use Explorer or the
+Note that after the "@code{mv}" command you will not be able to run any
+Cygwin programs. Exit the bash shell, and use Explorer or the
Windows command shell to move @code{C:\cygwin\tmp\usr\bin\cygwin1.dll}
-to @code{C:\cygwin\bin\cygwin1.dll}.
+to @code{C:\cygwin\bin\cygwin1.dll} (assuming you installed Cygwin in
+@code{C:\cygwin}).
-@end enumerate
+The operative word in trying the snapshots is "@emph{trying}". If you
+notice a problem with the snapshot that was not present in the release
+DLL (what we call a "regression"), please report it to the Cygwin
+mailing list (see @file{http://cygwin.com/problems.html} for problem
+reporting guidelines). If you wish to go back to the older version of the
+DLL, again, close all Cygwin processes, delete
+@code{C:\cygwin\bin\cygwin1.dll}, and
+rename @code{C:\cygwin\bin\cygwin1-prev.dll} back to
+@code{C:\cygwin\bin\cygwin1.dll} (again assuming that your "@code{/}" is
+@code{C:\cygwin}). To restore the rest of the snapshot
+files, reinstall the "@code{cygwin}" package using Setup.
@subsection Can Cygwin Setup maintain a ``mirror''?
More information about the Cygwin-patches
mailing list