Difference between revisions of "Development:Setting up Library Forwarding"

From FEX-Emu Wiki
Jump to navigation Jump to search
 
Line 1: Line 1:
 +
Library forwarding is a FEX feature that allows redirecting calls to common libraries OpenGL or Vulkan from their emulated x86 builds to their native ARM64 counterparts installed on the host system. This saves emulation overhead and dramatically improves performance for some applications.
 +
 
= Build instructions =
 
= Build instructions =
−
== Build dependencies ==
+
 
 +
Install the dependencies below and enable the <code>BUILD_THUNKS</code> CMake option:
 +
* <code>cmake -DBUILD_THUNKS=True .</code>
 +
 
 +
If your distribution is not listed below, there is a generic fallback that requires Nix or a [https://lix.systems/install/#on-any-other-linuxmacos-system compatible alternative].
 +
 
 +
=== Ubuntu dependencies ===
 
* g++-x86-64-linux-gnu (For building thunks)
 
* g++-x86-64-linux-gnu (For building thunks)
 
* pkg-config
 
* pkg-config
Line 25: Line 33:
 
* xorg-x11-server-devel
 
* xorg-x11-server-devel
  
−
== Setting CMake to build thunks ==
+
=== Generic Nix fallback ===
−
Pass in to CMake the option to enable thunk building.
+
 
−
* -DBUILD_THUNKS=True
+
With Nix installed, run <code>../Data/nix/cmake_enable_libfwd.sh</code> from your build folder. This will set up a cross-compiler, install the required dependencies, and enable the required CMake option.
  
 
= Configuration =
 
= Configuration =
  
 
FEXConfig can be used to enable/disable individual libraries.
 
FEXConfig can be used to enable/disable individual libraries.
 +
 +
=== Per-app overrides ===
 +
* Filename in '''$HOME/.fex-emu/AppConfig/Balatro.exe.json'''
 +
* Change the filename as necessary for your application
 +
 +
  {
 +
    "ThunksDB": {
 +
      "GL": 1,
 +
      "Vulkan": 1
 +
    }
 +
  }
  
 
= Advanced configuration =
 
= Advanced configuration =
−
== FEX thunk options ==
+
=== FEX environment variables and command-line arguments ===
 
* FEX_THUNKHOSTLIBS, -t <Thunk Host Libs Path>, --thunkhostlibs=<Thunk Host Libs path>, JSON: '''ThunkHostLibs:<Path>'''
 
* FEX_THUNKHOSTLIBS, -t <Thunk Host Libs Path>, --thunkhostlibs=<Thunk Host Libs path>, JSON: '''ThunkHostLibs:<Path>'''
 
** Folder to find the host-side thunking libraries.
 
** Folder to find the host-side thunking libraries.
Line 45: Line 64:
 
** If the filename isn't a path then FEX will search for the file in '''$HOME/.fex-emu/ThunkConfigs/'''
 
** If the filename isn't a path then FEX will search for the file in '''$HOME/.fex-emu/ThunkConfigs/'''
  
−
== How to use Thunks ==
+
===Overriding paths for library wrappers ===
 
You can can set the three configuration options to custom paths
 
You can can set the three configuration options to custom paths
  
Line 52: Line 71:
 
** Overriding these to another location is useful for application specific hacks if necessary
 
** Overriding these to another location is useful for application specific hacks if necessary
  
−
== Thunks Database format ==
+
=== ThunksDB.json schema ===
−
FEX provides a ThunksDB.json file which allows the user to describe a thunk mapping. '''$prefix/share/fex-emu/ThunksDB.json'''
+
FEX provides a ThunksDB.json file which allows the user to describe a thunk mapping. '''$prefix/share/fex-emu/ThunksDB.json'''. Normally this does not need to be modified, but an overlay to the default database can be provided at '''$HOME/.fex-emu/ThunksDB.json'''.
  
−
The user can also provide a '''$HOME/.fex-emu/ThunksDB.json''' which will overlay the system installed path
+
Example:
−
 
 
−
This allows the user to configure the thunk file mapping once, since it is unlikely to change between applications. The user can also mix and match ThunksDB and regular thunks configuration if a complex configuration is necessary.
 
−
 
 
−
* ThunksDB.json example
 
 
   {
 
   {
 
       "DB": {
 
       "DB": {
Line 73: Line 88:
 
       }
 
       }
 
   }
 
   }
−
 
−
Look at the FEX provided library for a real implementation, or just use the provided configuration.
 
−
 
−
Once the user has a viable ThunksDB provided, now configure FEX with a ThunkConfig filepath with the application thunk configuration.
 
−
 
−
This thunks configuration file can now enable Thunk definitions using the user defined names.
 
−
 
−
== Per-app overrides ==
 
−
* Filename in '''$HOME/.fex-emu/AppConfig/Balatro.exe.json'''
 
−
* Change the filename as necessary for your application
 
−
 
−
  {
 
−
    "ThunksDB": {
 
−
      "GL": 1,
 
−
      "Vulkan": 1
 
−
    }
 
−
  }
 
−
 
−
= Further notes =
 
−
== Limitations and problems ==
 
−
* For 32-bit applications, libGL is the only library that can use the host variant currently
 
  
 
[[Category:Development]]
 
[[Category:Development]]

Latest revision as of 10:05, 14 July 2025

Library forwarding is a FEX feature that allows redirecting calls to common libraries OpenGL or Vulkan from their emulated x86 builds to their native ARM64 counterparts installed on the host system. This saves emulation overhead and dramatically improves performance for some applications.

Build instructions

Install the dependencies below and enable the BUILD_THUNKS CMake option:

  • cmake -DBUILD_THUNKS=True .

If your distribution is not listed below, there is a generic fallback that requires Nix or a compatible alternative.

Ubuntu dependencies

  • g++-x86-64-linux-gnu (For building thunks)
  • pkg-config
  • libclang-dev
  • libssl-dev
  • Development packages for thunked libraries:
    • libdrm-dev
    • libxcb-present-dev
    • libxcb-dri2-0-dev
    • libxcb-dri3-dev
    • libxcb-glx0-dev
    • libxcb-shm0-dev
    • libxshmfence-dev

Fedora dependencies

  • libXext-devel
  • libXfixes-devel
  • libXrender-devel
  • libXrandr-devel
  • alsa-lib-devel
  • libxcb-devel
  • libxshmfence-devel
  • libdrm-devel
  • xorg-x11-server-devel

Generic Nix fallback

With Nix installed, run ../Data/nix/cmake_enable_libfwd.sh from your build folder. This will set up a cross-compiler, install the required dependencies, and enable the required CMake option.

Configuration

FEXConfig can be used to enable/disable individual libraries.

Per-app overrides

  • Filename in $HOME/.fex-emu/AppConfig/Balatro.exe.json
  • Change the filename as necessary for your application
 {
   "ThunksDB": {
     "GL": 1,
     "Vulkan": 1
   }
 }

Advanced configuration

FEX environment variables and command-line arguments

  • FEX_THUNKHOSTLIBS, -t <Thunk Host Libs Path>, --thunkhostlibs=<Thunk Host Libs path>, JSON: ThunkHostLibs:<Path>
    • Folder to find the host-side thunking libraries.
    • FEX by default installs these files to: /usr/lib/fex-emu/HostThunks/
  • FEX_THUNKGUESTLIBS, -j <Thunk Host Libs Path>, --thunkguestlibs=<Thunk Host Libs path>, JSON: ThunkGuestLibs:<Path>
    • Folder to find the guest-side thunking libraries.
    • FEX by default installs these files to: /usr/share/fex-emu/GuestThunks/
  • FEX_THUNKCONFIG, -k <Thunk Config json path>, --thunkconfig=<Thunk Config json path>, JSON: ThunkConfig:<Path>
    • A json file specifying where to overlay the thunks.
    • If the filename isn't a path then FEX will search for the file in $HOME/.fex-emu/ThunkConfigs/

Overriding paths for library wrappers

You can can set the three configuration options to custom paths

  • The user can likely set ThunkHostLibs and ThunkGuestLibs to the global install path
    • Unless these are set in the ThunkConfig file, these will be unused
    • Overriding these to another location is useful for application specific hacks if necessary

ThunksDB.json schema

FEX provides a ThunksDB.json file which allows the user to describe a thunk mapping. $prefix/share/fex-emu/ThunksDB.json. Normally this does not need to be modified, but an overlay to the default database can be provided at $HOME/.fex-emu/ThunksDB.json.

Example: 

 {
     "DB": {
       "<User Defined Name>": {
         "Library": "<Guest Library Name>.so",
         "Depends": [
           "<Other User Defined Name>"
         ],
         "Overlay": [
           "<System Library Path to library>"
         ]
       }
     }
 }
Retrieved from "https://wiki.fex-emu.com/index.php?title=Development:Setting_up_Library_Forwarding&oldid=1389"