Debugging
Debugging in Wine can be difficult, but Whisky comes equipped with some tools and tricks to make the process a bit easier.
Making Metal GPU Captures
important
Debugging GPU issues experienced under Wine on macOS can be an arduous task. This guide will assume that you have prior experience with Xcode, LLDB, and Metal GPU tools.
- In Xcode, create a new empty macOS project. This will be used to attach to the process but the project itself does not matter.
- Enable both
Metal HUDandMetal Tracein your Bottle Configuration - Launch the intended target in Whisky
- Open
Activity Monitorand find thePIDof thewine64-preloaderprocess that is utilising the GPU - In Xcode click on
Debug > Attach to Process by PID or Name... - Type in the
PIDof the target process and pressTABso that Xcode recognises that you've changed the value of the field. - Leave the rest of the options as their defaults and press
Attach
warning
This is the step where things are most likely to go wrong.
Have patience, it may take several attempts, or it may not work at all for your target program.
Being stopped at a SIGUSR1 signal is normal. If you get a EXC_BAD_ACCESS or other error the next steps will not work.
- In the LLDB console run
pro hand -p true -s false SIGUSR1and thencontinue - In the bar above the LLDB console there should be a Metal logo, click on it and adjust the scope and count as needed and press
Capture
warning
If it does not appear Xcode has not detected the GPU workload for this process, and you will not be able to create a capture.
note
Metal GPU captures can grow very quickly in size for complex titles. Captures larger than the amount of RAM available on your system will likely crash and be unusable.
If all has gone to plan, you will now have a full Metal GPU capture of the target Wine process, allowing you to debug graphics issues with the same tools you would use for a native macOS title. These same steps should work regardless of graphics API i.e. DX12, DX11, Vulkan, or OpenGL.