Difference between revisions of "Wine-Staging"

From WineHQ Wiki
Jump to: navigation, search
(change the bug links to just show the Wine Staging bug list.)
(how to report bugs against staging)
 
(8 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
Wine Staging is the testing area of winehq.org. It contains bug fixes and features, which have not been integrated into the development branch yet. The idea of Wine Staging is to provide experimental features faster to end users and to give developers the possibility to discuss and improve their patches before they are integrated into the main branch.
 
Wine Staging is the testing area of winehq.org. It contains bug fixes and features, which have not been integrated into the development branch yet. The idea of Wine Staging is to provide experimental features faster to end users and to give developers the possibility to discuss and improve their patches before they are integrated into the main branch.
  
Wine Staging is maintained as a set of patches which has to be applied on top of the corresponding Wine development version. Package maintainers can decide if they want to include our full patchset, or only want to cherry-pick patches for specific bugs. Our current version includes fixes for about 450 bugs and over 900 patches total, and new patches are added frequently. Features and bugfixes available in Wine-Staging 3.8 are for example:
+
Wine Staging is maintained as [https://github.com/wine-staging/wine-staging a set of patches] which has to be applied on top of the corresponding Wine development version. Package maintainers can decide if they want to include our full patchset, or only want to cherry-pick patches for specific bugs.
  
    CSMT (Commandstream multithreading) for better graphic performance
+
== Installation ==
    CUDA / PhysX / NVENC Support for NVIDIA graphic cards
+
    DXVA2 GPU video decoding (experimental)
+
    Direct3D 10/11 enhancements
+
    EAX 1 support
+
    Fixes for various upstream regressions
+
    GTK 3 theming support
+
    macOS preloader
+
    Performance improvements for IO-heavy programs and memory allocation functions
+
    S3 texture compression (DXTn) support
+
    Support for allocating more than 32 GB of memory
+
    Support for installing MSU files
+
    Various improvements to d3dx9
+
    Various speed improvements (shared memory, RT priority)
+
    Windows ACL support
+
  
 +
Pre-compiled Staging packages for most major distributions are available on the [https://wiki.winehq.org/Download Download] page. Instructions for installing Staging are given under each distribution that provides it.
 +
 +
== Building from source==
 +
 +
Since Wine-Staging is maintained as a set of patches rather than a forked repository, the process of building is slightly different. You will first need a vanilla Wine source tree and the required dependencies; for instructions see [[Building Wine]]. Note that Staging adds some optional dependencies which are necessary for certain additional features. You will also need the Staging "source"; this can be cloned or downloaded from [https://github.com/wine-staging/wine-staging the GitHub page].
 +
 +
Once you have obtained the sources, you will need to apply the Staging patches of your choice (or all of them) on top of the Wine source tree. You can do this using the provided <tt>patches/patchinstall.sh</tt> script; see its options with <tt>--help</tt> for detailed instructions. If you apply patches manually, take note that you will also need to run <tt>autoreconf -f</tt> and <tt>tools/make_requests</tt>, as such generated changes are not included in Staging patches. Be warned that an individual version of the Staging repository will ''only'' successfully apply against the upstream Wine commit it was last rebased against.
 +
 +
After you have applied patches, compilation proceeds as usual for upstream Wine; refer to [[Building Wine]] for detailed instructions.
 +
 +
== Reporting and debugging bugs against Staging ==
 +
 +
We, the Staging maintainers, really need to know whether a bug is introduced by a Staging patch, or has nothing to do with any Staging patches. If a bug is introduced by a Staging patch, it suggests that something is wrong with the patch in question, and that patch needs to be fixed before it can be sent upstream.
 +
 +
Therefore, when reporting a bug against Staging, '''always''' test '''both''' the '''latest''' Staging and upstream releases. If the bug is also present in the same form with upstream Wine, the bug should be reported against the Wine product, not the Wine-Staging product. Doing this saves ''everyone'' a lot of time and effort.
 +
 +
If the bug is present in Wine-Staging but not in upstream Wine, then the next most helpful thing to do is to bisect between Staging and Wine. In order to do this, you'll first want to acquire a clean Wine tree as well as the latest set of Staging patches. Next, apply each patch as a separate commit, using the command
 +
<pre>path/to/staging-tree/patches/patchinstall.sh --all --backend=git-am --force-autoconf</pre>
 +
either in your Wine source tree, or using the <tt>DESTDIR</tt> argument. You'll need to use the <tt>--force-autoconf</tt> argument to ensure that patches affecting configure.ac or protocol.def are properly applied; alternatively, you can omit this argument, so long as you remember to run it before compiling each step of the bisect. From here the bisect should proceed as normal; you can find some (admittedly rather outdated) instructions [[Regression Testing|here]].
 +
 +
=== Regressions between Staging versions ===
 +
 +
Suppose a failure is introduced in a later Staging version, that does not occur in an earlier one. This, again, could mean one of several things, each of which have a vastly different significance. There could be a bug introduced by a new Staging patch, or (re)introduced by losing one; there could be an error during rebasing, or an obscure way in which a change upstream breaks a Staging patch. Alternatively, there could be a problem introduced or exposed by a patch committed upstream, that is, a regression strictly in upstream Wine. Again, we really need to know which one of these things has happened. Therefore, we will again ask you, before you do anything else, to test the corresponding upstream Wine releases of both the "good" version and the "bad" version.
 +
 +
If both the "old" and "new" upstream Wine releases are not affected by the bug, it's a bug in Staging, and should be reported against the Wine-Staging product. In this case, it's again most helpful to then perform a regression test between Staging and Wine, as detailed above.
 +
 +
If the "old" upstream Wine release is not affected by the bug, but the "new" one is, we can pretty safely assume it's a bug in upstream Wine. In that case, the bug should be reported against the Wine product. From here the most helpful thing to do is perform a regression test between upstream Wine releases.
 +
 +
If the application does not work using upstream Wine to the point of triggering the bug in question—that is, it fails too early, but that failure is fixed by a Staging patch—the same principle applies, but is muddied by the additional presence of Staging patches. We first need to know exactly ''which'' Staging patches fix the earlier bug. This might be documented on bugs attached the application in our AppDB, or it may only be mentioned on the bugs themselves (in the latter case, please do submit bug links to the AppDB). It also may not be known at all, in which case you'll need to perform a ''reverse'' bisect between Wine-Staging and upstream Wine, of the last known working version—that is, a bisect where the meanings of "bad" and "good" are reversed. You may have to perform multiple such bisects, if the application depends on multiple Staging patches.
 +
 +
Once you've identified exactly which patches are necessary before the failure can be reproduced, the next step is to try applying only those patches against a clean upstream Wine of the earliest broken version. If the failure is not present, this implies something was broken in Staging. Figuring out what can be difficult, and is probably very dependent on circumstances, so this guide won't prescribe any further course of action at the present moment. If the failure is present, this implies something was broken in upstream Wine. In that case the next step is to perform a bisect between upstream Wine versions, as normal—except at every step you'll also need to apply the Staging patches that are necessary for the application to run.
 +
 +
This may seem like a lot of bisects and testing to perform—and it is, but it really is the easiest way for a problem to be fixed. It may be easiest for the user to simply pull a debug log with given flags, but in the vast majority of cases, it's orders of magnitude easier to fix a bug if it's known exactly what patch introduces that bug. Making things easier for developers is by far the best route to getting a bug fixed quickly. At the same time, we recognize that bisects are time-consuming for anyone to perform, and we will understand if you can't spare the time to perform them—as long as you understand in turn that your bug is not by any means guaranteed to be fixed quickly. However, we will always expect you to have tried upstream Wine first.
  
 
== Quick Links ==
 
== Quick Links ==
Line 27: Line 46:
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
|-
 
|-
| [[File:icon-usage.png]]
+
| [[File:icon-usage.png]]https://github.com/wine-staging/wine-staging
 
| [[Wine-Staging_Usage|Usage]]
 
| [[Wine-Staging_Usage|Usage]]
 
|-
 
|-
Line 39: Line 58:
 
| [https://bugs.winehq.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=STAGED&bug_status=REOPENED&bug_status=NEEDINFO&bug_status=RESOLVED&list_id=610554&product=Wine-staging&query_format=advanced Bugs]
 
| [https://bugs.winehq.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=STAGED&bug_status=REOPENED&bug_status=NEEDINFO&bug_status=RESOLVED&list_id=610554&product=Wine-staging&query_format=advanced Bugs]
 
|}
 
|}
 +
 +
== See Also ==
 +
[https://github.com/wine-staging/wine-staging Wine-staging GitHub repository]

Latest revision as of 21:17, 20 September 2019

What is Wine Staging?

Wine Staging is the testing area of winehq.org. It contains bug fixes and features, which have not been integrated into the development branch yet. The idea of Wine Staging is to provide experimental features faster to end users and to give developers the possibility to discuss and improve their patches before they are integrated into the main branch.

Wine Staging is maintained as a set of patches which has to be applied on top of the corresponding Wine development version. Package maintainers can decide if they want to include our full patchset, or only want to cherry-pick patches for specific bugs.

Installation

Pre-compiled Staging packages for most major distributions are available on the Download page. Instructions for installing Staging are given under each distribution that provides it.

Building from source

Since Wine-Staging is maintained as a set of patches rather than a forked repository, the process of building is slightly different. You will first need a vanilla Wine source tree and the required dependencies; for instructions see Building Wine. Note that Staging adds some optional dependencies which are necessary for certain additional features. You will also need the Staging "source"; this can be cloned or downloaded from the GitHub page.

Once you have obtained the sources, you will need to apply the Staging patches of your choice (or all of them) on top of the Wine source tree. You can do this using the provided patches/patchinstall.sh script; see its options with --help for detailed instructions. If you apply patches manually, take note that you will also need to run autoreconf -f and tools/make_requests, as such generated changes are not included in Staging patches. Be warned that an individual version of the Staging repository will only successfully apply against the upstream Wine commit it was last rebased against.

After you have applied patches, compilation proceeds as usual for upstream Wine; refer to Building Wine for detailed instructions.

Reporting and debugging bugs against Staging

We, the Staging maintainers, really need to know whether a bug is introduced by a Staging patch, or has nothing to do with any Staging patches. If a bug is introduced by a Staging patch, it suggests that something is wrong with the patch in question, and that patch needs to be fixed before it can be sent upstream.

Therefore, when reporting a bug against Staging, always test both the latest Staging and upstream releases. If the bug is also present in the same form with upstream Wine, the bug should be reported against the Wine product, not the Wine-Staging product. Doing this saves everyone a lot of time and effort.

If the bug is present in Wine-Staging but not in upstream Wine, then the next most helpful thing to do is to bisect between Staging and Wine. In order to do this, you'll first want to acquire a clean Wine tree as well as the latest set of Staging patches. Next, apply each patch as a separate commit, using the command

path/to/staging-tree/patches/patchinstall.sh --all --backend=git-am --force-autoconf

either in your Wine source tree, or using the DESTDIR argument. You'll need to use the --force-autoconf argument to ensure that patches affecting configure.ac or protocol.def are properly applied; alternatively, you can omit this argument, so long as you remember to run it before compiling each step of the bisect. From here the bisect should proceed as normal; you can find some (admittedly rather outdated) instructions here.

Regressions between Staging versions

Suppose a failure is introduced in a later Staging version, that does not occur in an earlier one. This, again, could mean one of several things, each of which have a vastly different significance. There could be a bug introduced by a new Staging patch, or (re)introduced by losing one; there could be an error during rebasing, or an obscure way in which a change upstream breaks a Staging patch. Alternatively, there could be a problem introduced or exposed by a patch committed upstream, that is, a regression strictly in upstream Wine. Again, we really need to know which one of these things has happened. Therefore, we will again ask you, before you do anything else, to test the corresponding upstream Wine releases of both the "good" version and the "bad" version.

If both the "old" and "new" upstream Wine releases are not affected by the bug, it's a bug in Staging, and should be reported against the Wine-Staging product. In this case, it's again most helpful to then perform a regression test between Staging and Wine, as detailed above.

If the "old" upstream Wine release is not affected by the bug, but the "new" one is, we can pretty safely assume it's a bug in upstream Wine. In that case, the bug should be reported against the Wine product. From here the most helpful thing to do is perform a regression test between upstream Wine releases.

If the application does not work using upstream Wine to the point of triggering the bug in question—that is, it fails too early, but that failure is fixed by a Staging patch—the same principle applies, but is muddied by the additional presence of Staging patches. We first need to know exactly which Staging patches fix the earlier bug. This might be documented on bugs attached the application in our AppDB, or it may only be mentioned on the bugs themselves (in the latter case, please do submit bug links to the AppDB). It also may not be known at all, in which case you'll need to perform a reverse bisect between Wine-Staging and upstream Wine, of the last known working version—that is, a bisect where the meanings of "bad" and "good" are reversed. You may have to perform multiple such bisects, if the application depends on multiple Staging patches.

Once you've identified exactly which patches are necessary before the failure can be reproduced, the next step is to try applying only those patches against a clean upstream Wine of the earliest broken version. If the failure is not present, this implies something was broken in Staging. Figuring out what can be difficult, and is probably very dependent on circumstances, so this guide won't prescribe any further course of action at the present moment. If the failure is present, this implies something was broken in upstream Wine. In that case the next step is to perform a bisect between upstream Wine versions, as normal—except at every step you'll also need to apply the Staging patches that are necessary for the application to run.

This may seem like a lot of bisects and testing to perform—and it is, but it really is the easiest way for a problem to be fixed. It may be easiest for the user to simply pull a debug log with given flags, but in the vast majority of cases, it's orders of magnitude easier to fix a bug if it's known exactly what patch introduces that bug. Making things easier for developers is by far the best route to getting a bug fixed quickly. At the same time, we recognize that bisects are time-consuming for anyone to perform, and we will understand if you can't spare the time to perform them—as long as you understand in turn that your bug is not by any means guaranteed to be fixed quickly. However, we will always expect you to have tried upstream Wine first.

Quick Links

Here are some links to the most important topics.

Icon-usage.pnghttps://github.com/wine-staging/wine-staging Usage
Icon-config.png Configuration
Icon-contribute.png Contributing
Icon-bug.png Bugs

See Also

Wine-staging GitHub repository