diff --git a/Configuration.md b/Configuration.md index 1ed58bf..1e6472d 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,12 +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) +## 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) diff --git a/Configuration/CUDA.md b/Configuration/CUDA.md index af1c072..f84b790 100644 --- a/Configuration/CUDA.md +++ b/Configuration/CUDA.md @@ -1,43 +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. +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. diff --git a/Configuration/Dll-Redirects.md b/Configuration/Dll-Redirects.md index 923e3de..a3b6448 100644 --- a/Configuration/Dll-Redirects.md +++ b/Configuration/Dll-Redirects.md @@ -1,56 +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:
-![](/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. +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:
+![](/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. diff --git a/Configuration/Environment-Variables.md b/Configuration/Environment-Variables.md index 705e7f1..474e22b 100644 --- a/Configuration/Environment-Variables.md +++ b/Configuration/Environment-Variables.md @@ -1,106 +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. +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. diff --git a/Configuration/Miscellaneous.md b/Configuration/Miscellaneous.md index 08e2e0e..01dd1b7 100644 --- a/Configuration/Miscellaneous.md +++ b/Configuration/Miscellaneous.md @@ -1,38 +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. +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. diff --git a/Configuration/PhysX.md b/Configuration/PhysX.md index f3c4fb8..f0dedd8 100644 --- a/Configuration/PhysX.md +++ b/Configuration/PhysX.md @@ -1,22 +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. +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. diff --git a/Contributing.md b/Contributing.md index 7a218f9..6bd3716 100644 --- a/Contributing.md +++ b/Contributing.md @@ -1,112 +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. +## 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. diff --git a/Packaging.md b/Packaging.md index fc73079..cc25b3a 100644 --- a/Packaging.md +++ b/Packaging.md @@ -1,156 +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. +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. diff --git a/Usage.md b/Usage.md index 5e5d10d..f95fc12 100644 --- a/Usage.md +++ b/Usage.md @@ -1,52 +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// - /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. +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// + /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. diff --git a/home.md b/home.md index fda849e..b9d6228 100644 --- a/home.md +++ b/home.md @@ -1,315 +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 `. - 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&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) +--- +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 `. + 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&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)