Maybe adding more pages to the readme for "trouble-shooting" and "wine installation"?

[WheezyE]

I've been thinking about writing up some documentation to add to the readme for common topics I've been seeing in the Discord, but wanted people's input / editing / permission. I wasn't sure if Discord or git issues would be the best place to post this, but it got kind of long, so I figured maybe Git would be better for readability. I'd love to have Seb's thoughts on this, especially, since I don't want to make lots of unwanted changes or anything to the readme. Anyway, here's my plan:

I was thinking of two sections: "Installing Wine & Winetricks" & "Trouble-Shooting"

• I think Wine+Box86 has been around long enough that we've learned a lot about it and can provide others with some insight on it now.
• I've also wanted to search through the Discord for all the tips/tricks Seb and others have shared (and invite people to share their notes files) and compile all that info into one reference (also so new people don't keep asking the same questions on the Discord).

Installing Wine & Winetricks

Wine for Box86 and winetricks come pre-installed on TwisterOS.

Your entire Wine installation can reside within a single folder on your Linux computer. TwisterOS assumes that your Wine installation is located inside the ~/wine/ directory. The actual directory where you put your wine folder doesn't matter as long as you have symlinks within the /usr/local/bin/ directory which point to the wine folder so that Linux can find Wine when you type wine into the terminal). When you first run or boot Wine (wine wineboot), Wine will create a new user environment within which to install Windows software. This user environment is called a "wineprefix" (or "wine bottle") and is located (by default) in ~/.wine (note that Linux folders with a . in front of them are "hidden" folders). For more Wine documentation, see WineHQ.

Some versions of Wine work better with certain software. It is best to install a version of Wine that is known to work with the software you would like to run. There are three main development branches of Wine you can pick from, referred to as wine-stable, wine-devel, and wine-staging. The wine-staging branch requires extra installation steps on Raspberry Pi.

Install files for Wine can be found from the TwisterOS FAQ page, the PlayOnLinux website, or the WineHQ repository. Box86 requires the "i386" versions of Wine install files (even though we are installing it on an ARM processor) since Box86 "wraps" many of Wine's core i386 libraries to interpret them for ARM. Below are examples of how to install Wine from each of those places.

Winetricks is a script which automates installation & configuration of some core Windows software for Wine.

Wine installation steps overview
The general procedure for installing Wine for Box86 is to...

• Download all the install files (.deb, .zip, or .pol files) for the version of Wine you wish to install
• Unzip or dpkg the install files into one folder
• Move that folder to the directory that you wish Wine to run from (in TwisterOS, this is ~/wine/ by default)
• Go to /usr/local/bin and make symlinks or scripts that will point to your main wine binaries (wine, winecfg, and wineserver).
• Boot wine to create a new wineprefix

Wine installation examples
Installing wine-devel, wine-stable, or wine-staging for Raspberry Pi OS Buster from WineHQ deb files
Links are from https://dl.winehq.org/wine-builds/debian/dists/buster/main/binary-i386/
(replace the links / version numbers below with links from the winehq repo for the version of Wine you wish to install)

# Backup any old wine installations
sudo mv ~/wine ~/wine-old
sudo mv ~/.wine ~/.wine-old
sudo mv /usr/local/bin/wine /usr/local/bin/wine-old
sudo mv /usr/local/bin/winecfg /usr/local/bin/winecfg-old
sudo mv /usr/local/bin/wineserver /usr/local/bin/wineserver-old

# These packages are only needed for wine-staging (credits: chills340)
sudo apt install libstb0
cd ~/Downloads
wget http://ftp.us.debian.org/debian/pool/main/f/faudio/libfaudio0_20.11-1~bpo10+1_i386.deb
dpkg-deb -xv libfaudio0_20.11-1~bpo10+1_i386.deb libfaudio
sudo cp -TRv libfaudio/usr/ /usr/

# Download and extract
cd ~/Downloads
wget https://dl.winehq.org/wine-builds/debian/dists/buster/main/binary-i386/wine-devel-i386_5.21~buster_i386.deb # Note that we need the i386 version for Box86 even though we're installing it on our ARM processor
wget https://dl.winehq.org/wine-builds/debian/dists/buster/main/binary-i386/wine-devel_5.21~buster_i386.deb
dpkg-deb -xv wine-devel-i386_5.21~buster_i386.deb wine-installer
dpkg-deb -xv wine-devel_5.21~buster_i386.deb wine-installer

# Install (move wine folder into place and make symlinks)
sudo mv wine-installer/opt/wine-devel ~/wine
sudo ln -s ~/wine/bin/wine /usr/local/bin/wine
sudo ln -s ~/wine/bin/winecfg /usr/local/bin/winecfg
sudo ln -s ~/wine/bin/wineserver /usr/local/bin/wineserver

# Boot wine (make fresh wineprefix in ~/.wine )
wine wineboot

Installing Wine for Raspberry Pi OS from PlayOnLinux pol files
Links are from https://www.playonlinux.com/wine/binaries/linux-x86/

# future work

Installing Wine for Raspberry Pi OS from the TwisterOS FAQ zip file

# future work

Wineprefixes (and Wine initialization)
The first time Wine is run (wine wineboot), it will create a fresh wineprefix for you (by default, located in the hidden folder ~/.wine). Think of a wineprefix as Wine's virtual 'harddrive' where it installs software and saves settings. Wineprefixes are portable and deletable.

If you at any point corrupt something inside your default wineprefix, you can start "fresh" by deleting your ~/.wine directory (with the rm -rf ~/.wine command) and boot wine again to create a new default wineprefix.

Transplanting wineprefixes (side-loading)
If software isn't installing in Wine with Box86, but is installing for you in Wine on a regular x86 Linux computer, you can copy a wineprefix from your x86 Linux computer to the device you're running Box86 on. This is most easily done by tarring the ~/.wine folder on your x86 Linux computer (tar -cvf winebottle.tar ~/.wine), transferring the tar file to your device, then un-tarring the tar file on your device running Box86 & Wine. Tarring the wineprefix preserves any symlinks that are inside it.

Swapping out different versions of Wine
You can change which version of Wine you are running simply by renaming your old wine and .wine folders to something else, then putting a new wine folder (containing your new version of Wine) in its place. Running wine wineboot again will make a fresh wineprefix with your new version of Wine. You can check which version of Wine you're running with the wine --version command.

Installation and use of Winetricks

# Backup old winetricks
sudo mv /usr/local/bin/winetricks /usr/local/bin/winetricks-old

# Download
cd ~/Downloads
wget https://raw.githubusercontent.com/Winetricks/winetricks/master/src/winetricks

# Install
sudo chmod +x winetricks
sudo cp winetricks /usr/local/bin

# winetricks needs this installed
sudo apt-get install cabextract -y

Whenever we run winetricks, we must suppress Box86's banner by typing BOX86_NOBANNER=1 to avoid errors. Similarly, invoking Box86's logging features (with BOX86_LOG=1 or similar) will cause winetricks to crash (unless we patch winetricks - see the Troubleshooting section below).

Here is an example of a winetricks proper command:
BOX86_NOBANNER=1 winetricks -q corefonts vcrun2010 dotnet35sp1

Trouble-Shooting

Enabling logging
You can tell Box86 to be more verbose with errors and log terminal output with commands like:

BOX86_LOG=1 wine YOURPROGRAM.exe 2>&1 | tee logfile.txt

Using BOX86_LOG=1 is usually sufficient for finding errors. Much more output can be generated with BOX86_LOG=2 though for cases where no obvious error can be found with BOX86_LOG=1. Log files from LOG=2 can be 500MB or more. Large log files are difficult to read on slower processors, so it is often easier to zip a large log file, transfer it to a more powerful computer, then read the large log file using a log reader program (like UltraEdit for example).

Logging causes wine to go very slowly and hang for a few minutes every once in a while.

Common Box86 error messages
SIGSEGV
DOUBLESIGSEGV

Best practices for testing wine programs
Test in x86 Linux wine first.

Hunting down regressions with test.sh
As Box86 continues to be developed, occasionally "regressions" can crop up. A regression is when a program used to work with Box86, but doesn't anymore. Regressions are often most easily found by installing older versions of Box86 until you find out the last version of Box86 that ran the program. Once we know which version of Box86 broke the program, we can try to locate the code in the Box86 commit that broke the program.

Because it takes longer to compile Box86 than it does to download a pre-compiled version, Pale has created a script that will let you download a version of Box86 built from the last commit of the day. Using this script can save a lot of time when tracking down regressions. You can download Pale's script here.

Git bisect is another way to find regressions.

Opcodes & Zydis Info
Sometimes Box86 will find an x86ams opcode that it doesn't know how to interpret yet. Opcode errors look like this:

18228|0x6427ee2b: Unimplemented Opcode F4 08 00 00 00 00 00 04

Zydis is a helpful Linux program for interpreting and exploring opcodes (credits: Seb). You can build and install Zydis with the following commands:

sudo apt-get install cmake -y
git clone --recursive 'https://github.com/zyantific/zydis.git'
cd zydis
mkdir build && cd build
cmake ..
make
sudo make install

Run Zydis with ZydisInfo -32 YOUROPCODEHERE
Look under the INTEL section to help interpret your x86 ASM opcode as interpreted with Intel-based architecture.

Note: If you get an opcode error that looks like this

Unimplemented Opcode (00) F3 51 5C 03 06 00 00 00

Then the (00) is just the previous byte of a previous instruction. In this case, you would run ZydisInfo -32 F3 51 5C 03 06 00 00 00 (or in this case, ZydisInfo -32 F3 51 would also work).

Some GDB basics
I might need someone else to expand this.

Winetricks patch for box86 error logging/debugging
If you need to use BOX86_LOG=1 (or similar) on something that winetricks installs, you will need to patch the winetricks. This patch is kind of a kludge, but works for now.

# patch line 2853 of winetricks-20200412 to avoid "adobeair corrupt" error
sudo sed -i 's|echo "\${arg%%=\*}"=\\""${arg#\*=}"\\"|echo \${arg%%=\*}=\\"\${arg#\*=}\\"|g' /usr/local/bin/winetricks

[WheezyE]

Just edited the above post by expanding the sections a bit

[Hacker1245]

Maybe add the Mesa 20.2 build script into troubleshooting? https://cdn.discordapp.com/attachments/700827603623346278/801066815970082816/mesabuild.sh
Credit: phoenixbyrd

[QueenPew]

That's a pretty good thing! maybe the troubleshooting section should be added in a separate document, like TROUBLESHOOTING.md or something?

[ptitSeb]

moving this to Discussion.