wine/wine-staging
0
0
Fork 0
mirror of https://gitlab.winehq.org/wine/wine-staging.git synced 2024-11-21 16:46:54 -08:00
Code Issues Packages Projects Releases Wiki Activity

Import pages from MediaWiki.

Alexandre Julliard 2024-09-04 11:16:44 +02:00
commit 42508fd386
11 changed files with 912 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
Configuration.md Normal file

@ -0,0 +1,12 @@
## Available topics
- [CUDA Configuration](Configuration/CUDA)
- [Dll Redirects Configuration](Configuration/Dll-Redirects)
- [Environment Variables
Configuration](Configuration/Environment-Variables)
- [Miscellaneous Configuration](Configuration/Miscellaneous)
- [PhysX Configuration](Configuration/PhysX)

43
Configuration/CUDA.md Normal file

@ -0,0 +1,43 @@
Starting with version 1.7.34 Wine Staging provides support for CUDA, a
GPU computation platform by NVIDIA. CUDA is often used by games to run
physic calculations on the GPU or in scientific environments to speed up
simulations. For games there is also a separate NVIDIA library called
[PhysX](Configuration/PhysX) which makes use of CUDA and
provides some predefined physic simulations.
In order to use CUDA based applications you need to have a NVIDIA
graphic card (\>= Geforce 8xxx) and you need to use the proprietary
NVIDIA driver. Make sure that you also have the 32 bit driver files
installed on 64 bit systems. Please note that there is a
[bug](https://bugs.launchpad.net/ubuntu/+source/nvidia-graphics-drivers-331/+bug/1361207)
affecting some Ubuntu distributions, that the necessary kernel modules
for CUDA (`nvivida_uvm`) are not loaded automatically. As a workaround
you can manually install the package `nvidia-modprobe` package (for
example with `sudo apt-get install nvidia-modprobe`) if you encounter
this problem.
The easiest way to verify that everything is set up correctly is to use
the linux version of [CUDA-Z](https://cuda-z.sourceforge.net/). If the
application starts and shows information about your GPU everything is
working fine. If you only get an error message it is possible that you
are either missing some files or not all required kernel modules are
loaded.
There is no additional configuration required for Wine Staging and
applications can directly start using CUDA. Nevertheless, the
implementation is not yet complete and some functions (like directly
accessing DirectX objects from CUDA) are unimplemented. In case an
application will try to use one of this functions it is going to
abort/crash. If CUDA is only an optional dependency of the program you
want to use, and it doesn't work with our incomplete implementation, it
might be useful to disable CUDA support again until the support is good
enough. Feel free to report a bug in this case, and we will try to fix
it till the next release.
## Disable CUDA
Hiding CUDA support from applications can be done by deactivating the
nvcuda.dll through winecfg. Open `winecfg`, go to the Libraries tab, add
an override for `nvcuda` and change it to disable by pressing the edit
button. If you would like to re-enable the support, you just need to
remove this line again.

56
Configuration/Dll-Redirects.md Normal file

@ -0,0 +1,56 @@
Wine Staging 1.7.33 introduced a feature called DLL Redirects which make
it possible to dynamically exchange the DLLs a program tries to load.
This feature is currently used by our CSMT implementation to replace
`wined3d.dll` with `wined3d-csmt.dll` to allow switching it on and off
at runtime. These redirects are controlled through registry keys and
work with builtin/wine dlls and native/win32 dlls.
## Adding redirects
In order to add a redirection, you need to create a registry key using
regedit. You can either create a global dll redirection under
HKEY_CURRENT_USER\Software\Wine\DllRedirects
or an application specific one under
HKEY_CURRENT_USER\Software\Wine\AppDefaults\[app.exe]\DllRedirects
(replace \[app.exe\] with the actual filename of the executable).
If you want to add a redirect from broken.dll to working.dll, you need
to create a string value (REG_SZ) with broken as name (you need to strip
off the .dll extension) and working.dll as value. Alternatively you can
also specify a full win32 path to the dll.
Here you can see what it looks like for the CSMT redirect:<br>
![](/Configuration/Registry-redirects.png "registry-redirects.png")
## How does it work?
We added some logic to Wine's dll loader to replace the filename of the
loaded dll. Wine itself thinks that the original dll is loaded and
therefore all API functions like `GetModuleFileName` or
`GetModuleHandle` will still work as if the original was loaded. This
makes it almost impossible for an application to find out that the wrong
library is loaded. There are some ways like checking the actual file
content of the library against the loaded memory chunks but it is
unlikely that an application implements something like this. However,
this approach also has some drawbacks which may be fixed in future
versions.
## Drawbacks
You can only redirect existing dlls because an application can query the
full path of a loaded library and it is not clear which path we should
return for non existing dlls. A library may be anywhere in the programs
search path (C:\windows\system32, current working directory, ...) and we
therefore require the file to exist.
The current implementation of DLL redirects does not store any
information about loaded dlls which were redirected. This causes trouble
if an application tries to manually load the target of a redirection
while the same library is already loaded under a different name. Wine
does not notice that the library was already loaded and tries to load it
a second time. The behaviour of builtin/native DLLs is slightly
different, but in both cases an application might be confused.

106
Configuration/Environment-Variables.md Normal file

@ -0,0 +1,106 @@
Some features of Wine Staging are experimental and affect so many parts
of Wine that they cannot be configured through winecfg or a registry
key. In these cases we decided to add an environment variable that
allows you to enable/disable the feature. The following list contains a
description of the supported environment variables and what they are
supposed to do.
## Write Copy
The `STAGING_WRITECOPY` environment variable can be used to simulate
the memory management system of Windows more precisely. Windows loads
dlls only a single time into the memory when multiple applications
want to use the same dll. This should lower the memory usage and
Windows will only create a copy of them if an application tries to
modify them (Copy-on-Write). On Wine it will have no effect on the
memory usage, but an application can check if a dll was already
modified in the current process and some programs (for example,
[Voobly](#29384)) fail if this information is incorrect.
You can enable the feature simply by starting a program using
STAGING_WRITECOPY=1 /opt/wine-staging/bin/wine game.exe
The feature is currently not enabled by default since it revealed
further bugs in Wine. Please help us by testing programs with this
feature enabled and report bugs in our [bug
tracker](https://bugs.winehq.org) so that we can enable this feature by
default in future versions.
## Shared Memory
Wine Staging can optimize some wineserver calls by using shared memory.
While this only brings a small performance improvement for most
programs, it can result in a big improvement for applications which use
specific API functions in an excessive way. This feature can be enabled
through `STAGING_SHARED_MEMORY` and is only available for Linux with
kernel \>= 3.17 at the moment. We are going to enable it for more
platforms in future versions.
In order to use this feature make sure that the wineserver was started
using this environment variable (i.e. no other programs are currently
running in the WINEPREFIX)
STAGING_SHARED_MEMORY=1 /opt/wine-staging/bin/wine game.exe
## Realtime Priorities
The Realtime Priority patchset allows applications running in Wine to
use higher priority levels on Linux than they are usually allowed to
use.
You can change the priority level on the wineserver by setting the
`STAGING_RT_PRIORITY_SERVER` environment variable, which has a similar
effect like using shared memory. The wineserver is usually idling and
waiting for new requests, so setting a higher priority causes the system
to schedule the wineserver faster and double the throughput in
wineserver benchmarks.
It is also possible to change the priority of all programs running in
Wine by setting `STAGING_RT_PRIORITY_BASE` though this will usually not
result in big performance improvements. The linux kernel will reduce the
priority again if an application does not idle often enough and most
games therefore may even run slower this way. We recommend changing the
priority only for the wineserver since this gives you a small
performance improvement without the risk of slowing down your
application, but feel free to try it yourself.
Before you can make use of the realtime priority levels, you need to
give the wineserver the permission to use them.
### setcap
The easiest and simplest way is to set file capabilities on the
wineserver:
sudo setcap cap_sys_nice+ep /opt/wine-staging/bin/wineserver
This should be enough on most systems, but will be reset on a wine
staging update.
### limits.conf
Alternatively, you can give your user the permission to use the realtime
priorities in all programs. Some distributions already provide an audio
group that grants you these permissions. If this is not the case, you
can add the following entry to /etc/security/lmits.conf:
@userOrGroup - rtprio 90
@userOrGroup - nice -10
Now logout and back in.
### Use RT priorities
In case you want to change the priority of the wineserver, make sure
that the server was not started yet. Now start your application using:
STAGING_RT_PRIORITY_SERVER=90 STAGING_RT_PRIORITY_BASE=90 /opt/wine-staging/bin/wine test.exe
The priority must be between 1 (lowest) and 99 (highest). You do not
need to use both of them, simply skip one if you don't want to enable it
or set it to 0. Note that you probably should not use 99, as the kernel
has some housekeeping threads running at this priority. More information
can also be found in the [patch submission
request](https://bugs.wine-staging.com/show_bug.cgi?id=183#c0) where
this feature was added.

38
Configuration/Miscellaneous.md Normal file

@ -0,0 +1,38 @@
All Wine Staging specific registry settings which do not have a
dedicated wiki entry are mentioned on this page. You can change the
settings using `regedit`.
## Tablet / Media Center
On Windows application can check through the `GetSystemMetrics` API
function whether the system is a tablet and/or Media Center. Wine
Staging contains a patch to configure the return value through the
registry.
| Registry Key (HKCU\Software\Wine\\) | Type | Values | Description |
|-------------------------------------|-------|--------|------------------------------------------------|
| ...\System\TabletPC | DWORD | 0 / 1 | 1 if the system is a tablet pc, otherwise 0 |
| ...\System\MediaCenter | DWORD | 0 / 1 | 1 if the system is a media center, otherwise 0 |
The same values can also be configured using the application specific
registry keys.
## DirectSound Mixing buffers
Wine does not support hardware mixing of sound buffers (and most linux
sound drivers don't support it either) and therefore the whole sound
mixing is done on the CPU. This can cause trouble for games that use
DirectSound with many different sound buffers, especially if they have
different sampling rates. Some games even use one sound buffer per sound
causing Wines complicated sound mixing algorithm to slow down the whole
game. We added a patch to Wine Staging which uses a faster but slightly
more incorrect algorithm if a specific number of sound buffers is
exceeded. The default limit is 4 but it can be changed through the
following registry key.
| Registry Key (HKCU\Software\Wine\\) | Type | Values | Description |
|-------------------------------------|-------|--------|--------------|
| ...\DirectSound\HQBuffersMax | DWORD | \>= 0 | buffer limit |
The same values can also be configured using the application specific
registry keys.

22
Configuration/PhysX.md Normal file

@ -0,0 +1,22 @@
PhysX is a physics simulation library provided by NVIDIA which is
commonly used in games. Wine supports this library since quite some
time in the CPU fallback mode which means that all physics
calculations are done on your CPU. On Windows PhysX also supports
offloading of calculations to NVIDIA based graphic cards through
[CUDA](Configuration/CUDA). Starting with Wine Staging 1.7.34 the
necessary features were added to provide the same possibility in Wine.
If you want to use GPU accelerated PhsyX you should first make sure that
[CUDA](Configuration/CUDA) is set up correctly as described in
the according Wiki page. The next step is to install the PhysX software
into the wineprefix containing the program requiring PhysX support. Many
applications will directly install the necessary dlls during the
installation, but you can also download them from the [NVIDIA
website](https://www.nvidia.com/object/physx-9.14.0702-driver.html).
PhysX should now be able to offload calculations to a NVIDIA GPU.
You can verify that PhsysX is working properly using the [PhysX
FluidMark](https://www.ozone3d.net/benchmarks/physx-fluidmark/)
Benchmark. The software displays in the start dialog whether GPU
acceleration is available. You can also compare the FPS between GPU and
CPU based simulations by changing the GPU checkbox in the start dialog.

BIN
Configuration/Registry-redirects.png Normal file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

112
Contributing.md Normal file

@ -0,0 +1,112 @@
## Contributing to Wine
The best way to make Staging better is to make upstream Wine better.
This helps both projects, as Staging draws directly and regularly from
upstream Wine. Many patches in the past which have been written for
Staging have been perfectly acceptable for upstream Wine, so for any
simple patch, going straight upstream is almost always better.
## For new developers
We try to make the process of contributing to Wine as friendly and
helpful as possible, but nevertheless it can be difficult to get patches
in, especially for new developers who don't have a familiarity with the
code base. One of the purposes of Staging is to provide a less demanding
environment for new developers, so that patches which aren't quite up to
upstream's high quality standards at first can be accepted into Staging,
improved by the author with the help of the Staging maintainers, and
then submitted upstream. On the other hand, some simple patches may
already be quite acceptable for upstream, so don't be surprised if a
patch is suggested for upstreaming right away by a Staging maintainer or
someone else.
## For experienced developers
Another purpose of Staging, as is suggested by its name, is to provide a
temporary place for large or risky patchsets to gain some testing, so as
to more completely test them for bugs and account for regressions that
the changes might expose. We encourage all developers to take advantage
of this facility, both to improve their code and to avoid the situation
where helpful patches are long to see the light of day.
## Requirements
Our standards are less strict than upstream Wine, but we do still have
some requirements:
- The patch must be a step in the right direction; that is, we don't
allow patches that are gross hacks, or take an obviously wrong
approach to solving a problem. The end goal is always to submit the
patch upstream eventually, so work should progress in that direction.
- The patch must have a bug attached. We place great value on
traceability, so we require all patches to have an associated WineHQ
bug (exceptions may be granted under special circumstances). We also
strongly encourage all discussion to take place on the relevant bug.
- Like upstream Wine, a patch must have correct attribution. If you did
not write a patch, you must make this clear (ideally using the From:
line in the patch itself).
- Unlike upstream Wine, we do not require sign-offs. We take sign-offs
to mean the same thing as they do for upstream Wine: that you consider
your code to be good enough to go into upstream Wine and to meet all
of the legal and technical requirements thereof; accordingly a
sign-off is not necessary for Staging patches, which do not need to
meet these requirements. However, if you do provide a sign-off, be
aware that your sign-off may be preserved by someone else who submits
the patch upstream.
- Like upstream Wine, we do not take contributions from anyone who has
disassembled or reverse-engineered Microsoft code, or seen sources
(whether leaked or publicly available).
## How to submit patches
As of 2018, Staging has a strict policy that all new patches submitted
for Staging *must* have an associated bug report. This is to combat the
problem where patches written cannot be verified, justified, or tested
for regressions. To facilitate this, Staging uses the Wine bug tracker
as, in some sense, a patch tracker. If you want a patch to be included
in Staging, attach it to the bug, and then add one of the Staging
maintainers (Alistair Leslie-Hughes, Zebediah Figura, or Paul Gofman) as
CC, *with the explicit request* that the patch be considered for
Staging. Please be explicit and provide details about the patch if you
can, and tell us why you are submitting the patch into Staging rather
than upstream Wine. Don't just CC one of us and expect us to know what
you want; make sure you state clearly that the patch is meant for
Staging. If you are writing a patch for a bug that has not yet been
filed, it's perfectly fine to file a new bug.
We prefer patches to be formatted for submission using
`git format-patch`, as this is how all patches are stored in the Staging
repository itself. If you have several patches, please compress them
into a single tarball or zip instead of attaching each one individually.
However, if you have several patches which fix individual bugs (e.g. a
series of patches in different areas that are needed to allow a certain
application to work), these should ideally target separate bugs in
Bugzilla, which can be created if necessary.
After a Staging maintainer has considered the patch, if it is deemed
acceptable for Staging, we will add the patch to the Staging repository
and mark the bug as STAGED. We may additionally scout existing bugs or
the wine-devel mailing list for patches, but if you want to make sure we
see a patch to be added into Staging, make sure you CC us and request so
on the relevant bug. Since we use Bugzilla as a patch tracker, further
discussion on a patch will take place on the bug report, so make sure
you are subscribed to it.
## Packaging
We already support a large number of distributions and provide new
builds every two weeks, but we can not support every single
distribution. If you are using an unsupported one and you know how to
create packages, feel free to do so by following the instructions in
our [Packaging](Packaging) guidelines. We may also add a description
on how to use your packages in our Installation instructions, if you
tell us about them. Just open a bug report or contact us on IRC.
## Testing
The idea behind Wine Staging is to add experimental functions and bug
fixes. In order to make sure that we do not introduce any new bugs or
failed to fix existing ones, we need people to test Wine Staging. We try
to test as much stuff as possible on our own, but some bugs occur in
proprietary software which we do not own. You should therefore try as
much software as possible with Wine Staging.

156
Packaging.md Normal file

@ -0,0 +1,156 @@
In case you want to compile Wine Staging or create a package for it, you
should follow these instructions. Please note that simply applying all
patches inside the `patches` folder won't work. Even when using the
script it is still possible to exclude patches if desired, take a look
at the end of this document for more details.
## Compiling Wine Staging
Before you can start compiling Wine Staging, you need to make sure that
you have all necessary dependencies installed. The easiest way to find
the appropriate packages for your distribution (especially if you want
to create a package) is to take a look at an existing Wine source
packages. In case you are using a 64 bit system, you can optionally
decide to compile Wine for 32 and 64 bit to create a "WOW64" build, but
you will always need at least the 32 bit part. Depending on the
Distribution you are using, this can be a bit complicated and you can
find some tips in [Building Wine](https://gitlab.winehq.org/wine/wine/-/wikis/Building-Wine#shared-wow64).
Wine Staging also supports the following optional dependencies:
| Library | Functionality |
|-----------------|------------------------------------------------|
| **libpulse** | PulseAudio support |
| **libattr** | Windows ACL support |
| **libtxc_dxtn** | DXTn software decoding / encoding support (\*) |
| **libva-x11** | GPU video decoding via X11 |
| **libva-drm** | GPU video decoding via DRM |
| **libgtk-3** | GTK3 theming support |
(\*) Since 1.7.37 it is not necessary anymore to have this library
available at build time, if it is called either `libtxc_dxtn.so` or
`libtxc_dxtn_s2tc.so.0`. If your distro uses a library with a
different name, you still need it. This change was done to simplify
building Wine Staging on distros where `libtxc_dxtn` is not available
in the official repositories.
The compilation will also continue without these libraries installed,
though you may want to provide as many features as possible if you are
creating a package.
### Instructions
The following instructions (based on the [Gentoo
Wiki](https://wiki.gentoo.org/wiki/Netflix/Pipelight#Compiling_manually))
will explain how to compile Wine Staging. If you encounter any problems,
feel free to join our IRC channel \#wine-staging.
As the first step please grab the latest Wine source (or use the git
repos for development):
```sh
$ wget https://prdownloads.sourceforge.net/wine/wine-1.7.38.tar.bz2
$ wget https://github.com/wine-compholio/wine-staging/archive/v1.7.38.tar.gz
```
Extract the archives:
```sh
$ tar xvjf wine-1*.tar.bz2
$ cd wine-1*
$ tar xvzf ../v1.7.38.tar.gz --strip-components 1
```
And apply the patches:
```sh
$ ./patches/patchinstall.sh DESTDIR="$(pwd)" --all
```
Afterwards run configure (you can also specify a prefix if you don't
want to install Wine Staging system-wide:
`--prefix=$HOME/staging-test`):
```sh
$ ./configure --with-xattr
```
Before you continue you should make sure that `./configure` doesn't show
any warnings (look at the end of the output). If there are any warnings,
this most likely means that you're missing some important header files.
Install them and repeat the `./configure` step until all problems are
fixed.
Afterwards compile everything (and grab a cup of coffee):
```sh
$ make
```
And install it (you only need sudo for a system-wide installation):
```sh
$ sudo make install
```
### Failure to apply all patches
When trying to build the current git version of Wine Staging (and not a
release tag), it can happen from time to time that `patchinstall.sh`
will fail because of a failure to apply all patches. This happens either
when patches get upstream into the development branch (and have to be
deleted from Wine Staging), or when changes in the development branch
conflict with Wine Staging patchsets. In both cases we will try to fix
the problem as soon as possible, and there is usually no need to open a
separate bug report for it.
To workaround this issue, you can run:
```sh
$ ./patches/patchinstall.sh --upstream-commit
```
It will return a git commit hash like
`d04a54857cc84f881393e4bc794185650a302084`. By checking out exactly this
commit in the Wine git repository, you should be able to apply all
patches without issues. Alternatively you can also wait until we push a
commit to rebase Wine Staging against the current development branch.
### Excluding patches
It is also possible to apply only a subset of the patches, for example
if you're compiling for a distribution where PulseAudio is not
installed, or if you just don't like a specific patchset. Please note
that some patchsets depend on each other, and requesting an impossible
situation might result in a failure to apply all patches.
Lets assume you want to exclude the patchset in directory `DIRNAME`,
then just invoke the script like this:
```sh
$ ./patches/patchinstall.sh DESTDIR="$(pwd)" --all -W DIRNAME
```
Using the same method its also possible to exclude multiple patchsets.
If you want to exclude a very large number of patches, it is easier to
do specify a list of patches which should be included instead. To apply
for example only the patchsets in directory `DIRNAME1` and `DIRNAME2`,
you can use:
```sh
$ ./patches/patchinstall.sh DESTDIR="$(pwd)" DIRNAME1 DIRNAME2
```
## Additional notes for package maintainers
Some applications and games require fonts like Arial or Courier to run
properly. In order to fix this problem Wine Staging contains some open
source replacement fonts which use the same metrics as the original
fonts by Microsoft. These fonts are licensed under different terms than
Wine and you will need to ship the according license files.
By applying the font patches the LICENSE file is being updated to
reflect which files are covered by which license. Moreover you will also
get the following new files containing the individual licenses:
`COPYING.arial`, `COPYING.cour` and `COPYING.msyh`. Simply add these
files to your package.

52
Usage.md Normal file

@ -0,0 +1,52 @@
Since we don't want to duplicate a lot of information here, we
recommend to take a look at the official [Wine
FAQ](https://gitlab.winehq.org/wine/wine/-/wikis/FAQ) for general
information about how to use Wine. The following part will mainly
concentrate on the differences between Wine and Wine Staging.
## Multiple Wine versions
It is absolutely no problem to have multiple versions of Wine installed
at the same time, for example regular system Wine located in
`/usr/bin/wine` and Wine Staging in `/opt/wine-staging/bin/wine`.
Nevertheless it can be confusing for beginners, so when you plan to use
Wine Staging as a replacement for system-Wine it might be useful to
install the `wine-staging-compat` compatibility symlinks package, which
allows to omit the `/opt/wine-staging/bin/` part in all following
commandlines. Please refer to the installation instructions for more
details.
If you prefer to continue with multiple Wine versions, make sure to type
always the full path in order to select the right one. You can switch
between versions as often as you like - just make sure that all Windows
programs have terminated before starting them with a different version.
## Running Wine Staging
To run Wine Staging without compatibility symlinks always type
`/opt/wine-staging/bin/wine`, for example:
cd ~/.wine/drive_c/<your path>/
/opt/wine-staging/bin/wine game.exe
You also have to add `/opt/wine-staging/bin/` when running other wine
related programs, here are some additional examples:
# Initialize the wine prefix
/opt/wine-staging/bin/wineboot
# Open the wine configuration
/opt/wine-staging/bin/winecfg
# Run winepath to convert paths
/opt/wine-staging/bin/winepath --unix 'c:\Windows'
# Kill the running wineserver instance
/opt/wine-staging/bin/wineserver -k
## Wineprefix
Unless you specify a special `WINEPREFIX` environment variable, Wine
Staging will use the same wineprefix `~/.wine` (in your home directory)
like regular Wine. This allows you to use your already installed
programs directly, without much effort or re-installing them.

315
home.md Normal file

@ -0,0 +1,315 @@
---
title: Wine Staging
---
## 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](https://gitlab.winehq.org/wine/wine-staging) 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.
The current Wine-Staging team is:
- Alistair Leslie-Hughes (lead maintainer)
- Dean Greer
- Paul Gofman
- Thomas Crider
- Zeb Figura
## Installation
Pre-compiled Staging packages for most major distributions are
available on the
[Download](https://gitlab.winehq.org/wine/wine/-/wikis/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](https://gitlab.winehq.org/wine/wine/-/wikis/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 GitLab
page](https://gitlab.winehq.org/wine/wine-staging).
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 `staging/patchinstall.py` script
(introduced with wine-staging 5.6, for earlier versions use
`patches/patchinstall.sh`); 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](https://gitlab.winehq.org/wine/wine/-/wikis/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/staging/patchinstall.py --all --backend=git-am --force-autoconf -d path/to/wine/source/dir
. 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](https://gitlab.winehq.org/wine/wine/-/wikis/Regression-Testing).
### 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.
## Submitting patches
We welcome everyone, old and new contributors alike, to contribute new
patches to Wine-Staging. Our primary goal is to offer a place for large,
incomplete, or risky patchsets to be tested and maintained until they
are ready for inclusion into upstream Wine. For new developers, we also
try to provide a more helpful and less demanding environment to get
acquainted with the Wine project.
### Requirements
Our standards are less strict than upstream Wine, but we do still have
some requirements:
- The patch must be a step in the right direction; that is, we don't
allow patches that are gross hacks, or take an obviously wrong
approach to solving a problem. The end goal is always to submit the
patch upstream eventually, so work should progress in that direction.
- The patch must have a bug attached. We place great value on
traceability, so we require all patches to have an associated WineHQ
bug (exceptions may be granted under special circumstances). We also
strongly encourage all discussion to take place on the relevant bug.
- Like upstream Wine, a patch must have correct attribution. If you did
not write a patch, you must make this clear (ideally using the From:
line in the patch itself). You must use your real name.
- Like upstream Wine, we cannot take contributions from anyone who has
disassembled or reverse-engineered Microsoft code, or seen sources
(whether leaked or publicly available).
### How to submit
Since we need a bug report anyway, the ideal way to submit a patch is
simply to attach it to the given bug report. If you have a patch (or
patch set) which fixes a bug and you'd like it to be included in
staging, please attach it to the bug as a patch against Wine (rather
than against the Wine-Staging tree itself). Instructions for how to
create patches against Wine can be found at [Submitting
Patches](https://gitlab.winehq.org/wine/wine/-/wikis/Submitting-Patches). If
you have several patches, please compress them into a single tarball
or zip instead of attaching each one individually.
Then, CC or e-mail Alistair Leslie-Hughes (leslie_alistair AT SPAMFREE
hotmail DOT com) and Zeb Figura (z DOT figura 12 AT SPAMFREE gmail DOT
com) on the bug asking for acceptance into Staging. Please be explicit
and provide details about the patch if you can, and tell us why you are
submitting the patch into Staging rather than upstream Wine. If
accepted, we will add your patch into the Staging tree, creating the
definition files and updating the install script as necessary.
We may ask you to submit your patch upstream first if it seems good
enough already. Remember that Wine-Staging is never the ultimate goal
for a patch; all patches should eventually get into upstream Wine.
## Maintaining Staging
At the time of this writing, none of the Staging maintainers plan to go
anywhere. Nevertheless, so that all future hand-offs proceed smoothly,
I've attempted to document the general process of maintaining Staging
below, or at least the parts that particularly need instructions.
### Organization
The layout of the Staging repository is mostly self-explanatory. The
`staging/` directory contains tools to maintain the patches, and the
`patches/` directory contains the patches themselves, as well as the
\`patchinstall.sh\` script to install them.
Each set of patches is contained within a single folder, labeled
\`component-Short_Description\`, where the component is the most salient
DLL or source directory (as with upstream Wine). Each set contains one
or more patches, plus a \`definition\` file. This latter file uses a
relatively simple format that looks like this:
Fixes: [10000] The original win32 api implementation is still more popular than wine.
Depends: ntdll-Some_Dependency
Depends: server-Another_Dependency
Disabled: true
The `Fixes:` line was historically used by a tool that would check
whether a linked bug was still open. That tool was rarely useful and has
been removed. Specifying it is still a convenience, though. At any rate
any new patch set added to the tree \*must\* have a corresponding bug
linked somewhere, either in the patches themselves or in the definition
file.
Each `Depends:` line gives the name of a patch set that *must* be
applied before this one is applied. Sometimes this dependency is given
for the purpose of functionality; i.e. this patch simply won't work
without its dependency also applied. More often it's given because the
two patches touch closely related code, and the diffs would conflict if
they were applied independently.
A `Disabled:` line may be added if necessary. We try to avoid this if at
all possible. A disabled patch is not being maintained, is not being
rebased, is not being tested, and is really useless to everyone, with
the exception that it's at least visible if anyone wants to look for it.
The line may be omitted if the patch is not disabled (i.e. you don't
have to put `false`).
### Rebasing
We currently rebase staging onto upstream wine after every daily commit
round. We could do it less often, but this has a tendency to make
changes pile up and become much more difficult to deal with. The point
of rebasing is to change the patches to apply directly on top of
upstream. We have scripts to make this relatively simple.
I keep a separate git worktree, which is entirely clean (no untracked
files) so that I can just run `git clean -df` to wipe artifacts of
rebasing.
Starting from an up-to-date source tree `wine/` and a not yet rebased
staging tree `wine-staging/`, my process of rebasing goes like this:
1. Examine the day's commit list and remove any Staging patches which
were upstreamed or obviated. Make sure to do this, as patches which
were upstreamed without changes will be silently ignored by
`git-am`.
2. From `wine-staging/`, run `./staging/newupdate.py`.
3. If applying the patches fails, repeat the following until it
succeeds:
1. From `wine/`, run
`wine-staging/staging/patchinstall.py -r `<name-Of_Patchset>.
This will fail inside of `git-am`.
2. Run `git am --show-current-patch | patch -p1`.
3. Resolve conflicts manually if fuzz detection wasn't enough.
4. Run `git add -u && git am --continue`. You may need to also
manually `git add` files that were added by the patch.
5. Run `git format-patch -N -1 --no-signoff`, and replace the
previous patch with that. Alternatively, replace -1 with a
larger number. Try to avoid changing the filename, though; it
makes things more difficult to trace. I usually just generate a
patch and then cp it onto the old filename. You can omit
--no-signoff by configuring `format.signOff` to false.
6. Make sure the updated diff makes sense—things didn't get applied
in completely the wrong place, upstream code didn't change to
break the functionality of the new changes. I often just read
the diff of the diffs, at a certain point it's easy enough to
tell
7. Run `git reset --hard origin && git clean -df` and go back to
step 2.
4. Build Wine.
5. Run winecfg, at least; make sure wine isn't completely broken. We
don't hold wine-staging to nearly as high a standard as upstream
wine, mostly because we simply don't have the time (note also that
currently many tests are broken on wine-staging anyway).
6. Run `./staging/commit-rebase.sh`.
7. Push.
## Quick Links
Here are some links to the most important topics.
- [Usage](Usage)
- [Configuration](Configuration)
- [Contributing](Contributing)
- [Bugs](https://bugs.winehq.org/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=STAGED&amp;bug_status=REOPENED&amp;bug_status=NEEDINFO&amp;bug_status=RESOLVED&amp;list_id=610554&amp;product=Wine-staging&amp;query_format=advanced)