News:New OpenGL management in Funtoo

From Funtoo
Jump to navigation Jump to search

New OpenGL management in Funtoo

Funtoo is switching to an improved system for managing multiple OpenGL providers (Mesa/Xorg, AMD and NVIDIA). The update may involve blockers and file collisions.

By Mgorny / March 30, 2015

New OpenGL management

System principles

Proprietary video drivers such as x11-drivers/ati-drivers and x11-drivers/nvidia-drivers provide non-standard versions of core OpenGL system libraries, Xorg server modules and OpenGL headers. Those drivers do not work correctly with libraries provided by mesa/Xorg. Funtoo makes it possible to install those drivers by moving the colliding files into dedicated subtrees. Afterwards, user can use app-admin/eselect-opengl to switch between different library providers, therefore selecting the implementation matching video driver used.

Before, the system focused on exchanging the system libraries and headers by creating symlinks to the dedicated subtrees. This system caused a number of issues, most importantly:

  • the packages were built against currently selected OpenGL implementation, resulting in inconsistencies between binary packages created on different Funtoo systems and causing build failures on some packages requiring newer OpenGL headers than ones provided by the selected implementation,
  • the switching process was non-atomic and fragile. The user's system may have ended up with partially switched OpenGL implementation or dangling symlinks.

The new system provides a clear distinction between libraries and headers used at build-time, and libraries used at run-time. All packages are built consistently against the reference OpenGL implementation (mesa/Xorg), while user is allowed to override the implementation used at run-time. The overrides are done purely using system configuration.


The reference implementation (mesa/Xorg) packages install headers and libraries into standard system locations (/usr/include, /usr/lib*). The compiler and linker finds them using the usual rules and uses them.

The third-party OpenGL vendors install libraries and server extension modules into vendor-named subdirectories of /usr/lib*/opengl. Those files are not used directly.

app-admin/eselect-opengl is used to select OpenGL implementation used at run-time. The choice of implementation is controlled via dynamic linker configuration ( and Xorg server configuration. If the reference implementation is selected, the eselect module outputs null configuration that causes the linker and server to use the standard paths. If an another implementation is selected, the configuration prepends /usr/lib*/opengl paths to linker and server configuration, causing them to prefer the third-party libraries over reference.

Upgrade information

Automatic upgrade

Please note that the OpenGL subsystem upgrade is a lock-step update involving file collisions and blockers. This means that a few packages need to be upgraded consecutively during a single emerge run, and during that process the OpenGL support may become temporarily broken. If the upgrade is interrupted, your system may require manual attention.

For most of our users, a regular @world upgrade should be sufficient:

root # emerge -vDu @world

However, please make sure that FEATURES=collision-protect is not enabled during the world upgrade. It involves replacing some of externally created symlinks with package files. FEATURES=protect-owned (enabled by default) is fine. If you don't want to disable FEATURES=collision-protect world-upgrade-wide, please see below for manual upgrade method.

Manual upgrade

If one desires to perform the upgrade stand-alone (without upgrading other packages), he needs to pass all installed packages from the following list to emerge:

  • app-admin/eselect-opengl,
  • app-emulation/emul-linux-x86-opengl,
  • media-libs/mesa,
  • x11-base/xorg-server,
  • x11-drivers/ati-drivers,
  • x11-proto/glproto.

For example, the following command may be used to commence a manual update:

root # FEATURES=-collision-protect emerge -1nu app-admin/eselect-opengl media-libs/mesa x11-base/xorg-server x11-proto/glproto


  1. FEATURES=-collision-protect will ensure that Portage can replace the symlinks created by old versions of eselect-opengl with real libraries.
  2. -1 will ensure that none of intermediate packages end up in @world, causing issues in the future,
  3. -n will prevent Portage from unnecessarily rebuilding packages that were upgraded already,
  4. -u will cause Portage to upgrade the remaining packages.