diff --git a/README.md b/README.md index 64e543753..4740626cb 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ Box64 offers environment variables to control its behavior. For details, see [Us - [Compilation Instructions](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md) - [Bundle x86 Libraries](https://github.com/ptitSeb/box64/blob/main/docs/BUNDLE-X86-LIBS.md) -- [Wine Installation for Box64](https://github.com/ptitSeb/box64/blob/main/docs/X64WINE.md) +- [Wine Installation for Box64](https://github.com/ptitSeb/box64/blob/main/docs/WINE.md) --- diff --git a/README_CN.md b/README_CN.md index 44186a3b4..af6ff4071 100644 --- a/README_CN.md +++ b/README_CN.md @@ -34,7 +34,7 @@ Box64 提供了环境变量来控制其行为。有关详细信息请参阅[使 ## 🚀 编译和安装 - [编译说明](https://github.com/ptitSeb/box64/blob/main/docs/COMPILE.md) -- [安装 Wine](https://github.com/ptitSeb/box64/blob/main/docs/X64WINE.md) +- [安装 Wine](https://github.com/ptitSeb/box64/blob/main/docs/WINE.md) --- diff --git a/README_UK.md b/README_UK.md index 9aa8c305f..c998a09fe 100644 --- a/README_UK.md +++ b/README_UK.md @@ -37,7 +37,7 @@ Box64 інтегрується з DynaRec (динамічний рекомпіл Компіляція/Встановлення ---- > Інструкцію зі складання Box64 можна знайти [тут](docs/COMPILE.md).\ -> Інструкцію з встановлення Wine для Box64 можна знайти [тут](docs/X64WINE.md). +> Інструкцію з встановлення Wine для Box64 можна знайти [тут](docs/WINE.md). ---- Історія версій/Журнал змін diff --git a/docs/WINE.md b/docs/WINE.md new file mode 100644 index 000000000..199171842 --- /dev/null +++ b/docs/WINE.md @@ -0,0 +1,55 @@ +# The guide on using Wine with Box64 + +Wine Is Not an Emulator, but Box64 is. Box64 supports Wine in multiple ways. Before continuing reading, you should have a basic understanding of Wine. + +## Wine variants + +Wine ships in multiple forms: + + +1. **x86 Wine** + + The executable architecture of **x86 Wine** is x86, and it runs x32 Windows executables. + + **x86 Wine** requires a 32-bit environment (read 32-bit Linux libraries), which is usually available on x86_64 machines because of the nature of the architecture. + + However, when you try to run it via an emulator on RISC architectures, the situation is a bit different. For Arm64, there is armhf, which is a 32-bit environment, and there is also Box86, which is made for armhf, so you can use Box86 to run **x86 Wine**. + + However, for RISC-V 64, LoongArch64, and many newer Arm64 cores, a 32-bit environment is not available. Box64 introduced a new mode called Box32, which can be enabled at compile time via a CMake option `BOX32`. It essentially emulates a 32-bit environment using the 64-bit environment, so it can be used to run **x86 Wine**. But be aware that Box32 is still highly experimental and unstable. + +2. **x86_64 Wine** + + The executable architecture of **x86_64 Wine** is x86_64, and it runs x64 Windows executables. + + It can be used with Box64. Note that **x86_64 Wine** usually ships with **x86 Wine** included. So you can use a combination of Box86 + Box64 or Box64 alone with Box32 enabled to run both x32 and x64 executables seamlessly. + +3. **x86_64 Wine WOW64** + + The executable architecture of **x86_64 Wine WOW64** is x86_64, and it runs both x32 and x64 Windows executables. + + What's great about **x86_64 Wine WOW64** is that it does not require a 32-bit environment for x32 Windows executable, as the 32-bit environment emulation is taken care of by Wine WOW64 itself. + + That means you can just use Box64 (without Box32) to run x32 Windows executables. However, the downside is that the performance of WineD3D is pretty bad for 32-bit (use DXVK!). + +4. **Arm64 Wine WOW64** + + The executable architecture of **Arm64 Wine WOW64** is Arm64, and it runs + x32, x64, Arm32, Arm64 Windows executables. + + However, to run x32 and x64 ones, a cpu.dll is required, known as the + WOW64 (for 32-bit) and Arm64EC (for 64-bit). + + Box64 now supports 32-bit WOW64 DLL. You can have it compiled by enabling the `WOW64` CMake option. And we plan to support Arm64EC in the future. + +## Wine installation + +For x86 Wines, there are plenty of places to download, to name a few: + +- https://github.com/Kron4ek/Wine-Builds (Wine \[WOW64\]) +- https://github.com/GloriousEggroll/proton-ge-custom (Proton, known as the Valve-optimized Wine) + +After the download, just add the `bin` folder to your path in any way you like; Wine should work with Box64 just fine. + +To install components like DXVK, d3dcompiler_xx, or cjkfonts, it's recommended to use Winetricks: https://github.com/Winetricks/winetricks + +For Arm64 Wines, use of Hangover is recommended: https://github.com/AndreRH/hangover. \ No newline at end of file diff --git a/docs/X64WINE.md b/docs/X64WINE.md deleted file mode 100644 index 072fa6da3..000000000 --- a/docs/X64WINE.md +++ /dev/null @@ -1,177 +0,0 @@ -# Installing Wine64 -Running Wine64/Wine with Box64/Box86 allows x64/x86 Windows programs to run on 64-bit ARM Linux devices. - - Box64 needs `wine-amd64` to be installed **manually** on ARM64 (aarch64) devices. This will run 64-bit Windows programs (aka x86_64). - - Box86 needs `wine-i386` to be installed **manually** on ARM32 (armhf) devices (or on ARM64 with multiarch or chroot). This will run 32-bit Windows programs (aka x86). - - _Note that `wine:arm64` and `wine:armhf` will not work with Box64/Box86. Your device's package manager might try to install those if you ask it to install wine._ - -See installation steps below (in the [Examples](#examples) section). - -## Overview -The general procedure for installing Wine64 & Wine for Box64 & Box86 is to... - - Download all the install 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 (often `~/wine/` by default) - - Go to `/usr/local/bin` and make symlinks or scripts that will point to your main wine binaries. - - Boot wine to create a new wineprefix. - - Download winetricks (which is just a complicated bash script), make it executable, then copy it to `/usr/local/bin`. - -## Examples -### Installing Wine64 & Wine for Box64 & Box86 on Raspberry Pi OS from WineHQ .deb files -_Links from the [WineHQ repo](https://dl.winehq.org/wine-builds/debian/dists/)_ - -This install method allows you to install different versions of Wine64/Wine. You may install any version/branch of Wine that you wish. -``` - # NOTE: Can only run on aarch64 (since box64 can only run on aarch64) - # box64 runs wine-amd64, box86 runs wine-i386. - - ### User-defined Wine version variables ################ - # - Replace the variables below with your system's info. - # - Note that we need the amd64 version for Box64 even though we're installing it on our ARM processor. - # - Note that we need the i386 version for Box86 even though we're installing it on our ARM processor. - # - Wine download links from WineHQ: https://dl.winehq.org/wine-builds/ - - local branch="devel" #example: devel, staging, or stable (wine-staging 4.5+ requires libfaudio0:i386) - local version="7.1" #example: "7.1" - local id="debian" #example: debian, ubuntu - local dist="bullseye" #example (for debian): bullseye, buster, jessie, wheezy, ${VERSION_CODENAME}, etc - local tag="-1" #example: -1 (some wine .deb files have -1 tag on the end and some don't) - - ######################################################## - - # Clean up any old wine instances - wineserver -k # stop any old wine installations from running - rm -rf ~/.cache/wine # remove any old wine-mono/wine-gecko install files - rm -rf ~/.local/share/applications/wine # remove any old program shortcuts - - # Backup any old wine installs - rm -rf ~/wine-old 2>/dev/null; mv ~/wine ~/wine-old 2>/dev/null - rm -rf ~/.wine-old 2>/dev/null; mv ~/.wine ~/.wine-old 2>/dev/null - sudo mv /usr/local/bin/wine /usr/local/bin/wine-old 2>/dev/null - sudo mv /usr/local/bin/wine64 /usr/local/bin/wine-old 2>/dev/null - sudo mv /usr/local/bin/wineboot /usr/local/bin/wineboot-old 2>/dev/null - sudo mv /usr/local/bin/winecfg /usr/local/bin/winecfg-old 2>/dev/null - sudo mv /usr/local/bin/wineserver /usr/local/bin/wineserver-old 2>/dev/null - - # Wine download links from WineHQ: https://dl.winehq.org/wine-builds/ - LNKA="https://dl.winehq.org/wine-builds/${id}/dists/${dist}/main/binary-amd64/" #amd64-wine links - DEB_A1="wine-${branch}-amd64_${version}~${dist}${tag}_amd64.deb" #wine64 main bin - DEB_A2="wine-${branch}_${version}~${dist}${tag}_amd64.deb" #wine64 support files (required for wine64 / can work alongside wine_i386 main bin) - #DEB_A3="winehq-${branch}_${version}~${dist}${tag}_amd64.deb" #shortcuts & docs - LNKB="https://dl.winehq.org/wine-builds/${id}/dists/${dist}/main/binary-i386/" #i386-wine links - DEB_B1="wine-${branch}-i386_${version}~${dist}${tag}_i386.deb" #wine_i386 main bin - DEB_B2="wine-${branch}_${version}~${dist}${tag}_i386.deb" #wine_i386 support files (required for wine_i386 if no wine64 / CONFLICTS WITH wine64 support files) - #DEB_B3="winehq-${branch}_${version}~${dist}${tag}_i386.deb" #shortcuts & docs - - # Install amd64-wine (64-bit) alongside i386-wine (32-bit) - echo -e "Downloading wine . . ." - wget -q ${LNKA}${DEB_A1} - wget -q ${LNKA}${DEB_A2} - wget -q ${LNKB}${DEB_B1} - echo -e "Extracting wine . . ." - dpkg-deb -x ${DEB_A1} wine-installer - dpkg-deb -x ${DEB_A2} wine-installer - dpkg-deb -x ${DEB_B1} wine-installer - echo -e "Installing wine . . ." - mv wine-installer/opt/wine* ~/wine - - # Download wine dependencies - # - these packages are needed for running box86/wine-i386 on a 64-bit RPiOS via multiarch - sudo dpkg --add-architecture armhf && sudo apt-get update # enable multi-arch - sudo apt-get install -y libasound2:armhf libc6:armhf libglib2.0-0:armhf libgphoto2-6:armhf libgphoto2-port12:armhf \ - libgstreamer-plugins-base1.0-0:armhf libgstreamer1.0-0:armhf libldap-2.4-2:armhf libopenal1:armhf libpcap0.8:armhf \ - libpulse0:armhf libsane1:armhf libudev1:armhf libusb-1.0-0:armhf libvkd3d1:armhf libx11-6:armhf libxext6:armhf \ - libasound2-plugins:armhf ocl-icd-libopencl1:armhf libncurses6:armhf libncurses5:armhf libcap2-bin:armhf libcups2:armhf \ - libdbus-1-3:armhf libfontconfig1:armhf libfreetype6:armhf libglu1-mesa:armhf libglu1:armhf libgnutls30:armhf \ - libgssapi-krb5-2:armhf libkrb5-3:armhf libodbc1:armhf libosmesa6:armhf libsdl2-2.0-0:armhf libv4l-0:armhf \ - libxcomposite1:armhf libxcursor1:armhf libxfixes3:armhf libxi6:armhf libxinerama1:armhf libxrandr2:armhf \ - libxrender1:armhf libxxf86vm1 libc6:armhf libcap2-bin:armhf # to run wine-i386 through box86:armhf on aarch64 - # This list found by downloading... - # wget https://dl.winehq.org/wine-builds/debian/dists/bullseye/main/binary-i386/wine-devel-i386_7.1~bullseye-1_i386.deb - # wget https://dl.winehq.org/wine-builds/debian/dists/bullseye/main/binary-i386/winehq-devel_7.1~bullseye-1_i386.deb - # wget https://dl.winehq.org/wine-builds/debian/dists/bullseye/main/binary-i386/wine-devel_7.1~bullseye-1_i386.deb - # then `dpkg-deb -I package.deb`. Read output, add `:armhf` to packages in dep list, then try installing them on Pi aarch64. - - # - these packages are needed for running box64/wine-amd64 on RPiOS (box64 only runs on 64-bit OS's) - sudo apt-get install -y libasound2:arm64 libc6:arm64 libglib2.0-0:arm64 libgphoto2-6:arm64 libgphoto2-port12:arm64 \ - libgstreamer-plugins-base1.0-0:arm64 libgstreamer1.0-0:arm64 libldap-2.4-2:arm64 libopenal1:arm64 libpcap0.8:arm64 \ - libpulse0:arm64 libsane1:arm64 libudev1:arm64 libunwind8:arm64 libusb-1.0-0:arm64 libvkd3d1:arm64 libx11-6:arm64 libxext6:arm64 \ - ocl-icd-libopencl1:arm64 libasound2-plugins:arm64 libncurses6:arm64 libncurses5:arm64 libcups2:arm64 \ - libdbus-1-3:arm64 libfontconfig1:arm64 libfreetype6:arm64 libglu1-mesa:arm64 libgnutls30:arm64 \ - libgssapi-krb5-2:arm64 libjpeg62-turbo:arm64 libkrb5-3:arm64 libodbc1:arm64 libosmesa6:arm64 libsdl2-2.0-0:arm64 libv4l-0:arm64 \ - libxcomposite1:arm64 libxcursor1:arm64 libxfixes3:arm64 libxi6:arm64 libxinerama1:arm64 libxrandr2:arm64 \ - libxrender1:arm64 libxxf86vm1:arm64 libc6:arm64 libcap2-bin:arm64 - # This list found by downloading... - # wget https://dl.winehq.org/wine-builds/debian/dists/bullseye/main/binary-amd64/wine-devel_7.1~bullseye-1_amd64.deb - # wget https://dl.winehq.org/wine-builds/debian/dists/bullseye/main/binary-amd64/wine-devel-amd64_7.1~bullseye-1_amd64.deb - # then `dpkg-deb -I package.deb`. Read output, add `:arm64` to packages in dep list, then try installing them on Pi aarch64. - - # These packages are needed for running wine-staging on RPiOS (Credits: chills340) - sudo apt install libstb0 -y - cd ~/Downloads - wget -r -l1 -np -nd -A "libfaudio0_*~bpo10+1_i386.deb" http://ftp.us.debian.org/debian/pool/main/f/faudio/ # Download libfaudio i386 no matter its version number - dpkg-deb -xv libfaudio0_*~bpo10+1_i386.deb libfaudio - sudo cp -TRv libfaudio/usr/ /usr/ - rm libfaudio0_*~bpo10+1_i386.deb # clean up - rm -rf libfaudio # clean up - - # Install symlinks - sudo ln -s ~/wine/bin/wine /usr/local/bin/wine - sudo ln -s ~/wine/bin/wine64 /usr/local/bin/wine64 - sudo ln -s ~/wine/bin/wineboot /usr/local/bin/wineboot - sudo ln -s ~/wine/bin/winecfg /usr/local/bin/winecfg - sudo ln -s ~/wine/bin/wineserver /usr/local/bin/wineserver - sudo chmod +x /usr/local/bin/wine /usr/local/bin/wine64 /usr/local/bin/wineboot /usr/local/bin/winecfg /usr/local/bin/wineserver -``` - -## Installing winetricks -Winetricks is a bash script which makes it easier to install & configure any desired Windows core system software packages which may be dependencies for certain Windows programs. You can either install it with `apt`, or manually using the steps below. - -``` -sudo apt-get install cabextract -y # winetricks needs this installed -sudo mv /usr/local/bin/winetricks /usr/local/bin/winetricks-old # Backup old winetricks -cd ~/Downloads && wget https://raw.githubusercontent.com/Winetricks/winetricks/master/src/winetricks # Download -sudo chmod +x winetricks && sudo mv winetricks /usr/local/bin/ # Install -``` - -Whenever we run winetricks, we must tell Box86 to supress its info banner, otherwise winetricks will crash. Box86's info banner can be suppressed using the `BOX86_NOBANNER=1` environment variable before invoking winetricks (example: `BOX86_NOBANNER=1 winetricks`). - -If `apt` installed a desktop menu shortcut for winetricks (or if you make your own desktop shortcut for winetricks) then you may need to edit that shortcut to include Box86's BOX86_NOBANNER=1 env var. With your favorite text editor, edit `/usr/share/applications/winetricks.desktop` and change `Exec=winetricks --gui` to `Exec=env BOX86_NOBANNER=1 winetricks --gui`. - -## Example commands -Creating a 64-bit wineprefix: -`wine64 wineboot` or `wine wineboot` (wineprefix is created in `~/.wine/`) -`WINEPREFIX="$HOME/prefix64" wine wineboot` (wineprefix is created in `~/prefix64/`) _Note: You will need to invoke `WINEPREFIX="$HOME/prefix64"` before every command to use this wineprefix._ - -Creating a 32-bit wineprefix: -`WINEARCH=win32 wine wineboot` (wineprefix is created in `~/.wine/`) - -Fore-quitting wine: -`wineserver -k` - -Running Wine Configuration: -`winecfg` - -Using winetricks: -`winetricks -q corefonts vcrun2010 dotnet20sp1` -_This command will silently install three packages in series: Windows core fonts, VC++ 2010 Runtimes, and .NET 2.0 SP1. `-q` is the "install silent/quiet" command._ - -Invoking Box86's logging features (with `BOX86_LOG=1` or similar) will cause winetricks to crash. - -For a list of all the different Windows packages & libraries that winetricks can help you install, run `winetricks list-all` - -## Other notes - -### Wineprefixes (and Wine initialization) -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). Think of a wineprefix as Wine's virtual 'harddrive' where it installs software and saves settings. Wineprefixes are portable and deletable. For more Wine documentation, see [WineHQ](https://www.winehq.org/documentation). - -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 -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 (`tar -xf winebottle.tar`) on your device running Box86 & Wine. Tarring the wineprefix preserves any symlinks that are inside it. - -### Swapping out different versions of Wine -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. _Note that the wine-staging branch requires extra installation steps on Raspberry Pi._ - -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). - -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 migrate a wineprefix from an older version of Wine to be usable by the newer version of Wine you just installed. You can check which version of Wine you're running with the `wine --version` command.