commit 42508fd3867f3616e41cd29ab292549405b39572 Author: Alexandre Julliard Date: Wed Sep 4 11:16:44 2024 +0200 Import pages from MediaWiki. diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..1ed58bf --- /dev/null +++ b/Configuration.md @@ -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) diff --git a/Configuration/CUDA.md b/Configuration/CUDA.md new file mode 100644 index 0000000..af1c072 --- /dev/null +++ b/Configuration/CUDA.md @@ -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. diff --git a/Configuration/Dll-Redirects.md b/Configuration/Dll-Redirects.md new file mode 100644 index 0000000..923e3de --- /dev/null +++ b/Configuration/Dll-Redirects.md @@ -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:
+![](/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 new file mode 100644 index 0000000..705e7f1 --- /dev/null +++ b/Configuration/Environment-Variables.md @@ -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. diff --git a/Configuration/Miscellaneous.md b/Configuration/Miscellaneous.md new file mode 100644 index 0000000..08e2e0e --- /dev/null +++ b/Configuration/Miscellaneous.md @@ -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. diff --git a/Configuration/PhysX.md b/Configuration/PhysX.md new file mode 100644 index 0000000..f3c4fb8 --- /dev/null +++ b/Configuration/PhysX.md @@ -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. diff --git a/Configuration/Registry-redirects.png b/Configuration/Registry-redirects.png new file mode 100644 index 0000000..16140d6 Binary files /dev/null and b/Configuration/Registry-redirects.png differ diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..7a218f9 --- /dev/null +++ b/Contributing.md @@ -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. diff --git a/Packaging.md b/Packaging.md new file mode 100644 index 0000000..fc73079 --- /dev/null +++ b/Packaging.md @@ -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. diff --git a/Usage.md b/Usage.md new file mode 100644 index 0000000..5e5d10d --- /dev/null +++ b/Usage.md @@ -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// + /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 new file mode 100644 index 0000000..fda849e --- /dev/null +++ b/home.md @@ -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 `. + 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)