libs/newlib-cygwin
libs
/
newlib-cygwin
mirror of git://sourceware.org/git/newlib-cygwin.git
4
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cygwin: FAQ: describe test releases, deprecate developer snapshots 

Signed-off-by: Corinna Vinschen <corinna@vinschen.de>
This commit is contained in:
Corinna Vinschen 2022-12-02 21:54:19 +01:00
parent a5bcfe616c
commit 08f33e5b6a
3 changed files with 51 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
winsup/doc/faq-api.xml
View File

@ -30,13 +30,24 @@ User's Guide.
<question><para>Are development snapshots for the Cygwin library available?</para></question>
<answer>
<para>Yes. They're made whenever anything interesting happens inside the
Cygwin library (usually roughly on a nightly basis, depending on how much
is going on). They are only intended for those people who wish to
contribute code to the project. If you aren't going to be happy
debugging problems in a buggy snapshot, avoid these and wait for a real
release. The snapshots are available from
<ulink url="https://cygwin.com/snapshots/"/>.
<para>Starting December 2022, the old developer snapshots have been
deprecated by regular, automated test releases. See the next FAQ entry
<ulink url="https://cygwin.com/faq/faq-api.html#faq.api.testrels"/>)
</para>
</answer></qandaentry>
<qandaentry id="faq.api.testrels">
<question><para>Are test releases for the Cygwin library available?</para></question>
<answer>
<para>Yes. Starting December 2022, regular, automated test releases
are created whenever a considerable patch is pushed to the Cygwin git
repo at
<ulink url="https://cygwin.com/git/newlib-cygwin.git"/>.
You can download the cygwin package test releases just like any other
test release for any Cgywin package using the Cygwin Setup program.
For more info, see
<ulink url="https://cygwin.com/faq/faq-setup.html#faq.setup.testrels"/>
</para>
</answer></qandaentry>

8
winsup/doc/faq-programming.xml
View File

@ -764,10 +764,10 @@ operation e.g. when checking a pointer is valid)
</para>
<para>
It is also a good
idea to use the latest code in case the bug has been fixed, so we
recommend trying the latest snapshot from
<ulink url="https://cygwin.com/snapshots/"/> or building the DLL from git.
It is also a good idea to use the latest code in case the bug has been fixed,
so we recommend trying the latest cygwin test release (see
<ulink url="https://cygwin.com/faq/faq-setup.html#faq.setup.testrels"/>)
or building the DLL from git.
</para>
<para>To build a debugging version of the Cygwin DLL, you will need to follow

79
winsup/doc/faq-setup.xml
View File

@ -21,10 +21,10 @@ tools.
is available on using the Cygwin Setup program.
</para>
<para>If you do it any other way, you're on your own!
If something doesn't work right for you, and
it's not covered here or in the latest development snapshot at
<ulink url="https://cygwin.com/snapshots/"/>, then by all means report it to the
mailing list.
If something doesn't work right for you, and it's not covered here or in
the latest Cygwin test package (see
<ulink url="https://cygwin.com/faq/faq-api.html#faq.api.testrels"/>),
then by all means report it to the mailing list.
</para>
<para>For a searchable list of packages that can be installed with Cygwin,
see <ulink url="https://cygwin.com/packages/"/>.
@ -627,56 +627,35 @@ directory has been stored in the registry at all.
</answer></qandaentry>
<qandaentry id="faq.setup.snapshots">
<question><para>How do I install snapshots?</para></question>
<qandaentry id="faq.setup.testrels">
<question><para>How do I install Cygwin test releases?</para></question>
<answer>
<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, or at the request of a Cygwin developer.
<para>You can install Cygwin test releases just like test releases of
any other package using the Cygwin Setup program. Ideally, you install
not only the <emphasis role='bold'>cygwin</emphasis> test package, but
also the <emphasis role='bold'>cygwin-debuginfo</emphasis> test package
with the same version number. The cygwin-debuginfo package allows source
code debugging using gdb. Install the
<emphasis role='bold'>cygwin-devel</emphasis> test package, if you also
want to test building against a new API.
</para>
<para>You cannot use the Cygwin Setup program to install a snapshot.
<para>However, are you sure you want to do this? Test releases are risky.
They have only been marginally tested most of the time. 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, or at the
request of a Cygwin developer.
</para>
<para>First, you will need to download the snapshot from the snapshots
page at <ulink url="https://cygwin.com/snapshots/"/>. 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>
/bin/tar -C / -xvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.* --exclude=usr/bin/cygwin1.dll
/bin/tar -C /tmp -xvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.* usr/bin/cygwin1.dll
</screen>
</para>
<para>Exit the bash shell, and use Explorer or the Windows command shell to
first rename <literal>C:\cygwin\bin\cygwin1.dll</literal> to
<literal>C:\cygwin\bin\cygwin1-prev.dll</literal> and then move
<literal>C:\cygwin\tmp\usr\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="https://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
<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 the Cygwin Setup program.
<para>The operative word in trying the test releases 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="https://cygwin.com/problems.html"/> for problem
reporting guidelines). If you wish to go back to the most recent non-test
release of the Cygwin DLL, close all Cygwin processes, as usual, start the
Cygwin Setup program and choose the most recent non-test release of the
cygwin package, as well as the cygwin-debuginfo and cygwin-devel packages.
That's all there is to it.
</para>
</answer></qandaentry>