Difference between revisions of "Development:Setting up FEX"

From FEX-Emu Wiki
Jump to navigation Jump to search
m (FEXInterpreter -> FEX)
 
(36 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[Category:Development]]
 
[[Category:Development]]
 
== Build dependencies ==
 
== Build dependencies ==
 +
=== Debian/Ubuntu dependencies ===
 
* git
 
* git
 
* cmake
 
* cmake
 
* ninja-build
 
* ninja-build
−
* pkg-config
+
* pkgconf
 
* ccache (Recommended if you're rebuilding constantly)
 
* ccache (Recommended if you're rebuilding constantly)
 
* clang
 
* clang
 +
* llvm
 
* lld (For ThinLTO)
 
* lld (For ThinLTO)
 
* binfmt-support (For AArch64 binfmt_misc support)
 
* binfmt-support (For AArch64 binfmt_misc support)
−
* libsdl2-dev (For GUI)
+
* libssl-dev
−
* libepoxy-dev (For GUI)
+
* python-setuptools (For build scripts)
 
* g++-x86-64-linux-gnu (For building thunks)
 
* g++-x86-64-linux-gnu (For building thunks)
 +
* libgcc-XX-dev-i386-cross (For building thunks, version should match your g++-x86-64-linux-gnu package)
 +
* libgcc-XX-dev-amd64-cross (For building thunks, version should match your g++-x86-64-linux-gnu package)
 
* nasm (only if building tests)
 
* nasm (only if building tests)
 
* python3-clang (for struct verifier)
 
* python3-clang (for struct verifier)
−
* libstdc++-10-dev-i386-cross (for struct verifier)
+
* libstdc++-12-dev-i386-cross (for struct verifier)
−
* libstdc++-10-dev-amd64-cross (for struct verifier)
+
* libstdc++-12-dev-amd64-cross (for struct verifier)
−
* libstdc++-10-dev-arm64-cross (for struct verifier)
+
* libstdc++-12-dev-arm64-cross (for struct verifier)
 
* squashfs-tools (For squashfs rootfs support)
 
* squashfs-tools (For squashfs rootfs support)
 
* squashfuse (For mounting the squashfs)
 
* squashfuse (For mounting the squashfs)
 
* libc-bin or glibc-tools (For unittests, needs catchsegv from this)
 
* libc-bin or glibc-tools (For unittests, needs catchsegv from this)
−
* gcc-multilib (For FEXLinuxTests)
+
* libc6-dev-i386-amd64-cross (For FEXLinuxTests)
−
* g++-multilib (For FEXLinuxTests)
+
* lib32stdc++-XX-dev-amd64-cross (For FEXLinuxTests, version should match your g++-x86-64-linux-gnu package)
 +
* qtdeclarative5-dev (For GUI)
 +
* qml-module-qtquick-controls (For GUI)
 +
* qml-module-qtquick-controls2 (For GUI)
 +
* qml-module-qtquick-dialogs (For GUI)
  
 
=== Gentoo dependencies ===
 
=== Gentoo dependencies ===
Line 30: Line 38:
 
* clang
 
* clang
 
* lld
 
* lld
−
* libsdl2
 
−
* libepoxy
 
 
* nasm
 
* nasm
  
 
'''Use gubbins'''
 
'''Use gubbins'''
 
* >=media-libs/libglvnd-1.3.4 X
 
* >=media-libs/libglvnd-1.3.4 X
 +
 +
=== Fedora dependencies ===
 +
* git
 +
* cmake
 +
* ninja-build
 +
* pkg-config
 +
* ccache
 +
* clang
 +
* lld
 +
* llvm
 +
* llvm-devel
 +
* openssl-devel
 +
* nasm
 +
* python3-clang
 +
* python3-setuptools
 +
* squashfs-tools
 +
* squashfuse
 +
* erofs-fuse
 +
* erofs-utils
 +
* qt5-qtdeclarative-devel
 +
* qt5-qtquickcontrols
 +
* qt5-qtquickcontrols2
 +
 
== Build Configuration ==
 
== Build Configuration ==
 
* Ensure release mode is enabled
 
* Ensure release mode is enabled
Line 46: Line 75:
 
   mkdir Build
 
   mkdir Build
 
   cd Build
 
   cd Build
−
   CC=clang CXX=clang++ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release -DENABLE_LTO=True -DENABLE_LLD=True -DBUILD_TESTS=False -DENABLE_ASSERTIONS=False -G Ninja ..
+
   CC=clang CXX=clang++ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release -DUSE_LINKER=lld -DENABLE_LTO=True -DBUILD_TESTING=False -DENABLE_ASSERTIONS=False -G Ninja ..
 
   ninja
 
   ninja
  
Line 52: Line 81:
 
   sudo ninja install
 
   sudo ninja install
  
−
=== On AArch64 hosts ===
 
 
You can install a binfmt_misc handler for both 32bit and 64bit x86 execution directly from the environment.
 
You can install a binfmt_misc handler for both 32bit and 64bit x86 execution directly from the environment.
−
If you already have box86's 32bit binfmt_misc handler installed then I don't recommend installing FEX's until it is useful.
+
If you already have box86's 32bit binfmt_misc handler installed then make sure to uninstall their's first.
 
Make sure to have run install prior to this, otherwise binfmt_misc will install an old handler even if the executable has been updated.
 
Make sure to have run install prior to this, otherwise binfmt_misc will install an old handler even if the executable has been updated.
  
−
   sudo ninja binfmt_misc_32
+
   sudo ninja binfmt_misc
−
  sudo ninja binfmt_misc_64
 
  
−
'''binfmt_misc problems'''
+
=== Quirks ===
 +
 
 +
==== binfmt_misc problems ====
 
* Double check that binfmt_misc has worked
 
* Double check that binfmt_misc has worked
 
** `ls /usr/share/binfmts/FEX*` should return files
 
** `ls /usr/share/binfmts/FEX*` should return files
Line 67: Line 96:
 
*** If it doesn't exist then make sure your kernel has `CONFIG_BINFMT_MISC=y`
 
*** If it doesn't exist then make sure your kernel has `CONFIG_BINFMT_MISC=y`
 
*** If it still doesn't exist then make sure systemd isn't disabling it `systemctl enable binfmt-support`
 
*** If it still doesn't exist then make sure systemd isn't disabling it `systemctl enable binfmt-support`
 +
 +
==== DESTDIR quirks ====
 +
* When using DESTDIR, make sure the path is absolute instead of relative
 +
** FEX's thunks use subprojects because it needs to cross-compile
 +
** If DESTDIR is relative then the install paths of the subprojects go to the wrong location
 +
** Using $(pwd)/install works well
  
 
== Runtime Configuration ==
 
== Runtime Configuration ==
 
FEXConfig is the application to use for runtime configuration setup.
 
FEXConfig is the application to use for runtime configuration setup.
  
−
CTRL+SHIFT+O will open default "global" configuration.
+
CTLR+S saves the configuration.
−
 
 
−
CTLR+S saves it.
 
  
 
=== Things to ensure to set ===
 
=== Things to ensure to set ===
Line 82: Line 115:
 
* Silent Logging (Useful to get FEX information spam out of the way)
 
* Silent Logging (Useful to get FEX information spam out of the way)
 
* Block Size (500 is a good default. Optimization passes may break things though)
 
* Block Size (500 is a good default. Optimization passes may break things though)
−
* Multiblock: enabled (Can cause more stuttering)
 
  
−
More Details at: Follow the instructions here https://wiki.fex-emu.org/index.php/Development:Configuring_FEX
+
More Details at: Follow the instructions [[Development:Configuring_FEX|here]]
 +
 
 
== RootFS generation ==
 
== RootFS generation ==
−
AArch64 hosts require a rootfs for running applications
+
AArch64 hosts require a rootfs for running applications. FEX provides various x86 images that can be installed through [[Development:Setting_up_RootFS#Quick_Setup_with_FEXRootFSFetcher|FEXRootFSFetcher]]
−
Follow the instructions here https://wiki.fex-emu.org/index.php/Development:Setting_up_RootFS
 
  
−
== Installing Thunks ==
+
For more detailed instructions see [[Development:Setting_up_RootFS]]
−
Only if you want
 
  
−
Follow the instructions here: https://wiki.fex-emu.org/index.php/Development:Setting_up_Thunks
+
== Setting up library forwarding ==
  
−
Additional details here: https://github.com/FEX-Emu/FEX/blob/main/ThunkLibs/README.md
+
Follow the instructions [[Development:Setting_up_Library_Forwarding|here]].
  
 
== Binaries ==
 
== Binaries ==
−
* FEXLoader
+
* FEX
−
** This is useful for development purposes but is generally recommended against using.
+
** This is the emulator executable used to run x86 programs
−
** Allows passing arguments to FEX for configuration purposes, which can break under some execve situations
 
 
* FEXInterpreter
 
* FEXInterpreter
−
** This is a hardlink to FEXLoader which refuses to treat arguments as configuration options
+
** This is a (deprecated) alias for ''FEX'', provided for backwards compatibility
−
** Is recommended to use over FEXLoader; Using FEXConfig to set configuration
 
−
** Requires being a hardlink or executable copy, execve logic sees through a softlink
 
−
** Is the executable used for binfmt_misc for interpreters
 
 
* FEXConfig
 
* FEXConfig
−
** Used for setting configuration options from a GUI
+
** Used for configuring emulation from a Qt-based GUI
−
** Written using Dear ImGui
 
−
** Can load/save global configuration and application configuration files
 
−
** Application configuration files are compared against the executable filename
 
 
* FEXBash
 
* FEXBash
 
** Can be useful for starting a bash instance that is running under emulation
 
** Can be useful for starting a bash instance that is running under emulation
Line 116: Line 140:
 
** This is a mount daemon that will run in the background when you are using a squashfs based rootfs
 
** This is a mount daemon that will run in the background when you are using a squashfs based rootfs
 
** Usually one one instance open at any given moment
 
** Usually one one instance open at any given moment
−
** It usually closes when the FEXInterpreter exits, but not always. See the problems section in setting up a rootfs
+
** It usually closes when FEX exits, but not always. See the problems section in setting up a rootfs
 
*** Has a ten second timeout window in case a another instance of FEX opens and uses it.
 
*** Has a ten second timeout window in case a another instance of FEX opens and uses it.
  

Latest revision as of 14:01, 22 September 2025

Build dependencies

Debian/Ubuntu dependencies

  • git
  • cmake
  • ninja-build
  • pkgconf
  • ccache (Recommended if you're rebuilding constantly)
  • clang
  • llvm
  • lld (For ThinLTO)
  • binfmt-support (For AArch64 binfmt_misc support)
  • libssl-dev
  • python-setuptools (For build scripts)
  • g++-x86-64-linux-gnu (For building thunks)
  • libgcc-XX-dev-i386-cross (For building thunks, version should match your g++-x86-64-linux-gnu package)
  • libgcc-XX-dev-amd64-cross (For building thunks, version should match your g++-x86-64-linux-gnu package)
  • nasm (only if building tests)
  • python3-clang (for struct verifier)
  • libstdc++-12-dev-i386-cross (for struct verifier)
  • libstdc++-12-dev-amd64-cross (for struct verifier)
  • libstdc++-12-dev-arm64-cross (for struct verifier)
  • squashfs-tools (For squashfs rootfs support)
  • squashfuse (For mounting the squashfs)
  • libc-bin or glibc-tools (For unittests, needs catchsegv from this)
  • libc6-dev-i386-amd64-cross (For FEXLinuxTests)
  • lib32stdc++-XX-dev-amd64-cross (For FEXLinuxTests, version should match your g++-x86-64-linux-gnu package)
  • qtdeclarative5-dev (For GUI)
  • qml-module-qtquick-controls (For GUI)
  • qml-module-qtquick-controls2 (For GUI)
  • qml-module-qtquick-dialogs (For GUI)

Gentoo dependencies

  • dev-vcs/git
  • cmake
  • ninja
  • ccache
  • clang
  • lld
  • nasm

Use gubbins

  • >=media-libs/libglvnd-1.3.4 X

Fedora dependencies

  • git
  • cmake
  • ninja-build
  • pkg-config
  • ccache
  • clang
  • lld
  • llvm
  • llvm-devel
  • openssl-devel
  • nasm
  • python3-clang
  • python3-setuptools
  • squashfs-tools
  • squashfuse
  • erofs-fuse
  • erofs-utils
  • qt5-qtdeclarative-devel
  • qt5-qtquickcontrols
  • qt5-qtquickcontrols2

Build Configuration

  • Ensure release mode is enabled
  • Disable test building
  • Enable LTO in a release build
  • Enable LLD to make LTO builds faster
 git clone --recurse-submodules https://github.com/FEX-Emu/FEX.git
 cd FEX
 mkdir Build
 cd Build
 CC=clang CXX=clang++ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release -DUSE_LINKER=lld -DENABLE_LTO=True -DBUILD_TESTING=False -DENABLE_ASSERTIONS=False -G Ninja ..
 ninja

Installation

 sudo ninja install

You can install a binfmt_misc handler for both 32bit and 64bit x86 execution directly from the environment. If you already have box86's 32bit binfmt_misc handler installed then make sure to uninstall their's first. Make sure to have run install prior to this, otherwise binfmt_misc will install an old handler even if the executable has been updated. 

 sudo ninja binfmt_misc

Quirks

binfmt_misc problems

  • Double check that binfmt_misc has worked
    • `ls /usr/share/binfmts/FEX*` should return files
    • `ls /var/lib/binfmts/FEX*` should return files
    • `/proc/sys/fs/binfmt_misc/status` should exist
      • If it doesn't exist then make sure your kernel has `CONFIG_BINFMT_MISC=y`
      • If it still doesn't exist then make sure systemd isn't disabling it `systemctl enable binfmt-support`

DESTDIR quirks

  • When using DESTDIR, make sure the path is absolute instead of relative
    • FEX's thunks use subprojects because it needs to cross-compile
    • If DESTDIR is relative then the install paths of the subprojects go to the wrong location
    • Using $(pwd)/install works well

Runtime Configuration

FEXConfig is the application to use for runtime configuration setup.

CTLR+S saves the configuration.

Things to ensure to set

On AArch64 host, a rootfs path is mandatory, while it is optional on x86-64 host

  • Core: JIT
  • RootFS
  • Silent Logging (Useful to get FEX information spam out of the way)
  • Block Size (500 is a good default. Optimization passes may break things though)

More Details at: Follow the instructions here

RootFS generation

AArch64 hosts require a rootfs for running applications. FEX provides various x86 images that can be installed through FEXRootFSFetcher

For more detailed instructions see Development:Setting_up_RootFS

Setting up library forwarding

Follow the instructions here.

Binaries

  • FEX
    • This is the emulator executable used to run x86 programs
  • FEXInterpreter
    • This is a (deprecated) alias for FEX, provided for backwards compatibility
  • FEXConfig
    • Used for configuring emulation from a Qt-based GUI
  • FEXBash
    • Can be useful for starting a bash instance that is running under emulation
    • It's not a chroot! Don't use sudo inside of this environment!
  • FEXMountDaemon
    • This is a mount daemon that will run in the background when you are using a squashfs based rootfs
    • Usually one one instance open at any given moment
    • It usually closes when FEX exits, but not always. See the problems section in setting up a rootfs
      • Has a ten second timeout window in case a another instance of FEX opens and uses it.

Debug binaries

  • TestHarnessRunner
    • Used for running FEX's ASM unit tests
    • Runs some binary in a host x86_64 host environment or FEX and checks results
    • Useful for quickly creating ASM based unit tests
  • IRLoader
    • Used for running FEX's IR based unit tests
    • Only runs through FEX and checks the results
    • Minimal number of tests
  • UnitTestGenerator
    • This is supposed to be an x86-64 instruction generator
    • Has an understanding of x86-64 instruction encoding format
    • Generates hundreds of thousands of instructions
    • Used to be used with a lockstep runner to ensure correct behaviour
    • Largely unsupported, avoiding undefined behaviour is difficult and FEX doesn't need to match undefined behaviour
    • Lockstep hostrunner wasn't ever made to be bug free, hard to support
    • Doesn't ensure correct behaviour on AArch64 device
Retrieved from "https://wiki.fex-emu.com/index.php?title=Development:Setting_up_FEX&oldid=1447"